Token Mechanism

The Simple Sign-in solution involves two types of tokens.

• Link token. Issue a link token to authenticate the identity of a user within your system. A link token is proof of linkage with an Amazon user. The link token might contain additional contextual information, such as the time when account was linked.
• Simple Sign-in (SSI) token. A transient token issued each time by Amazon for every new sign-in request. The SSI token is used to securely transmit the link token back to the app. It encapsulates a link token within it and it's used to attest to the validity of the underlying link token and authorize its use for customer authentication.

• Link token advantages
• Link token specification
• Lifecycle of a link token
• The SSI token specification
• SSI tokens and secure authentication
• Cryptographic keys used
• Customer authentication using a link token

Link token advantages

Using a link token has the following advantages.

• Provides a strong assertion that the user has been authenticated by you and that approval for account linking has been obtained. Plain identifiers are not adequate to prove user authentication or authorization.
• Allows you the ability to off-load the heavy work of storing and keeping track of the association between user identities on Amazon while still being the authority to grant account linking.
• Allows you to capture more contextual information about account linking, such as the source device info, as part of the token itself which they can consume during token validation. Otherwise, you would need to build a custom solution to maintain this data.

Link token specification

The version of the link token specification is identified using the string literal LINK-TOKEN-1.0.

• A link token must include an identifier which is used to uniquely identify the user of an app within your identity management system.
• A link token must be scoped to the linked Amazon user so that its usage can be restricted to devices that are registered to that particular Amazon user. This is achieved by embedding the Amazon user ID (AmazonUserId) in the token. The Amazon user ID is exposed to apps through the getUserAndLinks() method in the Simple Sign-in client APIs. For details, see SSI Client APIs.
• The link token must include the link verification key, an elliptic curve (EC) public key used in checking the authenticity and integrity of the corresponding SSI tokens. For details about the link verification key, see Cryptographic keys used.
• You can include additional contextual fields, such as the time when the account linking was set up, or metadata about the source app or device from where the account linking was initiated.
• To maintain the secrecy of data elements encoded inside the token, encrypt the token payload. The cryptographic keys used for encryption and decryption operations are managed by you and should not be shared with Amazon.
• To verify the integrity and authenticity of a token during token validation, you must digitally sign the token. The cryptographic keys used for digital signatures are managed by app owners and don't need to be shared with Amazon.
• Link tokens don't have an expiration. The validity of a link token is tied to the current status of the user's account linking.
• A link token is an opaque string from Amazon's perspective. The specification doesn't prescribe any particular encoding scheme for the construction of tokens.

Lifecycle of a link token

Link tokens don't have an expiration. Their usage is restricted through short-lived SSI tokens. Link tokens are valid in the system until users initiate an action which invalidates account linking. Customers can remove account linking by turning off Simple Sign-in, either globally at their account level or specific to particular apps. These settings can be managed from the on-device settings menu, or remotely from Amazon's website. When customers initiate unlinking from Amazon's end, the linkage is marked as removed and the corresponding link token is destroyed on the Simple Sign-in server.

The SSI token specification

The SSI token specification is identified using the string literal SSI-TOKEN-1.0.

• The SSI token is generated by Amazon and is used to securely transmit link tokens from Amazon to your systems while authenticating a user on an app using a linked account.
• The SSI token encapsulates a link token within itself and additionally includes the following data to restrict the scope of usage:
  • Directed ID. Identifies the Amazon user currently active on the device.
  • Timestamp fields. Used to specify the window of time for which the token is valid. The duration of this window is set to Five minutes from the time the token is issued. This is typically long enough for the ongoing sign-in request to complete and accounts for potential clock differential between Amazon's servers and your servers.
• The token is unencrypted.
• The token is signed by Amazon using a link signing key, which is issued by you along with a link token when account linking is set up.

The token is encoded as a signed JSON Web Token (JWT). The fields are explained below.

Header

{
  "alg": "ES384",
  "typ": "JWT",
  "schema": "SSI-TOKEN-1.0"
}

Payload

{  "iss": "https://ssi.amazon.com", //Identifies the Amazon SSI service as the token issuer
  "aud": "<PARTNER_VENDOR_ID>", //Indicates the recipient of this token. A unique vendor ID assigned by Amazon Appstore Developer Console during developer onboarding is used.
  "linkInfo": {
     "linkToken": {
         "schema": "LINK-TOKEN-1.0",
         "token": "<LINK_TOKEN>" //Link token issued by the developer.
     },
     "amazonUser": "<AMZN_USER_ID>", //Developer-scoped directed ID, representing the user's Amazon account which is active on the origin Amazon device. Developers match this value with the Amazon user ID captured inside the link token to verify that the link token is used on intended devices only.
     "partnerUser": "<PARTNER_USER_ID>", //Directed ID representing the user account provided by the developer during account linking.
  },
  "nbf": 1589366574, //Token validity - Begin Time - Seconds since epoch
  "iat": 1589366874, //Token issue time - Seconds since epoch
  "exp": 1589367174, //Token validity - End Time - Seconds since epoch
  "jti": "<JWT_ID>" //Unique identifier for the token
 }

