Require Authentication

As defined by the SEP-10 Stellar Web Authentication specification,

This SEP defines the standard way for clients such as wallets or exchanges to create authenticated web sessions on behalf of a user who holds a Stellar account. A wallet may want to authenticate with any web service which requires a Stellar account ownership verification, for example, to upload KYC information to an anchor in an authenticated way as described in SEP-12.

Most Polaris endpoints require a SEP-10 authentication token, refered to as the JWT, and Polaris includes an easily enabled implemenation of SEP-10 that clients can use to obtain these tokens.

It is also possile to host a SEP-10 server independent of your Polaris deployment as long as the secret used to generate the signature of each token matches the value assigned to Polaris’ SERVER_JWT_KEY environment variable. In this case, the following steps can be skipped.

Configure Settings

Add SEP-10 to ACTIVE_SEPS, and add the SIGNING_SEED and SERVER_JWT_KEY environment variables.

ACTIVE_SEPS=sep-1,sep-10
HOST_URL=http://localhost:8000
LOCAL_MODE=1
ENABLE_SEP_0023=1
SIGNING_SEED=S...
SERVER_JWT_KEY=...

SIGNING_SEED is used to sign challenge transactions requested by client applications, and SERVER_JWT_KEY is used to verify that the authenticatoin token payload has not been tampered with.

Update the TOML File

If you provided a static SEP-1 file for Polaris to use, make sure you add the WEB_AUTH_ENDPOINT attribute so clients can find your authentication service.

Confirm the API is Live

Run the web server.

python anchor/manage.py runserver

You should see the WEB_AUTH_ENDPOINT URL at http://localhost:8000/.well-known/stellar.toml, and making a GET request to it should return a error responses complaining about a missing account parameter.

Adding Client Attribution

Optionally, you can configure your authentication service to deny requests from clients that do not offer to cryptographically verify their identity. SEP10_CLIENT_ATTRIBUTION_REQUIRED and related environment variables allow you to define an allow or denylist of domains that can authenticate with your service.

By default, Polaris does not require clients to perform this verification, but it will allow clients to do so voluntarily. In these cases, Polaris will assign the client_domain property of the polaris.sep10.token.SEP10Token object passed to the request with the verified domain.

Issuing Tokens for Other Domains

SEP-10 servers can issue authentication tokens for multiple services, including services hosted on different domains. To enable this, add the domains you would like Polaris to issue authenticaton tokens for to the SEP10_HOME_DOMAINS environment variable.