Package com.atlassian.connect.spring

Interface AtlassianHostRestClients

  • public interface AtlassianHostRestClients
    A helper class for obtaining preconfigured RestTemplates to make authenticated requests to Atlassian hosts.

    JWT

    To make requests using JWT, the add-on must specify the authentication type jwt in its add-on descriptor.

    To obtain a RestTemplate using JWT authentication, use authenticatedAsAddon(): 

     @Autowired
 private AtlassianHostRestClients restClients;

 public void makeRequest() {
     restClients.authenticatedAsAddon().getForObject(...);
 }

    OAuth 2.0 - JWT Bearer Token

    To make requests using OAuth 2.0, the add-on must request the ACT_AS_USER scope in its add-on descriptor.

    To obtain a RestTemplate using OAuth 2.0 authentication, use authenticatedAsHostActor() or authenticatedAs(AtlassianHostUser): 

     @Autowired
 private AtlassianHostRestClients restClients;

 public void makeRequest() {
     restClients.authenticatedAsHostActor().getForObject(...);
 }
    Since:
    1.1.0

    • Method Detail

      • authenticatedAsAddon

        RestTemplate authenticatedAsAddon()
        Returns a RestTemplate for making requests to Atlassian hosts using JWT authentication. The principal of the request is the add-on.

        During processing of a request from an Atlassian host, relative URLs can be used to make requests to the current host.

        When a request is made to an absolute URL, the request URL is used to resolve the destination Atlassian host. If no host matches, the request is not signed.

        Returns:
        a REST client for JWT authentication
        See Also:
        authenticatedAsAddon(AtlassianHost)

      • authenticatedAsAddon

        RestTemplate authenticatedAsAddon​(AtlassianHost host)
        Returns a RestTemplate for making requests to Atlassian hosts using JWT authentication. The principal of the request is the add-on.

        Relative URLs can be used to make requests to the given host.

        When a request is made to an absolute URL, the URL must match the base URL of the given host.

        Parameters:
        host - the host to which the request should be made
        Returns:
        a REST client for JWT authentication
        See Also:
        authenticatedAsAddon()

      • createJwt

        String createJwt​(HttpMethod method,
                 URI uri)
        Creates a JSON Web Token for use when the RestTemplate provided by authenticatedAsAddon() cannot be used to make requests to Atlassian hosts, such as when using Jersey. 
         WebTarget webTarget = ClientBuilder.newClient().target(host.getBaseUrl()).path(...);
 String jwt = atlassianHostRestClients.createJwt(HttpMethod.GET, webTarget.getUri());
 Response response = webTarget.request().header("Authorization", "JWT " + jwt).get();

        NOTE: Whenever possible, use of authenticatedAsAddon() is recommended over use of this method.

        The created JWT is restricted for use with the given HTTP method and request URL.

        The request URL is used to resolve the destination Atlassian host. If no host matches, an IllegalArgumentException is thrown.

        Parameters:
        method - the HTTP method of the request to be authenticated
        uri - the absolute URL of the request to be authenticated
        Returns:
        a JWT for use when authenticating as the add-on
        Throws:
        IllegalArgumentException - if the URL did not have the base URL of any installed host
        Since:
        1.3.0
        See Also:
        authenticatedAsAddon(), authenticatedAsAddon(AtlassianHost)

      • authenticatedAsHostActor

        RestTemplate authenticatedAsHostActor()
        Returns a RestTemplate for making requests to the currently authenticated Atlassian host using OAuth 2.0 JWT Bearer Token authentication. The principal of the request is the currently authenticated user.

        On first invocation, OAuth2JwtTokenService will request an access token from Atlassian's authorization server, and the token will be stored for further use. Once the token has expired, a new token will be fetched transparently. Additionally, the RestTemplate for a particular host user is cached between requests using Spring Caching.

        Returns:
        a REST client for OAuth 2.0 JWT Bearer Token authentication
        See Also:
        authenticatedAs(AtlassianHostUser)

      • authenticatedAs

        RestTemplate authenticatedAs​(AtlassianHostUser hostUser)
        Returns a RestTemplate for making requests to the given Atlassian host using OAuth 2.0 JWT Bearer Token authentication. The principal of the request is the given user.

        On first invocation, OAuth2JwtTokenService will request an access token from Atlassian's authorization server, and the token will be stored for further use. Once the token has expired, a new token will be fetched transparently. Additionally, the RestTemplate for a particular host user is cached between requests using Spring Caching.

        Parameters:
        hostUser - the host to which the request should be made, and the user principal
        Returns:
        a REST client for OAuth 2.0 JWT Bearer Token authentication
        See Also:
        authenticatedAsHostActor()

      • getAccessToken

        OAuth2AccessToken getAccessToken​(AtlassianHostUser hostUser)
        Get the access token for use when authenticating as the host user authenticatedAs(AtlassianHostUser).

        For example, you may explicitly get the access token and add it to the Authorization header when making a request, such as when using Jersey. 

        
     String token = atlassianHostRestClients.getAccessToken(hostUser).getTokenValue();
     requestContext.getHeaders().add("Authorization", String.format("Bearer %s", token));

        NOTE: You do not need to explicitly get and set access token if you are using authenticatedAsHostActor() or authenticatedAs(AtlassianHostUser), as it is already handled for you.

        Parameters:
        hostUser - the host to which the request should be made, and the user principal
        Returns:
        an access token for use when authenticating as the host user

      • authenticatedAsAddon

        RestTemplate authenticatedAsAddon​(AddonAuthenticationType auth)
        Returns a RestTemplate for making authenticated requests to Atlassian hosts. The principal of the request is the add-on. Applicable for Connect-on-Forge apps only.

        During processing of a request from an Atlassian host, relative URLs can be used to make requests to the current host.

        When a request is made to an absolute URL, the request URL is used to resolve the destination Atlassian host. If no host matches, the request is not signed.

        When AddonAuthenticationType is set to "jwt", the returned RestTemplate can only make request using JWT authentication, and if AddonAuthenticationType is "oauth2" it can make request with OAuth 2.0 client credentials flow when your app has opted in oauth2 - in case your app has not opted in oauth2 this method will throw an exception.

        Parameters:
        auth - an authentication type to be used for making authenticated requests to Atlassian hosts.
        Returns:
        the REST template for making authenticated requests to Atlassian hosts.

      • authenticatedAsAddon

        RestTemplate authenticatedAsAddon​(AtlassianHost host,
                                  AddonAuthenticationType auth)
        Returns a RestTemplate for making authenticated requests to Atlassian hosts for a specified. The principal of the request is the add-on. Applicable for Connect-on-Forge apps only.

        Relative URLs can be used to make requests to the given host.

        When a request is made to an absolute URL, the URL must match the base URL of the given host. Available options for the auth argument are: "jwt", and "oauth2".

        When AddonAuthenticationType is set to "jwt", the returned RestTemplate can only make request using JWT authentication, and if AddonAuthenticationType is "oauth2" it can make request with OAuth 2.0 client credentials flow when your app has opted in oauth2 - in case your app has not opted in oauth2 this method will throw an exception.

        Parameters:
        host - the host to which the request should be made
        auth - an authentication type to be used for making authenticated requests to Atlassian hosts.
        Returns:
        the REST template for making authenticated requests to Atlassian hosts.

      • isClientCredentialsAvailable

        boolean isClientCredentialsAvailable​(AtlassianHost host)
        Checks whether the AddonAuthenticationType is enabled by the AtlassianHost. Applicable for Connect-on-Forge apps only.
        Parameters:
        host - the host on which the check is performed.
        Returns:
        a boolean indicating whether the app can make requests to the tenant using OAuth 2.0 auth