The token is serialized as follows.

• unsignedToken = base64UrlEncode(header) + '.' + base64UrlEncode(payload)
• signature
  • Digital signature algorithm: ECDSA using P-384 and SHA-384
  • Signing input: unsignedToken
  • Signing key: linkSigningKey
• token = unsignedToken + '.' + base64UrlEncode(signature)

SSI tokens and secure authentication

• A link token represents a linkage with the identities involved. Therefore, it remains valid as long as account linking is valid. The SSI token serves as an authorization token which asserts that account linking is still valid and is used to approve the usage of the corresponding link token to authenticate the user.
• Because the SSI token is transient, it limits the usage of the underlying link token to a short time window. For every new sign-in attempt using a linked account, a fresh SSI token must be acquired.

Cryptographic keys used

This section explains how cryptographic keys are used in token generation and validation. It also specifies the expectations for key ownership and management.

• AppStoreKeyPair: A 2048-bit RSA key pair automatically provisioned by Amazon Appstore for every app as part of the app submission process. The public key is shared with you through the Appstore Developer Console. To find the public key, log into the Developer Console. On the Upload Your App File screen, in the Additional information section, click View public key. Use this key to encrypt payloads that need to be securely transmitted to Amazon. The AppStoreKeyPair once assigned, remains unchanged for the entire lifetime of an app and won't change when a new version of the app is submitted.
• LinkTokenEncryptionKey and LinkTokenDecryptionKey: Used to encrypt and decrypt link tokens respectively. You can use either symmetric or asymmetric key encryption. These keys are managed internally by you and are not shared with Amazon.
• LinkTokenSigningKey and LinkTokenVerificationKey: Used to sign and verify the authenticity and integrity of link tokens respectively. You can either use a digital signature with an asymmetric key pair or a MAC generated address using a secret key. You manage the keys internally and do not share them with Amazon.

• LinkKeyPair is an elliptic curve (ECC) key pair (Supported Curve: secp384r1/NIST P-384) generated by you as part of an account linking setup. A distinct key pair must be generated for each linked account. LinkSigningKey (the private key part of LinkKeyPair) and LinkVerificationKey (the public key part of LinkKeyPair) are used to sign and verify the SSI tokens. These keys are used as follows.
  • As part of the account linking setup:
    • LinkSigningKey is encrypted using the public key of the app specific AppStoreKeyPair and the corresponding LinkVerificationKey is added as a field inside LinkToken.
    • Include both LinkToken and the encrypted LinkSigningKey in the request to establish account linking.
    • Amazon decrypts LinkSigningKey using the corresponding private key of AppStoreKeyPair and persists the decrypted key as part of the account linking object on the SSI server.
  • When linked accounts are queried by the app later for signing in customers through Simple Sign-in:
    • Amazon generates an SSI token for each linked account and signs it using the corresponding LinkSigningKey.
    • Validate the SSI token signature using the corresponding LinkVerificationKey which is obtained by decrypting and decoding LinkToken.

Customer authentication using a link token

To authenticate a customer using a linked account in the Simple Sign-in flow, apps will use the link token shared with Amazon when account linking. When apps query for linked accounts, Amazon wraps link tokens inside signed SSI tokens to prove that account linking is still valid.

Note: Only link tokens obtained as part of an SSI token must be used for authentication since other link tokens are not sufficient to prove the current status of account linking. Those obtained as part of an SSI token also verify whether the link token is used within its scope, such as on the intended devices.

The following is a summary of the steps for authentication:

• Check if the SSI token is a validly signed JWT, conforming to the published schema.
• Check if the SSI token is used within its validity window (ssiToken.payload.nbf <= currentTime < ssiToken.payload.exp)
• Unwrap the SSI token to extract the link token from its payload.
• Validate the link token by doing the following:
  • Decrypt the token
  • Verify the token signature
  • Decode the token fields
• Verify the SSI token signature using LinkVerificationKey extracted from the link token.
• Verify link token permissions by checking whether the Amazon user which the link token is scoped to matches the current active Amazon user. Do this by comparing the Amazon user ID field encoded inside the link token with the Amazon user ID field present in the SSI token (ssiToken.payload>linkInfo>amazonUser).
• If all previous steps are completed successfully, complete authentication using the linked account the link token represents. In case of any failures, abort the Simple Sign-in flow and fallback to other standard sign-in options.

Last updated: Oct 02, 2023