Interface AtlassianHostRestClients
RestTemplate
s 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 Summary
Modifier and TypeMethodDescriptionauthenticatedAs
(AtlassianHostUser hostUser) Returns aRestTemplate
for making requests to the given Atlassian host using OAuth 2.0 JWT Bearer Token authentication.Returns aRestTemplate
for making requests to Atlassian hosts using JWT authentication.Returns aRestTemplate
for making authenticated requests to Atlassian hosts.Returns aRestTemplate
for making requests to Atlassian hosts using JWT authentication.authenticatedAsAddon
(AtlassianHost host, AddonAuthenticationType auth) Returns aRestTemplate
for making authenticated requests to Atlassian hosts for a specified.Returns aRestTemplate
for making requests to the currently authenticated Atlassian host using OAuth 2.0 JWT Bearer Token authentication.createJwt
(HttpMethod method, URI uri) Creates a JSON Web Token for use when theRestTemplate
provided byauthenticatedAsAddon()
cannot be used to make requests to Atlassian hosts, such as when using Jersey.getAccessToken
(AtlassianHostUser hostUser) Get the access token for use when authenticating as the host userauthenticatedAs(AtlassianHostUser)
.boolean
Checks whether theAddonAuthenticationType
is enabled by the AtlassianHost.
-
Method Details
-
authenticatedAsAddon
RestTemplate authenticatedAsAddon()Returns aRestTemplate
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
Returns aRestTemplate
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:
-
createJwt
Creates a JSON Web Token for use when theRestTemplate
provided byauthenticatedAsAddon()
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 authenticateduri
- 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:
-
authenticatedAsHostActor
RestTemplate authenticatedAsHostActor()Returns aRestTemplate
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, theRestTemplate
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
Returns aRestTemplate
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, theRestTemplate
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:
-
getAccessToken
Get the access token for use when authenticating as the host userauthenticatedAs(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()
orauthenticatedAs(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
Returns aRestTemplate
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 returnedRestTemplate
can only make request using JWT authentication, and ifAddonAuthenticationType
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
Returns aRestTemplate
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 returnedRestTemplate
can only make request using JWT authentication, and ifAddonAuthenticationType
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 madeauth
- 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
Checks whether theAddonAuthenticationType
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
-