addOnUISdk.app.oauth

Provides access to the OAuth API methods needed for implementing the user authorization with OAuth 2.0 use case. Be sure to check out the code samples as well for more extensive examples of using this workflow.

data-slots=text

data-variant=info
Runtime: This API runs in the iframe runtime (addOnUISdk). See the Add-on Architecture Guide for the dual-runtime model.

Methods

authorize()

Authorize a user using OAuth 2.0 PKCE workflow.

Signature

authorize(request: AuthorizationRequest): Promise<AuthorizationResponse>

Parameters

Name
Type
Description
request
object
AuthorizationRequest object payload with parameters to be used in the authorization workflow.

AuthorizationRequest

Name
Type
Description
authorizationUrl
string
OAuth provider's authorization URL.
clientId
string
Client identifier of the application created at the OAuth provider.
scope
string
Scope to control the application's access.
codeChallenge
string
Code challenge used in Authorization Code Exchange.
additionalParameters?
Map<string, string>
Additional parameters, specific to an OAuth provider which are required in the Authorization URL as query string parameters.
windowSize?
{ width: number; height: number }
The authorization window size in the form of an object containing the desired width and height as a number. <br/><br/>NOTE: The minimum (and default) values for windowSize are 480 x 480. The maximum allowed values are 800 x (screen height).

Return Value

A resolved Promise with the AuthorizationResponse object containing a one-time authorization code which can be used to obtain an access token.

AuthorizationResponse

Name
Type
Description
id
string
Unique identifier for the authorization request.
code
string
OAuth 2.0 generated authorization code which can be used once to obtain an access token and a refresh token.
redirectUri
string
URL where the user is redirected to after authorization. This is the default URL owned by Adobe and it is this URL which needs to be used to obtain access_token.
result
AuthorizationResult
An AuthorizationResult payload which denotes either success or failure. In the event of a "FAILED" status reported by the OAuth provider during authorization, the value of this property is an object, in the form of {[failure_title]: "failure_description"}, and for all other statuses the value of description is a string.

authorizeWithOwnRedirect()

Initiate the OAuth 2.0 PKCE authorization workflow by opening the user sign-in window. After authorization, the user is redirected to the add-on developer provided URL.

Signature

authorizeWithOwnRedirect(request: AuthorizeWithOwnRedirectRequest): Promise<AuthorizationResult>

Parameters

Name
Type
Description
request
object
AuthorizeWithOwnRedirectRequest object payload with parameters to be used in the authorization workflow.

AuthorizeWithOwnRedirectRequest

Name
Type
Description
authorizationUrl
string
OAuth provider's authorization URL.
clientId
string
Client identifier of the application created at the OAuth provider.
scope
string
Scope to control the application's access.
codeChallenge
string
Code challenge used in Authorization Code Exchange.
additionalParameters?
Map<string, string>
Additional parameters, specific to an OAuth provider which are required in the Authorization URL as query string parameters.
windowSize?
{ width: number; height: number }
The authorization window size in the form of an object containing the desired width and height as a number. <br/><br/>NOTE: The minimum (and default) values for windowSize are 480 x 480. The maximum allowed values are 800 x (screen height).
redirectUri
string
URL where the user is redirected to after successful or failed authorization. Hosting and handling redirects to this URL should be managed by the caller.
state
string
A value which is preserved in the request, and replayed back as a query string parameter in the redirectUri. Although the primary reason for using the state parameter is to mitigate CSRF attacks, it can also be used to encode any other information.

Return Value

A resolved Promise with the AuthorizationResult object, which contains a status and a description, which will either be a string or an object. In the event of a FAILED status reported by the OAuth provider during authorization, the value of this property is an object, in the form of {[failure_title]: "failure_description"}, and for all other statuses, the value of description is a string.

AuthorizationResult

Name
Type
Description
status
AuthorizationStatus
Status representing success or failure in the authorization workflow.
description
string or object
Description about the success or failure in the authorization workflow In the event of a "FAILED" status reported by the OAuth provider during authorization, the value of this property is an object, in the form of {[failure_title]: "failure_description"}. While for all other statuses the value of this property is a string

AuthorizationStatus

Each of the statuses returned below is the exact string value (e.g., SUCCESS = "SUCCESS").

Name
Type
Description
SUCCESS
string
Authorization completed successfully. Expected result for the authorize() method.
POPUP_OPENED
string
The popup was opened. Expected result for the authorizeWithOwnRedirect() method.
POPUP_BLOCKED
string
The popup was blocked. Add allow-popups to your manifest.json sandbox permissions.
POPUP_CLOSED
string
The user closed the popup before completing authorization.
POPUP_TIMEOUT
string
The popup timed out.
FAILED
string
The authorization workflow failed.
IFRAME_LOAD_FAILED
string
The OAuth iframe failed to load.
RESTRICTED_CLIENT_ID
string
The client ID is restricted and not permitted for this context.

Errors

The table below describes the possible error statuses returned when using the OAuth API, with a description of the scenario that will return them.

<br/>

Error Status
Description
POPUP_BLOCKED
The window for authorization was blocked.
POPUP_TIMEOUT
The window for authorization was timed out.
FAILED
<Failure object returned by the OAuth provider when authorization fails.>