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.
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. 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 | string or object | 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. 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 name as a string (ie: SUCCESS = "SUCCESS")
| Name | Type | Description |
|---|---|---|
SUCCESS | string | Successful authorization this is the expected result for the Authorize method) |
POPUP_OPENED | string | The popup was opened (this is the expected result for the AuthorizeWithOwnRedirect method) |
POPUP_BLOCKED | string | |
POPUP_TIMEOUT | string | The popup timed out. |
FAILED | string | The authorization workflow failed |
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.
| 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.> |
