Skip to content
AtheronDEVELOPERS

Tutorial: sign-in from start to finish

Register an app, send somebody to sign in, handle the callback, check the ID token, keep a session and sign out.

Sign in to see your own test client ID in the samples.

This walks through a whole sign-in on a server app. Pick your language in any code block and every block follows. Plan on about twenty minutes.

1. Register an app

Sign in to the developer portal and choose New app. Pick Confidential for a server app that can keep a secret, or Public for a mobile, desktop or browser app. You get a test client and a live client at once.

On the app's Sign-in page add your redirect address for the test client, for example http://localhost:3000/callback. Test clients may use localhost; live clients may not. Any https address, in test or live, must be on a domain your team verified on its Domains page (Verifying your domain).

On Credentials, make a secret. It starts ath_cs_ and is shown once: put it in your server's environment as ATHERON_CLIENT_SECRET, with the client ID as ATHERON_CLIENT_ID.

2. Send somebody to sign in

When somebody presses Sign in with Atheron, make a PKCE pair, a state and a nonce, keep them in an HTTP-only cookie for this browser, and redirect to the authorize address.

Only your team and your testers can sign in to the test client. Invite testers by username on the app's Testers page: each one sees your app, your team and what it asks for in their Atheron account, and becomes a tester when they accept. An invitation lasts 30 days, and somebody who declines cannot be asked again for 30 days.

# The authorize request is a page the person opens, not an API call. Build the address on your
# server: a fresh PKCE pair, state and nonce for this browser, then redirect them to it.
VERIFIER=$(openssl rand -base64 32 | tr '+/' '-_' | tr -d '=\n')
CHALLENGE=$(printf '%s' "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 | tr '+/' '-_' | tr -d '=\n')
STATE=$(openssl rand -hex 16)
echo "https://accounts.aton-network.org/oauth/authorize?response_type=code&client_id=$ATHERON_CLIENT_ID&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&scope=openid%20profile%20email&state=$STATE&code_challenge=$CHALLENGE&code_challenge_method=S256"
Example response302
(no body: the browser follows the redirect)

3. Handle the callback

We send the person back to your redirect address with code and state. Compare state with the one you kept, in constant time, then swap the code. It lasts 60 seconds and works once.

# Swap the code from the redirect for tokens, on your server. HTTP Basic carries your client ID and
# secret; the verifier proves this is the browser that started the sign-in.
curl https://accounts.aton-network.org/oauth/token \
  -u "$ATHERON_CLIENT_ID:$ATHERON_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri=https://app.example.com/callback \
  -d code_verifier="$VERIFIER"
Example response200
{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "openid profile email offline_access",
  "id_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IjIwMjYtMTAtMDEiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJodHRwczovL2FjY291bnRzLmF0b24tbmV0d29yay5vcmciLCJzdWIiOiI5YTZk...",
  "refresh_token": "ath_rt_6Qm9..."
}

4. Check the ID token

Before you trust the ID token, check its signature against our signing keys (ES256 only), that iss is https://accounts.aton-network.org, that aud is your client ID, that it has not expired, and that nonce is the one you kept. A JOSE library does all of this in one call.

5. Keep your own session

Key your user record on sub. It is your app's own ID for the person (another app sees a different one) and it never changes. Never key on email: people change it. Then set your own session cookie and forget the tokens unless you need userinfo later.

# Who the person is as of now, with an access token issued to your client.
curl https://accounts.aton-network.org/oauth/userinfo \
  -H "Authorization: Bearer $ACCESS_TOKEN"
Example response200
{
  "sub": "9a6d4c1e-1f0b-4a51-8a8e-3b2f6c0d7e11",
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "email_verified": true,
  "age": { "verified": true, "adult": true, "sixteen_or_over": true }
}

6. Sign out

Ending your session is enough for most apps. If you kept a refresh token, revoke it so it can never be used again.

# End a refresh token and every token in its line. Always answers 200 once your app is authenticated.
curl https://accounts.aton-network.org/oauth/revoke \
  -u "$ATHERON_CLIENT_ID:$ATHERON_CLIENT_SECRET" \
  -d token="$REFRESH_TOKEN" \
  -d token_type_hint=refresh_token
Example response200
{}

Next

Ask Atlas

AI assistant

Ask anything about Sign in with Atheron, the API or the portal. You get an answer from our docs, with links to the pages it used.