Skip to content

Latest commit

 

History

History
105 lines (72 loc) · 14 KB

app-oauth.md

File metadata and controls

105 lines (72 loc) · 14 KB

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 The popup was blocked. (Add allow-popups permission to your manifest.json sandbox permissions)
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.>