Overview

DCP SSO Sub Authenticator's provide applications the ability to fetch their own credentials by "exchanging" the centrally managed credentials for credentials in their own eco-system. Sub Authenticators should only be written if you do not use ADP Authentication (kindle DMS credentials) or OAuth Authentication or if your application used one on Otter.

Amazon SSO Sub Authenticator Design

Components of the System

• Amazon AccountAuthenticator -- The main AccountAuthenticator that is registered with the {@link android.accounts.AccountManager AccountManager} When a new Amazon customer account is added, this component registers the device with the Amazon Device Platform and obtains a set of tokens that can later authenticate the device to external 'exchange token' requests.
• Sub-Authenticator -- "Sub-authenticators" are plug-ins to the Amazon AccountAuthenticator, in much the same way as the Authenticator is a plug in to the {@link android.accounts.AccountManager AccountManager}. Each sub authenticator declares a set of (application specific) token names that it is responsible for. When a request comes in to the main Amazon AccountAuthenticator for that token, the request is passed off to the sub-authenticator for processing. The sub-authenticator can fulfill this request by issuing web requests to the appropriate 'exchange token' webservice.
• Device Registration UI -- This component is responsible for prompting the user for their amazon username / password. It is expected that this UI is implemented by exactly one package installed on the system. This component is not part of the Device Client Platform because the exact requirements of this UI may vary from device to device.

Using the pre-built DMS Sub-Authenticator or creating a Sub-Authenticator

An Amazon application can either use the DMS sub-authenticator that SSO provides or implement its own sub-authenticator.Ê The DMS sub-authenticator approach is recommended and should be used if you are registering with DMS. If you are not registering with DMS, then you should create a sub-authenticator.

• For apps registering or wish to register with DMS:

  An application that is registering with DMS should use the pre-built DMS Sub-Authenticator. The token types fetched by the DMS sub authenticator are "tokens.adp_token", "tokens.private_key", "tokens.storeAuthCookie"(x-fsn cookie used for the app, only received if a device capability is set), "tokens.device_type", and "tokens.dsn". These token types are prefixed by the package name of the Amazon application. For example, if the package name of an application is 'com.amazon.ssoclient', then the token name of its adp_token will be 'com.amazon.ssoclient.tokens.adp_token'. DMS sub-authenticator provides implementation for getting and updating a token of the four types above upon Amazon AccountAuthenticator's request.

To specify that an application is using DMS sub-authenticator, it simply needs to have an XML resource named exactly dms_sub_authenticator with the following format:

		     <account-sub-authenticator type="DMS" accountType="com.amazon.account">
		        <device-type>DMS_DEVICE_TYPE</device-type>
		     </account-sub-authenticator>
		

However, if an Amazon application is using the DMS sub-authenticator, but needs to implement any app-specific clean up action before the device is deregistered, please see {@link com.amazon.dcp.sso.AbstractDMSSubAuthenticatorCleanUpHandler AbstractDMSSubAuthenticatorCleanUpHandler} for more details.


Note: How we populate app-specific information in the exchange token request:

1. Device Type: The default value is the device type that you provide in dms_sub_authenticator.xml
2. Version number: We get the version code of your package from Android Package Manager
• For apps NOT registering with DMS:

  An application that's not registering with DMS first needs to implement a service that can exchange a user's DMS credentials for that user's credentials in your ecosystem; then implement a sub-authenticator that tells SSO what service we should call to exchange the DMS tokens, and how to interpret the response. For information on implementing a sub-authenticator, see {@link com.amazon.dcp.sso.AbstractSubAuthenticator AbstractSubAuthenticator}.

SSOClient sample application

• How to run the sample using the DMS sub-authenticator
  • For apps that do NOT need to do any clean-up action on de-registration:

    By default, the sample application is configured to work for this case, so you do not need to do any additional work. However, you should pay attention to the xml resource named dms_sub_authenticator (in the folder res/xml/) This is the xml file (as mentioned above) that you need to have in your application to let us know what the application's device type is and that you are using the DMS sub-authenticator.

  • For apps that need to do some clean-up action on de-registration: Generally, you will need to:
    1. Create an xml resource named dms_sub_authenticator.xml (same as the case above, this is done in the sample application)
    2. Implement AbstractDMSSubAuthenticatorCleanUpHandler. (This is done in the sample application, see DMSSubAuthenticatorCleanupHandler.java)
    3. Implement a bound service (This is done in the sample application, see DMSSubAuthenticatorCleanupHandlerService.java)
    4. Register the clean-up handler in the Manifest. This is the service (.DMSSubAuthenticatorCleanUpHandlerService) that has been commented out in the ssoclient AndroidManifest. You need to uncomment it to register the clean-up handler. NOTE: Do NOT uncomment the .SampleSubAuthenticatorService.

• How to run the sample using the sample sub-authenticator: Generally, you will need to:
  1. Create an xml resource named sub_authenticator.xml (This is done in the the sample application, see sub_authenticator.xml in ssoclient/res/xml/)
  2. Implement a sub-authenticator (This is done in the the sample application, see SampleSubAuthenticator.java)
  3. Implement a bound service (This is done in the the sample application, see SampleSubAuthenticatorService.java)
  4. Register the sub-authenticator in the Manifest. This is the service (.SampleSubAuthenticatorService) that has been commented out in the ssoclient AndroidManifest. You need to uncomment it to register the sub-authenticator. NOTE: Do NOT uncomment the .DMSSubAuthenticatorCleanUpHandlerService.