Skip to content
🎉 Welcome to the new Aptos Docs! Click here to submit feedback!
BuildGuidesAptos Keyless AccountsFederated Keyless

Federated Keyless?

AIP-96: Federated Keyless is an extension of Aptos Keyless to support more OpenID Connect (OIDC) providers, beyond the ones that are allow-listed in 0x1::jwks via JWK consensus, while maintaining its decentralization. Federated keyless adds support for authenticating users via identity & access management (IAM) providers (e.g. Auth0, Okta and AWS Cognito) as long as your project uses a supported IAM provider for user authentication.

To elaborate further, Federated Keyless enables:

  1. Extension of authentication methods a. All authentication methods supported by the IAM are available to the dApp including email/SMS OTP and their marketplace of social login integrations like Discord, Naver, X and more. Auth0 marketplace linked here as an example.

  2. Compatibility with existing account systems a. Since IAMs also support custom authentication, it allows an application to bring its own username/password (Cognito docs, Auth0 docs). An application can start using an existing account system already set up with an IAM or they can migrate their existing account system to an IAM to generate Keyless-compatible JWTs.

Federated Keyless Key Considerations

Supported IAMs

Currently, the three supported IAMs are Amazon Cognito, Auth0, and Okta across devnet, testnet, and mainnet. See a table of the full set of supported IAM providers here.

Federated Keyless flow

The flow for Federated Keyless transactions is the same as described here. However, the difference is that in Federated Keyless, instead of the OIDC provider (e.g. Google, Apple) acting as the issuer of the JWT, the IAM provider (e.g. Auth0, Cognito) acts as the issuer. The user authenticates with the application, the IAM receives the user’s credentials, and then the IAM issues the Keyless-compatible JWT.

Available authentication methods

All authentication methods that are supported by the IAM providers are available for use - this includes SMS OTP, email link, and the traditional username + password.

Configuration limitations

A Keyless account address varies according to the aud (AKA application ID or client ID), and iss (AKA issuer). The setup of your user data within the IAM must reflect the interoperability you seek to provide to your users. JWT tokens issued for a user in the same user pool but for different applications will result in a different address derivation if the aud value is different.

The trust and security model for Federated Keyless

Compared to the existing Keyless implementation, dApp developers utilizing Federated Keyless alongside certain authentication methods like email/SMS, OTP and email/password may have more access to user credentials when leveraging IAM providers than with the existing direct OIDC provider integrations.

We recommend each dApp developer perform their own research and consult with their legal counsel before integrating an authentication method. Developers should also understand to what extent they may have access to user credentials and what controls they have in place.

Integration Guide

To start integrating with Federated Keyless　Accounts, follow the integration guide here. Make sure to follow any additional steps needed to setup Federated Keyless.

Managing JWKs

If you or the IAM platform rotates the key pairs used to signed the JWT tokens, the JWK set must be updated on chain. Use the same account in step 3 above to update the JWK set. Existing JWTs will continue to work so long as the old JWK has not been removed. Any new JWTs issued by the new keypair will not be accepted until the JWK set is updated.

It is important to not lose access to the account used in JWK updates. Whenever a keypair is rotated it is important for the JWK data on chain to reflect that for JWT tokens to stay valid.

Frequently Asked Questions

What if I stop using my IAM for my application? What if I switch IAM providers?

  • An account address depends on values of several variables that are specific to an IAM service, including aud (client ID) and iss (issuer). If these values are changed, then a different address will be derived.
  • If you want to switch IAM providers, you will need to develop an account migration flow, resulting in a key rotation from the account derived from the prior IAM provider to the account derived from the new IAM provider.
  • We recommend allowing your users to add a secondary authentication method to their accounts (e.g. back-up private key) so that they can maintain access should the authentication path into their account via Federated Keyless is disrupted via service provider change

How do I make sure my users can continue accessing their accounts?

  • We recommend allowing your users to add a secondary authentication method to their accounts (e.g. back-up private key) so that they can maintain access should the authentication path into their account via Federated Keyless is disrupted via service provider change or other (In some future I would love to be able to tell users that email backup is possible)

What differences in legal considerations between standard keyless and federated keyless?

  • Custody - Admin has the ability to impersonate a user.
How Keyless WorksTerminology and FAQ