Updated
Quick start
This walkthrough takes a new tenant to a signed-in user and a validated token. It uses only curl, openssl and a few lines of JavaScript. The names, addresses and ids are made up: replace acme-games, app.example.com and the client id with your own.
You need a platform token (it starts with ag_) to create a tenant. Access is by invitation for now, so ask [email protected] for one. A tenant created for you can also be handed a tenant token with a narrower scope, see the management API.
export ALGIZIAN_TOKEN=ag_your_platform_token
export API=https://id.algizian.com/api/v1
1. Create a tenant
The slug becomes the sign-in address. It has 4 to 40 characters from a-z, 0-9 and -, and some names are reserved.
curl -s -X POST $API/tenants \
-H "Authorization: Bearer $ALGIZIAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"slug": "acme-games",
"name": "Acme Games",
"branding": { "displayName": "Acme Games", "primaryColor": "#c2410c" }
}'
The answer includes the tenant's issuer, https://acme-games.algizian.com. Providers default to Google, Microsoft and Apple; pass "providers": ["google"] to offer fewer. Until you register your own provider apps, Google, Microsoft and Apple show "Algizian" on their approval screen, so tell your users that you use the Algizian authentication server for social sign-in; the answer carries a notice with suggested wording, see what your users will see. The tenant is live straight away: open https://acme-games.algizian.com/.well-known/openid-configuration to see its endpoints.
2. Add a client
A client is your app. A public client (a single-page app, a mobile app or a game) holds no secret and relies on PKCE. A confidential client (a server) also gets a secret, which is shown once.
curl -s -X POST $API/tenants/acme-games/clients \
-H "Authorization: Bearer $ALGIZIAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme web app",
"redirectUris": ["https://app.example.com/callback"],
"type": "public"
}'
Keep the id of the answer (it looks like c_8f3k2m9x). That is your client_id. Redirect addresses are matched exactly and must be registered first. They use https; native apps and local development may also use http on localhost, 127.0.0.1 or [::1], or a reverse-domain scheme such as com.example.app. Wildcards are not allowed.
3. Create a PKCE challenge
PKCE with the S256 method is required. Generate a random verifier and derive the challenge from it. Keep the verifier and the state value for the next steps.
CODE_VERIFIER=$(openssl rand -base64 48 | tr -d '=+/\n' | cut -c1-64)
CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')
STATE=$(openssl rand -hex 16)
4. Send the user to sign in
Redirect the user's browser to the tenant's authorize endpoint:
https://acme-games.algizian.com/authorize
?response_type=code
&client_id=c_8f3k2m9x
&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
&scope=openid%20profile%20email%20offline_access
&state=<STATE>
&code_challenge=<CODE_CHALLENGE>
&code_challenge_method=S256
The user sees the sign-in screen with your branding, picks Google, Microsoft or Apple, and is sent back to your redirect address:
https://app.example.com/callback?code=Zp3...&state=<STATE>&iss=https%3A%2F%2Facme-games.algizian.com
Check that state matches the value you sent and that iss equals the issuer you expect. The code is single-use and short-lived.
Scopes: openid returns an ID token, profile adds name and picture, email adds the email address. offline_access is also accepted. A refresh token is returned to clients that allow the refresh_token grant, which is the default.
5. Exchange the code for tokens
curl -s -X POST https://acme-games.algizian.com/token \
-d grant_type=authorization_code \
-d client_id=c_8f3k2m9x \
-d redirect_uri=https://app.example.com/callback \
-d code=Zp3... \
-d code_verifier="$CODE_VERIFIER"
{
"access_token": "eyJhbGciOiJFUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 600,
"scope": "openid profile email offline_access",
"id_token": "eyJhbGciOiJFUzI1NiIs...",
"refresh_token": "agr_..."
}
A confidential client authenticates with its secret, either with HTTP Basic or with client_secret in the body.
6. Validate the token
Tokens are signed JWTs. Fetch the tenant's public keys from its key set and verify the signature, the issuer, the expiry and the audience. With the jose library:
import { createRemoteJWKSet, jwtVerify } from 'jose'
const issuer = 'https://acme-games.algizian.com'
const keys = createRemoteJWKSet(new URL(`${issuer}/jwks.json`))
// The ID token is meant for your client.
const { payload } = await jwtVerify(idToken, keys, { issuer, audience: 'c_8f3k2m9x' })
console.log(payload.sub, payload.email)
// The access token is meant for the resource it was requested for. Without
// a `resource` parameter its audience is the issuer.
await jwtVerify(accessToken, keys, { issuer, audience: issuer })
payload.sub is the user's id in this tenant. The same person has a different sub in every other tenant. Use the kid header and the key set rather than caching one key forever: keys can be rotated, and the key set always carries the keys that still matter.
You can also call GET https://acme-games.algizian.com/userinfo with the access token as a bearer token to read the profile claims.
7. Refresh
curl -s -X POST https://acme-games.algizian.com/token \
-d grant_type=refresh_token \
-d client_id=c_8f3k2m9x \
-d refresh_token=agr_...
Refresh tokens rotate: each use returns a new one and retires the old one. Always store the newest. To end a session, send the refresh token to POST /revoke.
Where to go next
- Concepts: how tenants, issuers, clients and users fit together.
- Management API: branding, users, tenant tokens and keys.
- Custom domains: sign in on
login.example.cominstead.