com.amazon.simplesignin.linktoken

Class LinkTokenV1Provider

java.lang.Object

com.amazon.simplesignin.linktoken.LinkTokenV1Provider

All Implemented Interfaces:

ILinkTokenProvider<GenerateLinkTokenV1Request>

public class LinkTokenV1Provider
extends Object
implements ILinkTokenProvider<GenerateLinkTokenV1Request>

Default implementation of ILinkTokenProvider APIs for the schema LinkTokenSchema.LINK_1_0.

This implementation encodes link token claims as a JSON string, further encrypts and represents it as a JWE (See https://tools.ietf.org/html/rfc7516).

It uses the algorithm "A128GCMKW" (Key wrapping with AES GCM using 128-bit key) for encrypting the secret key and "A128GCM" (AES GCM using 128-bit key) for content encryption.

JSON payload is constructed as follows. It includes all standard fields that are defined in the token specification and any additional custom fields specified by the partners.

 {
   # Amazon user id
   "amznUserId": "amzn1.ssi.did.abc123",

   # Partner user id
   "userId": "dev.xyz123",

   # LinkVerificationKey (Base64/X.509 encoded EC public key)
   "vKey": "acxVS5B0wVnnL+ODs..",

   # Fields whose names start with prefix "c." are custom fields specified by
   # partners during token generation. Token decoding logic takes care of
   # removing the prefix before exposing constituent fields.
   "c.iat": "1593526058876",
   "c.issuer": "dev"

   # More custom fields
   ...
   ...
 }
 

Constructor Summary

Constructors

Constructor and Description
LinkTokenV1Provider(@NonNull ILinkTokenCryptoKeyProvider linkTokenCryptoKeyProvider, @NonNull IAppStorePublicKeyProvider appStorePublicKeyProvider)
LinkTokenV1Provider(@NonNull ILinkTokenCryptoKeyProvider linkTokenCryptoKeyProvider, @NonNull IAppStorePublicKeyProvider appStorePublicKeyProvider, @NonNull LinkKeyPairProvider linkKeyPairProvider)

Method Summary

Modifier and Type	Method and Description
LinkTokenContainer	generateLinkToken(@NonNull GenerateLinkTokenV1Request request) Generates a new LinkToken.
LinkTokenSchema	getTokenSchema() Returns link token schema supported by the implementation.
LinkTokenInfo	validateLinkToken(@NonNull LinkToken linkToken, @NonNull IRequestContext requestContext) Validates the given LinkToken.
LinkTokenInfo	validateLinkToken(@NonNull SSITokenInfo ssiTokenInfo, @NonNull IRequestContext requestContext) Validates the LinkToken unwrapped from an SSI token.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LinkTokenV1Provider

public LinkTokenV1Provider(@NonNull
                           @NonNull ILinkTokenCryptoKeyProvider linkTokenCryptoKeyProvider,
                           @NonNull
                           @NonNull IAppStorePublicKeyProvider appStorePublicKeyProvider)

LinkTokenV1Provider

public LinkTokenV1Provider(@NonNull
                           @NonNull ILinkTokenCryptoKeyProvider linkTokenCryptoKeyProvider,
                           @NonNull
                           @NonNull IAppStorePublicKeyProvider appStorePublicKeyProvider,
                           @NonNull
                           @NonNull LinkKeyPairProvider linkKeyPairProvider)

Method Detail

generateLinkToken

public LinkTokenContainer generateLinkToken(@NonNull
                                            @NonNull GenerateLinkTokenV1Request request)
                                     throws TokenException

Description copied from interface: ILinkTokenProvider

Generates a new LinkToken.

Specified by:

generateLinkToken in interface ILinkTokenProvider<GenerateLinkTokenV1Request>

Parameters:

request - IGenerateLinkTokenRequest Object holding details required for generating link token.

Returns:

LinkTokenContainer.

Throws:

TokenException - is thrown to indicate unexpected errors encountered while generating token.

validateLinkToken

public LinkTokenInfo validateLinkToken(@NonNull
                                       @NonNull LinkToken linkToken,
                                       @NonNull
                                       @NonNull IRequestContext requestContext)
                                throws TokenException

Description copied from interface: ILinkTokenProvider

Validates the given LinkToken.

NOTE that for validating link token during the authentication flow, another variant of this method ILinkTokenProvider.validateLinkToken(SSITokenInfo, IRequestContext) must be used. This method doesn't enforce that a link token being validated is obtained as part of an SSI token. SSI token is essential to verify that account linking is still valid at this moment and link token is used for authentication on intended devices. Link token obtained through any other means might represent a stale or invalid account linking and doesn't provide authorization to be used for customer authentication.

LinkToken validation entails the following:

1. Token is decrypted successfully.
2. Token signature is verified successfully to ensure the authenticity of issuer and integrity of token contents.
3. Token contains all required fields.

Specified by:

validateLinkToken in interface ILinkTokenProvider<GenerateLinkTokenV1Request>

Parameters:

linkToken - LinkToken Link token to decode.

requestContext - IRequestContext object which holds additional contextual information about the request.

Returns:

LinkTokenInfo object containing information decoded from the link token.

Throws:

InvalidTokenException - is thrown for malformed tokens that cannot be decoded.

TokenException - is thrown to indicate other unexpected errors encountered while decoding token.

validateLinkToken

public LinkTokenInfo validateLinkToken(@NonNull
                                       @NonNull SSITokenInfo ssiTokenInfo,
                                       @NonNull
                                       @NonNull IRequestContext requestContext)
                                throws TokenException

Description copied from interface: ILinkTokenProvider

Validates the LinkToken unwrapped from an SSI token.

In addition to the validation steps done in ILinkTokenProvider.validateLinkToken(LinkToken, IRequestContext), this method verifies that the token is being used within its scope by matching Amazon user id from the enclosing SSI token (which represents the current active user on the device) with Amazon user id which link token has been scoped to.

Specified by:

validateLinkToken in interface ILinkTokenProvider<GenerateLinkTokenV1Request>

Parameters:

ssiTokenInfo - Decoded information from an SSI token.

requestContext - IRequestContext object which holds additional contextual information about the request.

Returns:

LinkTokenInfo object containing information decoded from the link token.

Throws:

InvalidTokenException - is thrown when the token cannot be decoded when it's malformed.

InvalidTokenUsageException - is thrown when the token usage is found to be not within the approved scope.

TokenException - is thrown to indicate other unexpected errors encountered while decoding token.

getTokenSchema

public LinkTokenSchema getTokenSchema()

Description copied from interface: ILinkTokenProvider

Returns link token schema supported by the implementation.

Specified by:

getTokenSchema in interface ILinkTokenProvider<GenerateLinkTokenV1Request>

Returns:

LinkTokenSchema