- Generate link tokens to issue to Amazon during account linking setup.
- Validate and decode SSI tokens during new sign-in requests to your app.
- Validate and decode link tokens during new sign-in requests to your app; a link token is extracted by decoding an SSI token.
- Generate SSI tokens to mimic the behavior of the Amazon SSI server in your internal tests.
Generate link tokens
TheLinkTokenV1Provider class provides the methods to generate link tokens. The constructor used to instantiate LinkTokenV1Provider takes two input parameters - instances of your implementations of the ILinkTokenCryptoKeyProvider and IAppStorePublicKeyProvider interfaces. These implementations include the logic to retrieve cryptographic keys from your key store.
The logic to retrieve cryptographic keys and the public key pair is inside the ILinkTokenCryptoKeyProvider and IAppStorePublicKeyProvider interfaces. Use the following code to create a LinkTokenV1Provider object, which is used to generate link tokens.
Generate and cache your key
The following sample implementation ofILinkTokenCryptoKeyProvider generates and caches an AES 128-bit key during instantiation of the class and provides this key any time it’s requested. In a real implementation, you must add logic to fetch the keys from a secure store where your app keys are pre-created and stored.
Generate static key pairs
The following two code samples used to implementIAppStorePublicKeyProvider, generate a static key pair locally and expose the public key component of the generated key pair through its getPublicKey() method. In the actual implementation, you must add logic to fetch key material from a secure store where the public key assigned by Appstore is stored.
Generate a link token
Now, you can generate a link token by invoking thegenerateLinkToken() method. The request object of type GenerateLinkTokenV1Request contains the details to be encoded inside the token.
LinkTokenContainer object returned as an output contains the following data.
- token: The link token payload. This is the plain string that captures the identity of a user within your system. It’s used as proof of linkage with an Amazon user.
- tokenSchema: The link token schema,
LINK-TOKEN-1.0. - linkSigningKeyEncrypted: The link signing key. An EC private key for which the SSI tokens for this link should be signed. Encrypted using your Appstore public key.
Validate and decode SSI token
To validate and decode the SSI token, use thedecodeAndVerifyToken() method of the SSITokenV1Validator class. This method verifies the signature of the SSI token and ensures the token isn’t expired.
linkTokenV1Provider- ALinkTokenV1Providerobject passed into the constructor ofSSITokenV1Validator. This is the same instance ofLinkTokenV1Providerthat you set up for link token generation.requestContext- An instance of your implementation of theIRequestContextinterface. This object contains the details needed for your implementation ofILinkTokenCryptoKeyProviderto get to the appropriate decryption key, to decrypt the link token, and to extract a link verification key. A link verification key is used to verify the SSI token signature embedded inside it.ssiToken- TheSSITokenobject that you want to decode and verify.
SSI tokens
SSI tokens have the formatSSIToken(token=<xxxxx.yyyyy.zzzzz>, schema=SSI-TOKEN-1.0). The token here is a JSON Web Token (JWT), which typically looks like “xxxxx.yyyyy.zzzzz”. Where xxxxx is the Base64Url encoded header, yyyyy is the Base64Url encoded payload, and zzzzz is the computed signature of xxxxx and yyyyy, with an app specific private key.
A decoded SSI token has the following format:
Validate and decode the link token
Once an SSI token is successfully validated, validate the wrapped link token and extract customer identification details from the token. Use thevalidateLinkToken() method of LinkTokenV1Provider to achieve this.
validateLinkToken() method used in this example are:
ssiTokenInfo- An instance of theSSITokenInfotype, which contains the details decoded from an SSI Token.requestContext- An instance of your implementation of theIRequestContextinterface. This object contains the details needed in your implementation ofILinkTokenCryptoKeyProviderto get the decryption key used to decrypt the link token.
Generate an SSI token
You don’t need to generate SSI tokens yourself for production apps, but you might want to generate tokens for testing purposes. You can generate SSI tokens with the SSI token library, following these steps:- Generate a link token by following the steps described in Generate a link token.
-
Assume for your test app you have access to both private and public keys of the Appstore key pair. Although, for a production app, you’ll have access to the public key only. Implement the
IAppStorePrivateKeyProviderinterface to enable access to the private key to decrypt the link signing key, which is issued along with the link token and encrypted using the Appstore public key. The following sample implementation of theIAppStorePrivateKeyProviderinterface generates a static key pair locally and exposes the private key through itsgetPrivateKey()method. Use both code samples. -
Decrypt the link signing key using a
LinkSigningKeyDecryptorobject. TheLinkSigningKeyDecryptorinstance is built using your implementation of theIAppStorePrivateKeyProviderinterface. -
Generate an Amazon representation of the account linking relationship by building a
Linkobject as follows. -
Generate an SSI token for the linked account represented using the
Linkobject created in the previous step. Use thegenerateToken()method exposed through theSSITokenV1Generatorclass to create an SSI token as follows.

