Aptos Keyless Integration Guide

Step 1. Configure your OpenID integration with your IdP

The first step is to setup the configuration with your IdP(s).

Follow the intructions here

Step 2. Install the Aptos TypeScript SDK

# Keyless is supported in version 1.18.1 and above
pnpm install @aptos-labs/ts-sdk

Step 3. Client Integration Steps

Below are the default steps for a client to integrate Keyless Accounts

0. -Federated Keyless only- Register JWK on-chain

To register the JWK - call the entry function 0x1::jwks::update_federated_jwk_set with an Aptos account that will store the JWKs that will be used to validate transactions signed by federated keyless accounts.

The JWK set can be found as follows -

AWS Cognito - https://cognito-idp.{Region}.amazonaws.com/{userPoolId}/.well-known/jwks.json

Auth0 - https://{yourDomain}/.well-known/jwks.json

The typescript SDK has a function to simplify the process given the iss for your IAM provider setup (the iss claim value on your user’s JWT tokens).

const jwkOwner = <Instantiate the account you want to use here>
const jwkUpdateTxn = await aptos.updateFederatedKeylessJwkSetTransaction({ sender: jwkOwner, iss });
await aptos.signAndSubmitTransaction({ signer: jwkOwner, transaction: jwkUpdateTxn });

1. Present the user with a “Sign In with [IdP]” button on the UI

1. In the background, we create an ephemeral key pair. Store this in local storage.

   import {EphemeralKeyPair} from '@aptos-labs/ts-sdk';
    
   const ephemeralKeyPair = EphemeralKeyPair.generate();

2. Save the EphemeralKeyPair in local storage, keyed by its nonce.

   // This saves the EphemeralKeyPair in local storage
   storeEphemeralKeyPair(ephemeralKeyPair);

 
/**
 * Store the ephemeral key pair in localStorage.
 */
export const storeEphemeralKeyPair = (ekp: EphemeralKeyPair): void =>
  localStorage.setItem("@aptos/ekp", encodeEphemeralKeyPair(ekp));
 
/**
 * Retrieve the ephemeral key pair from localStorage if it exists.
 */
export const getLocalEphemeralKeyPair = (): EphemeralKeyPair | undefined => {
  try {
    const encodedEkp = localStorage.getItem("@aptos/ekp");
    return encodedEkp ? decodeEphemeralKeyPair(encodedEkp) : undefined;
  } catch (error) {
    console.warn(
      "Failed to decode ephemeral key pair from localStorage",
      error
    );
    return undefined;
  }
};
 
/**
 * Stringify the ephemeral key pairs to be stored in localStorage
 */
export const encodeEphemeralKeyPair = (ekp: EphemeralKeyPair): string =>
  JSON.stringify(ekp, (_, e) => {
    if (typeof e === "bigint") return { __type: "bigint", value: e.toString() };
    if (e instanceof Uint8Array)
      return { __type: "Uint8Array", value: Array.from(e) };
    if (e instanceof EphemeralKeyPair)
      return { __type: "EphemeralKeyPair", data: e.bcsToBytes() };
    return e;
  });
 
/**
 * Parse the ephemeral key pairs from a string
 */
export const decodeEphemeralKeyPair = (encodedEkp: string): EphemeralKeyPair =>
  JSON.parse(encodedEkp, (_, e) => {
    if (e && e.__type === "bigint") return BigInt(e.value);
    if (e && e.__type === "Uint8Array") return new Uint8Array(e.value);
    if (e && e.__type === "EphemeralKeyPair")
      return EphemeralKeyPair.fromBytes(e.data);
    return e;
  });

3. Prepare the URL params of the login URL. Set the redirect_uri and client_id to your configured values with the IdP. Set the nonce to the nonce of the EphemeralKeyPair from step 1.1.

   const redirectUri = 'https://.../login/callback'
   const clientId = env.IDP_CLIENT_ID
   // Get the nonce associated with ephemeralKeyPair
   const nonce = ephemeralKeyPair.nonce

4. Construct the login URL for the user to authenticate with the IdP. Make sure the openid scope is set. Other scopes such as email and profile can be set based on your app’s needs.

   const loginUrl = `https://accounts.google.com/o/oauth2/v2/auth?response_type=id_token&scope=openid+email+profile&nonce=${nonce}&redirect_uri=${redirectUri}&client_id=${clientId}`

5. When the user clicks the login button, redirect the user to the loginUrl that was created in step 1.4.

2. Handle the callback by parsing the token and create a Keyless account for the user

