Class adobeDPS-OAuthRedirectService

Extends:: adobeDPS-OAuthRedirectService -> adobeDPS-Service -> adobeDPS-Class
Platforms:: iOS, Windows

Service for handling OAuth2.0 authorization responses using HTTP redirection.
Accessible from adobeDPS.oauthRedirectService

Constructor

adobeDPS-OAuthRedirectService()

[inner] Create an instance of the OAuthRedirectService.

Static Fields

	Field	Defined By
	adobeDPS-OAuthRedirectService.instance The singleton of the OAuthRedirectService.	OAuthRedirectService

Fields

	Field	Defined By
	clientId : String The client Id assigned to the connected app for the authorization host.	OAuthRedirectService
	redirectURI : String The redirect URI used by the authorization server to send responses back to the application.	OAuthRedirectService
	oauthData : Object The authorization data object associated with the authorization server (host) for the active session.	OAuthRedirectService
	OAuthRedirectServiceErrorCodes : Object The supported error codes as an enum object	OAuthRedirectService

Methods

	Method	Defined By
	initAuthData(authSettings:Object, successCB:Function, errorCB:Function) Initialises the authorization session and retrieves the cached auth data from native keychain into the internal oauthData	OAuthRedirectService
	startListening(responseCB:Function, successCB:Function, errorCB:Function) Starts listening for authorization server response in preparation for an OAuth authorization request.	OAuthRedirectService
	stopListening(successCB:Function, errorCB:Function) Stops listening for authorization server response.	OAuthRedirectService
	updateAuthData(authData:Object, successCB:Function, errorCB:Function) Updates the cached authorization data for the current session (identified by clientId).	OAuthRedirectService
	resetAuthData(successCB:Function, errorCB:Function) Resets the cached authorization data for the current session (identified by clientId).	OAuthRedirectService
	authorize(requestURI:String, useTitle:Boolean, persistCookies:Boolean, successCB:Function, errorCB:Function) This is a Windows-specific API that replaces the function of the startListening() and stopListening() APIs.	OAuthRedirectService
	toString() Gets the string representation of this instance.	Class

Class Detail

adobeDPS-OAuthRedirectService()

[inner] Create an instance of the OAuthRedirectService.
This is an internal constructor and shouldn't be called by regular users.

Static Field Details

adobeDPS-OAuthRedirectService.instance

The singleton of the OAuthRedirectService.

Platforms:: iOS, Windows

Field Details

clientId : String

The client Id assigned to the connected app for the authorization host. It conforms to the OAuth spec for client_id field.

Platforms:: iOS, Windows

redirectURI : String

The redirect URI used by the authorization server to send responses back to the application. It conforms to the OAuth spec for redirect_uri field.

Platforms:: iOS, Windows

oauthData : Object

The authorization data object associated with the authorization server (host) for the active session. It contains key:value pairs of authorization data conforming to the OAuth spec. It represents a union of the response fields from the authorization server for initial authorization request and subsequent token refresh requests.

Platforms:: iOS, Windows

OAuthRedirectServiceErrorCodes : Object

The supported error codes as an enum object

See:: adobeDPS-OAuthRedirectServiceErrorCodes
Platforms:: iOS, Windows

Method Details

initAuthData(authSettings:Object, successCB:Function, errorCB:Function)

Initialises the authorization session and retrieves the cached auth data from native keychain into the internal oauthData

Parameters
authSettings	Object	The authorization settings objects with the following format: { authURL: String, clientId: String, redirectURI: String} where: authURL - The authorization URL used in the REST API for authorization grant request. It cannot be undefined, null or empty. clientId - The client Id assigned to the app for a specific service provider. It conforms to the OAuth spec requirements for the client_id field. It cannot be undefined, null or empty. redirectURI - The callback URI used by the authorization server to return the result to the app. It conforms to the OAuth spec requirements for the redirect_uri field). It cannot be undefined, null or empty. If authSettings or any of its properties is invalid the errorCB() is called with INVALID_ARGUMENTS error, if errorCB is defined. If errorCB is undefined, the 'Invalid error handler' exception is thrown.
successCB	Function	The callback function that handles the success of the request. This function can use the oauthData property to access the tokens needed. It cannot be undefined or null. Signature: successCB()
errorCB	Function	The error callback to handle the error codes below. It cannot be undefined or null. Signature: errorCB(error) INVALID_ARGUMENTS - when the API is used with invalid arguments. OPERATION_IN_PROGRESS - when another authorization session is in progress (startListening is use) or the previous API request did not complete.

Throws:: Error If the errorCB is invalid
Platforms:: iOS, Windows

startListening(responseCB:Function, successCB:Function, errorCB:Function)

Starts listening for authorization server response in preparation for an OAuth authorization request. It registers a response callback which is invoked when the server response with redirectURI scheme is received or server times out.

Parameters
responseCB	Function	The callback function that handles the authorization server response object or a timeout message. This handler should be able to differentiate between success or error responses based on the object content according to OAuth spec. It cannot be undefined or null. Signature responseCB(data)
successCB	Function	The success callback indicating the request is successful and the viewer is ready for server data. It cannot be undefined or null. The user should use this function to send the authorization request to the server. Signature: successCB()
errorCB	Function	The error callback to handle the error codes below. It cannot be undefined or null. Signature: errorCB(error) INVALID_ARGUMENTS - when the API is used with invalid arguments. INVALID_AUTH_SESSION - when the clientId property of the adobeDPS.oauthRedirectService is invalid. It requires a call to initAuthData. OPERATION_IN_PROGRESS - when another authorization session is in progress (startListening is use) or the previous API request did not complete.

Throws:: Error If the errorCB is invalid
Platforms:: iOS

stopListening(successCB:Function, errorCB:Function)

