Skip to main content

Stellar Authentication

Enable Stellar Authentication​

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

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

# dev.env
SEP10_ENABLED=true
SEP10_HOME_DOMAIN=localhost:8080
SECRET_SEP10_SIGNING_SEED="a Stellar private key"
SECRET_SEP10_JWT_SECRET="a secret encryption key"

SEP_10_HOME_DOMAIN is the home_domain property used by [sep-10]. The configuration value must be equal to the host of the toml file. If you are hosting toml file via the Platform, (SEP1_ENABLED is set to true), toml file will be hosted on the SEP server.

SECRET_SEP10_SIGNING_SEED is the private key to the public key you've specified as the SIGNING_KEY in your stellar.toml file. It will be used to sign authentication challenges presented to wallet applications, providing that you are in possession of the SIGNING_KEY. Wallets will check for this signature before signing and sending back the authentication challenge.

SECRET_SEP10_JWT_SECRET is the encryption key that will be used to sign and verify the authentication tokens you issue to wallet applications after they or their users have proven control of their Stellar account.

info

By default, the Anchor Platform allows anyone with a Stellar account to authenticate with your services. If you'd like to only allow users of a particular wallet application to authenticate, or want to disallow specific users from authenticating, use the following environment variables. This is an optional feature and should only be added if it is a business requirement.

# dev.env
SEP10_CLIENT_ATTRIBUTION_REQUIRED=true
clients:
  # Each item in the list may contain the following fields:
  #   - name: (required) the name of the client
  #   - type: (required) `custodial` or `noncustodial`
  #
  #   If the type is `custodial`,
  #   - signing_key: (required) the custodial SEP-10 signing key of the client.
  #   - callback_url: (optional) the URL of the client's callback API endpoint.
  #   - allow_any_destination: (optional) default to false. If set to true, allows any destination for deposits.
  #   - destination_accounts: (optional) list of accounts allowed to be used for the deposit. If allows_any_destinations set to true, this configuration option is ignored.
  #
  #   If the type is `noncustodial`,
  #   - domain: (required) the domain of the client.
  #   - callback_url: (optional) the URL of the client's callback API endpoint
  #   - signing_key: (optional) the signing key of the client.

  # custodial client
  - name: custodial-client1
    type: custodial
    signing_key: "the custodial SEP-10 signing key of the client1"
    callback_url: https://callback.custodial-client1.com/api/v1/anchor/callback
    allow_any_destination: false
    destination_accounts:
  - name: custodial-client2
    type: custodial
    signing_key: "the custodial SEP-10 signing key of the client2"

  # noncustodial client
  - name: noncustodial-client1
    type: noncustodial
    domain: noncustodial-client1.co
    callback_url: https://callback.noncustodial-client1.co/api/v2/anchor/callback
    signing_key: "the signing key of the client1"
  - name: noncustodial-client2
    type: noncustodial
    domain: noncustodial-client2.com

SEP10_CLIENT_ATTRIBUTION_REQUIRED informs the Anchor Platform whether it should allow users of noncustodial wallets to authenticate without the wallet also identifying itself.

CLIENTS is the list of outside wallet servers or clients for the Anchor server to safely communicate with.

Modify a Stellar Info File​

Next, let's modify stellar.toml file created earlier. Wallets need to know that SEP-10 functionality is supported by your business.

# dev.stellar.toml
ACCOUNTS = ["add your public keys for your distribution accounts here"]
SIGNING_KEY = "add your signing key here"
NETWORK_PASSPHRASE = "Test SDF Network ; September 2015"

WEB_AUTH_ENDPOINT = "http://localhost:8080/auth"

[DOCUMENTATION]
ORG_NAME = "Your organization"
ORG_URL = "Your website"
ORG_DESCRIPTION = "A description of your organization"