1. Once the user completes the login flow, they will be redirected to the redirect_uri set in step 1. The JWT will be set in the URL as a search parameter in a URL fragment, keyed by id_token. Extract the JWT from the window by doing the following:

   const parseJWTFromURL = (url: string): string | null => {
     const urlObject = new URL(url);
     const fragment = urlObject.hash.substring(1);
     const params = new URLSearchParams(fragment);
     return params.get('id_token');
   };
    
   // window.location.href = https://.../login/google/callback#id_token=...
   const jwt = parseJWTFromURL(window.location.href)

2. Decode the JWT and get the extract the nonce value from the payload.

   import { jwtDecode } from 'jwt-decode';
    
   const payload = jwtDecode<{ nonce: string }>(jwt);
   const jwtNonce = payload.nonce

3. Fetch the EphemeralKeyPair stored in step 1.2. Make sure to validate the nonce matches the decoded nonce and that the EphemeralKeyPair is not expired.

   const ekp = getLocalEphemeralKeyPair();
    
   // Validate the EphemeralKeyPair
   if (!ekp || ekp.nonce !== jwtNonce || ekp.isExpired() ) {
     throw new Error("Ephemeral key pair not found or expired");
   }

4. Instantiate the user’s KeylessAccount

   Normal Keyless

   import {Aptos, AptosConfig, Network} from '@aptos-labs/ts-sdk';
    
   const aptos = new Aptos(new AptosConfig({ network: Network.DEVNET })); // Configure your network here
   const keylessAccount = await aptos.deriveKeylessAccount({
       jwt,
       ephemeralKeyPair,
   });

If you are using an IAM provider, set the jwkAddress to the address of the account used in step 0

Federated Keyless

import {Aptos, AptosConfig, Network} from '@aptos-labs/ts-sdk';
 
const aptos = new Aptos(new AptosConfig({ network: Network.DEVNET })); // Configure your network here
const keylessAccount = await aptos.deriveKeylessAccount({
    jwt,
    ephemeralKeyPair,
    jwkAddress: jwkOwner.accountAddress
});

3. Store the KeylessAccount in local storage (Optional)

1. After the account has been derived, store the KeylessAccount in local storage. This allows the user to return to the application without having to re-authenticate.

   keyless.ts

   export const storeKeylessAccount = (account: KeylessAccount): void =>
     localStorage.setItem("@aptos/account", encodeKeylessAccount(account));
    
   export const encodeKeylessAccount = (account: KeylessAccount): string =>
     JSON.stringify(account, (_, e) => {
       if (typeof e === "bigint") return { __type: "bigint", value: e.toString() };
       if (e instanceof Uint8Array)
         return { __type: "Uint8Array", value: Array.from(e) };
       if (e instanceof KeylessAccount)
         return { __type: "KeylessAccount", data: e.bcsToBytes() };
       return e;
     });

2. Whenever the user returns back to the application, retrieve the KeylessAccount from local storage and use it to sign transactions.

   keyless.ts

   export const getLocalKeylessAccount = (): KeylessAccount | undefined => {
     try {
       const encodedAccount = localStorage.getItem("@aptos/account");
       return encodedAccount ? decodeKeylessAccount(encodedAccount) : undefined;
     } catch (error) {
       console.warn(
         "Failed to decode account from localStorage",
         error
       );
       return undefined;
     }
   };
    
   export const decodeKeylessAccount = (encodedAccount: string): KeylessAccount =>
     JSON.parse(encodedAccount, (_, e) => {
       if (e && e.__type === "bigint") return BigInt(e.value);
       if (e && e.__type === "Uint8Array") return new Uint8Array(e.value);
       if (e && e.__type === "KeylessAccount")
         return KeylessAccount.fromBytes(e.data);
       return e;
     });

4. Submit transactions to the Aptos blockchain

1. Create the transaction you want to submit. Below is a simple coin transfer transaction for example:

   import {Account} from '@aptos-labs/ts-sdk';
    
   const bob = Account.generate();
   const transaction = await aptos.transferCoinTransaction({
       sender: keylessAccount.accountAddress,
       recipient: bob.accountAddress,
       amount: 100,
   });

2. Sign and submit the transaction to the chain.

   const committedTxn = await aptos.signAndSubmitTransaction({ signer: keylessAccount, transaction });

3. Wait for the transaction to be processed on-chain

   const committedTransactionResponse = await aptos.waitForTransaction({ transactionHash: committedTxn.hash });