Stops listening for authorization server response. This will cancel the pending listening request for the for the current session (identified by clientId).

Parameters
successCB	Function	The success callback indicating the request is successful and the viewer is ready for server data. It cannot be undefined or null. Signature successCB()
errorCB	Function	The error callback to handle the error codes below. It cannot be undefined or null. Signature: errorCB(error) INVALID_ARGUMENTS - when the API is used with invalid arguments. INVALID_AUTH_SESSION - when the clientId property of the adobeDPS.oauthRedirectService is invalid. It requires a call to initAuthData. OPERATION_IN_PROGRESS - when another authorization session with different clientId is in progress (startListening is use) or the previous API request did not complete.

Throws:: Error If the errorCB is invalid
Platforms:: iOS

updateAuthData(authData:Object, successCB:Function, errorCB:Function)

Updates the cached authorization data for the current session (identified by clientId). This API is needed for OAuth flows that require refreshing the access token. The cached auth data (oauthData property) is updated with the fields from the authData. The authData object will be merged into the existing oauthData property object where fields existing on both objects will be updated with values from authData and new fields will be added.

Parameters
authData	Object	The new authorization data obtained from the token endpoint with refreshed access token and optionally a new refresh token. It cannot be undefined, null or empty.
successCB	Function	The callback function indicating the success of the request. The handler can use oauthData to access the new tokens. It cannot be undefined or null. Signature successCB()
errorCB	Function	The error callback to handle the error codes below. It cannot be undefined or null. Signature: errorCB(error) INVALID_ARGUMENTS - when the API is used with invalid arguments. INVALID_AUTH_SESSION - when the clientId property of the adobeDPS.oauthRedirectService is invalid. It requires a call to initAuthData. OPERATION_IN_PROGRESS - when another authorization session is in progress (startListening is use) or the previous API request did not complete.

Throws:: Error If the errorCB is invalid
Platforms:: iOS, Windows

resetAuthData(successCB:Function, errorCB:Function)

Resets the cached authorization data for the current session (identified by clientId). As a result the oauthData property object is set to null and the native counterpart is removed. Additionally this logs out the user from the authorization server by deleting all the relevant cookies for the current session's main domain. Note: Multiple authorization sessions with the same main domain will share the cookies for that domain. Thus logging out a user for host.domain.com will also invalidate the login status for other same domain authorization sessions (anyhost.domain.com, anyhost.anysubdomain.domain.com).

Parameters
successCB	Function	The callback function that handles the success of the request. It cannot be undefined or null. Signature: successCB()
errorCB	Function	The error callback to handle the error codes below. It cannot be undefined or null. Signature: errorCB(error) INVALID_ARGUMENTS - when the API is used with invalid arguments. INVALID_AUTH_SESSION - when the clientId property of the adobeDPS.oauthRedirectService is invalid. It requires a call to initAuthData. OPERATION_IN_PROGRESS - when another authorization session is in progress (startListening is use) or the previous API request did not complete.

Throws:: Error If the errorCB is invalid
Platforms:: iOS, Windows

authorize(requestURI:String, useTitle:Boolean, persistCookies:Boolean, successCB:Function, errorCB:Function)

This is a Windows-specific API that replaces the function of the startListening() and stopListening() APIs. It is only available on Windows 8 or later.

authorize() creates an instance of Windows Web Authentication Broker. It is designed by Microsoft to provide support for authentication flows such as SSO (Single Sign-On) and variants that pass back tokens back in the window title string.

Windows Web Authentication Broker looks like a web view that is created on top of the calling application. It contains UI elements that allow the user to cancel the login process and return to the application. Once authentication is finished, the Windows Web Authentication Broker closes itself and returns the data that the server sent to the redirectURI back to the calling application.

authorize() handles internally the functions of startListening() and stopListening(). Once authorize() finishes, successCB() is called and then the authorization data can be retrieved from the oathData instance variable of OauthRedirectService. The JavaScript workflow otherwise stays the same. initAuthData(), resetAuthData() and updateAuthData() are still used on the Windows platform.

Parameters
requestURI	String	The full URI to call the authorization host with. The URI should contain parameters required by the host such as redirect_uri, response_type and so forth. Please note that the redirectURI parameter given to initAuthData() is used for capturing the response from authorization host.
useTitle	Boolean	By default the OS authorization API expects that the authorization host returns authorization data in a query string sent to redirectURI. If the authorization host sends data in the window title string instead, set useTitle to true.
persistCookies	Boolean	If set true, cookies received from authorization host are preserved over app launches by the OS. This is commonly desired when SSO (single sign-on) is used. On Windows, resetAuthData() is unable to clear cookies. If persistCookies is set true, the user may be permanently signed in as long as the cookies are valid. If persistCookies is set true, the redirectURI parameter that is used when calling initAuthData() must be of the form ms-app://SID, where SID matches the SID of the Windows app. See Understanding and debugging the web authentication broker workflow for more documentation.
successCB	Function	The callback function that handles the success of the request. It cannot be undefined or null. After successCB() is called then the authorization data from the host can be retrieved from the oauthData instance variable of the OauthRedirectService object. Signature: successCB()
errorCB	Function	The error callback to handle the error codes below. It cannot be undefined or null. Signature: errorCB(error) INVALID_ARGUMENTS - when the API is used with invalid arguments. INVALID_AUTH_SESSION - when the clientId property of the oauthRedirectService is invalid. It requires a call to initAuthData(). OPERATION_IN_PROGRESS - when another authorization session is in progress or the previous API request did not complete.

Throws:: Error If the errorCB is invalid
Platforms:: Windows

Adobe DPS - Library and Store SDK 2.32

Class adobeDPS-OAuthRedirectService

Constructor

Static Fields

Fields

Methods