public class

AmazonAuthorizationManager

extends Object
java.lang.Object
   ↳ com.amazon.identity.auth.device.authorization.api.AmazonAuthorizationManager

Class Overview

This class is used by Login with Amazon clients to authorize users and retrieve tokens and profile data.

All methods with the Future<Bundle> and/or the AuthorizationListener/APIListener will return the results on a non-UI thread.

AuthorizationListener:
The AuthorizationListener interface is used by the authorize(String[], Bundle, AuthorizationListener) method to return results asynchronously. AmazonAuthorizationManager calls AuthorizationListener methods on a new (worker) thread created by the SDK. These methods include:

APIListener:
The APIListener interface is used by the getToken(String[], APIListener) and getProfile(APIListener) methods to return results in the same manner as AuthorizationListener. APIListener does not include the onCancel method.

Future<Bundle>:
Some methods return a Future object. Using the Future allows the developer to use the method synchronously. Calling get() will cause the flow to block until results are returned via a Bundle. Calling Future.get() on a non-UI thread is recommended in order to eliminate the likely risk of a ANR. The Bundle returned in the Future.get() call will have one additional parameter to help a developer determine what type of response it is (Success,Error,Cancel). The key for the value is FUTURE. This will return an enum of type AuthzConstants.FUTURE_TYPE. After determining the success or failure of the method, you can extract the data from the Bundle as if it was passed to onSuccess(Bundle) or onCancel(Bundle). If the method returned an error, you can extract the error using Bundle.getParcelable(String)} using the AUTH_ERROR_EXECEPTION. key.

APIKey:
The "APIKey" is a token meant to encode claims about a native application(e.g. Android, iOS) that can be used to verify the identity of the application without requiring a remote service call. In addition to the app identity, these tokens can carry other claims about the application as required. For example, a list of permissions granted to the application. The contents of the tokens are encoded and then digitally signed. The APIKey must be available for the SDK to obtain from the calling application.

  • It can be in the manifest for the application as a meta-data tag with the key "AmazonAPIKey" example: <meta-data android:name="AmazonAPIKey" android:value="@string/my_api_key" />
  • It can also be placed in a file in the application's asset folder. The filename must be: "api_key.txt"

AuthError:
Error Object to help SDK developers determine what actions to take.
Each AuthEror has a category(AuthError.ERROR_CATEGORY) and type(AuthError.ERROR_TYPE)

  • ACTION - Some action is required by the calling application in order to address this issue Consult the method documentation for specific error types (AuthError.ERROR_TYPE) and what actions are required.
  • NETWORK - Depending on the error type and the cause, you may want to retry the operation or alert the user.
  • INTERNAL - Please report errors in these categories to our SDK support team and provide logs. The type and cause may provide additional information in diagnosing the error.
  • UNKNOWN - Please report errors in these categories to our SDK support team and provide logs. The type and cause may provide additional information in diagnosing the error.
  • BAD_REQUEST - This is not currently used by this SDK.

{@version 2.0.2 }

See Also

Summary

Public Constructors
AmazonAuthorizationManager(Context context, Bundle options)
Constructor
Public Methods
Future<Bundle> authorize(String[] scopes, Bundle options, AuthorizationListener listener)
This method is deprecated. Use authorize(AuthorizeRequest).
Future<Bundle> clearAuthorizationState(APIListener listener)
This method is deprecated. Use signOut(Context, Listener)
String getAppId()
This method returns the application Id.
String getAppVariantId()
This method returns the application variant Id.
String getClientId()
This method returns the client ID that is encoded within the API key used by your app to integrate with the Login with Amazon Android SDK.
Future<Bundle> getProfile(APIListener listener)
This method is deprecated. Use fetch(Context, Listener)
String getRedirectUri()
If you are requesting the authorization code in the response to the authorize API, you must call this API in the onSuccess handler of your AuthorizationListener to get the redirect_uri parameter which is required to do server-side exchange of code with access token and refresh token.{@since 2.0.1 }
Future<Bundle> getToken(String[] scopes, APIListener listener)
This method is deprecated. Use getToken(Context, Scope[], Listener).
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public AmazonAuthorizationManager (Context context, Bundle options)

Constructor

Parameters
context - The context of the calling application
options - Can be null. Currently unused
Throws
IllegalArgumentException if context or clientId is null OR if the ApiKey is invalid or missing

Public Methods

public Future<Bundle> authorize (String[] scopes, Bundle options, AuthorizationListener listener)

This method is deprecated.
Use authorize(AuthorizeRequest).

This method handles requesting authorization (using OAuth 2.0) for a client for a specified scope. This results in a token that is used to access Amazon services/resources. By default, authorize uses a native browser to present a page that prompts the user to login and authorize the application. If SSO is available, an Amazon-hosted WebView will be used.

If the APIKey is incorrect, onError(AuthError) will be called with a ERROR_ACCESS_DENIED

onError(AuthError) will be called for the following OAuth-related errors::

Any other possible OAuth-related errors will be encapsulated in a ERROR_SERVER_REPSONSE

onCancel(Bundle) - only detects if the user clicks on "cancel" button during the authorization. Dismissal of the browser before authorization is complete will not be detected.{@since 1.0}

