Skip to main content
Version: Next

Stellar Authentication for Contract Accounts

Overview​

Stellar smart wallet applications create authenticated sessions with Stellar anchors by proving they, or their users, have sufficient control over a contract account. Once authenticated, the smart wallet application uses a session token provided by the anchor in subsequent requests to the anchor's standardized services.

This is similar to how SEP-10 works, but with a few differences:

  • The challenge is a list of Soroban authorization entries for an invocation of a SEP-45 contract that must be signed by the contract account's signers.
  • The wallet is responsible for simulating the transaction and ensuring it is not malicious.
  • The anchor verifies the signed authorization entries by simulating the transaction on the network.

An implementation of the SEP-45 contract is provided in the Anchor Platform repository. An instance of this contract is deployed at CD3LA6RKF5D2FN2R2L57MWXLBRSEWWENE74YBEFZSSGNJRJGICFGQXMX on testnet.

Enable Stellar Authentication for Contract Accounts​

The Anchor Platform supports this form of authentication with minimal configuration from the business.

Connect to Stellar RPC​

SEP-45 requires integration with Stellar RPC to simulate transactions. The Anchor Platform can connect to the Stellar RPC server of your choice.

You can use a public Stellar RPC provider, or you can run your own. A list of public providers can be found here. The following example uses SDF's testnet RPC.

# dev.env
STELLAR_NETWORK_RPC_URL=https://soroban-testnet.stellar.org

Enable SEP-45​

To enable SEP-45, set the following environment variables in your dev.env file.

# dev.env
SEP_45_ENABLED=true
SEP_45_WEB_AUTH_DOMAIN=localhost:8080
SEP_45_WEB_AUTH_CONTRACT_ID="CD3LA6RKF5D2FN2R2L57MWXLBRSEWWENE74YBEFZSSGNJRJGICFGQXMX"
SEP_45_HOME_DOMAINS=localhost:8080
SEP_45_JWT_TIMEOUT=900
SEP_45_AUTH_TIMEOUT=86400

SEP_45_ENABLED enables SEP-45.

SEP_45_WEB_AUTH_DOMAIN is the domain where the authentication service (WEB_AUTH_ENDPOINT or WEB_AUTH_FOR_CONTRACTS_ENDPOINT) is running. This might be the same as the home_domain, a subdomain (e.g., auth.example.com), or a completely different domain. It's verified in the challenge to ensure the client is talking to the correct server endpoint it discovered via the home_domain.

SEP_45_WEB_AUTH_CONTRACT_ID is the contract ID of the SEP-45 contract. This is the contract that will be used to construct the challenge.

SEP_45_HOME_DOMAINS is a comma-separated list of home domains that are allowed to authenticate with the anchor. Home domains are the domains hosting the stellar.toml file. This file tells clients where to find the authentication endpoint (WEB_AUTH_FOR_CONTRACTS_ENDPOINT) and which public key (SIGNING_KEY) the server will use for challenges.

SEP_45_JWT_TIMEOUT is the time in seconds that the JWT token is valid. The default is 900 seconds (15 minutes).

SEP_45_AUTH_TIMEOUT is the time in seconds that the authentication challenge is valid. The default is 86400 seconds (24 hours).

Modify a Stellar Info File​

The stellar.toml file created earlier must be updated to include the new authentication endpoint and contract ID.

# dev.stellar.toml
WEB_AUTH_FOR_CONTRACTS_ENDPOINT = "http://localhost:8080/sep45/auth"
WEB_AUTH_CONTRACT_ID = "CD3LA6RKF5D2FN2R2L57MWXLBRSEWWENE74YBEFZSSGNJRJGICFGQXMX"

WEB_AUTH_FOR_CONTRACTS_ENDPOINT is the URL where the authentication service is running. This is the URL that clients will use to authenticate with the anchor.

WEB_AUTH_CONTRACT_ID is the contract ID of the SEP-45 contract. This is the contract that will be used to construct the challenge.