Parameters
scopes An array of scopes representing the permissions requested by this application. Login with Amazon currently supports "profile" and "postal_code". You must request "profile" at the same time you request "postal_code".
options Can be null - used for optional settings via Bundle
listener AuthorizationListener interface that is invoked with a response from the method. Can be null if the Future is used.
Returns
  • Returns Future. See Class level javadocs for more info - Can be null. Currently unused
Throws
IllegalArgumentException if the scopes are null or empty.
See Also

public Future<Bundle> clearAuthorizationState (APIListener listener)

This method is deprecated.
Use signOut(Context, Listener)

This method removes any local authorization for the current user from this application. Your application must call authorize(String[], Bundle, AuthorizationListener) again to be able to get tokens or profile data.

If the APIKey is incorrect, onError(AuthError) will be called with a ERROR_ACCESS_DENIED

{@since 1.0}

Parameters
listener APIListener interface that is invoked with a response from the method. Can be null if the Future is used.
Returns
  • Future See Class level javadocs for more info.
Throws
AuthError ERROR_THREAD if the thread is interrupted or ERROR_ACCESS_DENIED

public String getAppId ()

This method returns the application Id. This is the id that was used to register the application and that will be bundled along with the binary.{@since 1.0 }

Returns
  • String - The "application ID" representing the application family this application belongs to. This is the appId used for all authorization flows by the SDK. Returns null if the SDK could not get the appId.
Throws
AuthError In case of failure (ERROR_ACCESS_DENIED)

public String getAppVariantId ()

This method returns the application variant Id. This is the variant id that was used to register the application and that will be bundled along with the binary.{@since 1.0 }

Returns
  • String - The "application variant ID" representing the application specifically. by the SDK. Returns null if the SDK could not get the appId.
Throws
AuthError In case of failure (ERROR_ACCESS_DENIED)

public String getClientId ()

This method returns the client ID that is encoded within the API key used by your app to integrate with the Login with Amazon Android SDK. This client Id is your client identifier that the Login with Amazon Android SDK uses to authorize customers for your application. If you are requesting the authorization code in the response to the authorize API, you must call this API in the onSuccess handler of your AuthorizationListener in order to get the client ID, which is a parameter required to do the exchange of code for access token and refresh token.{@since 2.0.1 }

Returns
  • String - The "clientId" associated with the API key
Throws
AuthError In case of failure (ERROR_ACCESS_DENIED)

public Future<Bundle> getProfile (APIListener listener)

This method is deprecated.
Use fetch(Context, Listener)

This method requests basic profile information for a user (using OAuth 2.0) for the scopes requested in the last call to authorize(String[], Bundle, AuthorizationListener).

The authorize(String[], Bundle, AuthorizationListener) method must have been called once prior to this call so that a user can authorize the app. If the app has restarted since the last authorize call, getProfile may still succeed using the cached credentials.

If the APIKey is incorrect, AuthorizationListener.onError will be called with a ERROR_ACCESS_DENIED

APIListener.onError will be called for the following OAuth-related errors:

Any other possible OAuth-related errors will be encapsulated in a ERROR_SERVER_REPSONSE

If the method completes successfully, it calls onSuccess(Bundle) with the profile embedded as a Bundle inside the result Bundle. Use PROFILE.val to retrieve it.
The PROFILE bundle contains the following strings:

  • Name: key = NAME.val, type = String
  • Email: key = EMAIL.val, type = String
  • User Id: key = USER_ID.val, type = String
  • Postal Code: key = POSTAL_CODE.val, type = String
The first three values are provided if the "profile" scope is requested, the last value is only provided if the "postal_code" scope is also requested.{@since 1.0}

Parameters
listener AuthorizationListener interface that is invoked with a response from the API.
Returns
  • Future for blocking calls. See Class level javadocs for more info.
Throws
IllegalArgumentException if the scopes are null or empty

public String getRedirectUri ()

If you are requesting the authorization code in the response to the authorize API, you must call this API in the onSuccess handler of your AuthorizationListener to get the redirect_uri parameter which is required to do server-side exchange of code with access token and refresh token.{@since 2.0.1 }

Returns
  • String - "redirect_uri" which is of the format "amzn://"
Throws
AuthError In case of failure (ERROR_ACCESS_DENIED)

public Future<Bundle> getToken (String[] scopes, APIListener listener)

This method is deprecated.
Use getToken(Context, Scope[], Listener).

This method handles requesting an authorization token (using OAuth 2.0) for the specified scopes for the given package.

The authorize(String[], Bundle, AuthorizationListener) method must have been called successfully with the same scopes, and the user must have granted consent to those scopes once, prior to this call, in order to get a token. If the app has restarted since the last authorize call, getToken may still succeed using the cached credentials.

If the APIKey is incorrect, onError(AuthError) will be called with a ERROR_ACCESS_DENIED

APIListener.onError will be called for the following OAuth-related errors:

Any other possible OAuth-related errors will be encapsulated in a ERROR_SERVER_REPSONSE

onSuccess Bundle Keys:
key = TOKEN.val,
variable type = String
{@since 1.0}

Parameters
scopes An array of scopes representing the permissions requested by this application. Login with Amazon currently supports "profile" and "postal_code".
listener APIListener interface that is invoked with a response from the method. Can be null if the Future is used.
Returns
  • Future See Class level javadocs for more info.
Throws
IllegalArgumentException if the scopes are null or empty