Documentation

Updated

Concepts

algizian is an OAuth 2.1 and OpenID Connect server that many separate products share. Each product is a tenant. This page explains the pieces and how they relate.

Tenants

A tenant is one product or site that needs sign-in: a game, an app, a website. It has a slug, a display name, optional branding, a list of enabled social providers and, optionally, a custom domain. Everything else (clients, users, keys, tokens) belongs to exactly one tenant, and tenants cannot see each other's data.

The slug has 4 to 40 characters from a-z, 0-9 and -. It cannot start or end with a hyphen, contain -- or be all digits, and a list of reserved names (such as admin or support) is refused. Names of well-known companies and products are reserved too, so nobody can sign in people on a lookalike address.

Issuers and sign-in hosts

The slug is also the tenant's address: a tenant called acme-games is served at https://acme-games.algizian.com, from the moment it is created. That address is the tenant's issuer, the iss value in its tokens, and the base of all its endpoints:

EndpointPath on the tenant host
Discovery/.well-known/openid-configuration and /.well-known/oauth-authorization-server
Authorization/authorize
Token/token
Key set/jwks.json
User info/userinfo
Revocation/revoke
Dynamic client registration/register

Read the endpoints from the discovery document rather than hard-coding them. A tenant can also be served on its own domain, see custom domains; each host is its own issuer.

Clients

A client is an application that asks users to sign in: a web app, a mobile app, a game, a server, or an agent connector. You create clients with the management API, or a connector registers itself through dynamic client registration.

  • Public clients (browser and mobile apps, games) hold no secret and always use PKCE.
  • Confidential clients (servers) get a secret, shown once, and authenticate at the token endpoint.
  • Redirect addresses are registered per client and matched exactly.
  • A first-party client belongs to the tenant itself, so users are not asked to consent again; a client that is not first-party shows a consent screen the first time.

Users

People sign in with Google, Microsoft or Apple. algizian stores no passwords. The first time someone signs in to a tenant, a user is created for that tenant, so sign-up is open to anyone with a valid account at a provider.

Users are tenant-scoped. The same person signing in to two tenants becomes two unrelated users with a different sub, so tenants cannot recognise or correlate each other's users. Inside a tenant, a person who signs in with a second provider that confirms the same verified email address is the same user; an email address that a provider has not verified is never trusted as proof of who someone is. A signed-in user can link another provider to their user at /link on the tenant address by signing in with that provider too; users are never merged automatically.

A tenant can block a user, which ends their sessions and refresh tokens and stops further sign-ins, or delete a user entirely. You can also create users yourself before they sign in, for example to import them from another system; invitations and allow lists are not available yet.

Providers

Each tenant lists the providers it offers: any of google, microsoft and apple, all three by default. Microsoft sign-in proves who the user is; it does not check game ownership or any product profile. By default the shared algizian apps are used, so the provider's consent screen names algizian. A tenant can register its own Google, Microsoft or Apple app instead and show its own name: see Your own provider apps.

What your users will see

With the shared algizian provider apps (the default), the Google, Microsoft or Apple approval screen names Algizian, not your product. A person who just tapped "Sign in" on a site called Acme Games can be surprised by that, and some abandon the sign-in or report it. Tell them in advance, on your own pages next to the sign-in button, for example:

We use the Algizian authentication server for social sign-in. Google, Microsoft or Apple will show "Algizian" when you approve. How Algizian handles your data

The sign-in page that algizian serves already says this under the provider buttons, for providers that run on the shared apps: "Sign-in is provided by Algizian. Google or Microsoft will show "Algizian" when you approve." A provider for which you registered your own app is left out of that line, and when none is shared the line disappears. To use your own words, set the sharedAppNotice branding field; null goes back to the default. To show your own name on the provider's approval screen, register your own app, see Your own provider apps.

Branding

Per tenant you can set the name shown on the screens, an uploaded logo (PNG, JPEG or WebP, shown as a 64 x 64 square), a primary, background and text colour, and the wording of the sign-in title, subtitle, consent note, footer and the line about the shared provider apps. Branding applies to the sign-in and consent screens. See the management API for the fields.

Tokens

  • Authorization code: single-use and short-lived, bound to the client, the redirect address and the PKCE challenge.
  • Access token: a signed JWT, short-lived. Its audience is the resource you asked for (RFC 8707), or the issuer when you gave none.
  • ID token: a signed JWT for your client with sub, iss, aud, exp, iat, auth_time, nonce and, depending on scope, name, picture and email.
  • Refresh token: opaque and rotating. Each use returns a new token and retires the old one.

Every tenant has its own signing keys, published at its /jwks.json. Rotating keys makes new tokens use a new key and keeps the previous key in the set for 7 days, longer than any token lives, so verification of earlier tokens does not break. Keys also rotate by themselves after 90 days.

The standards in use

Discovery (RFC 8414 and OpenID Connect Discovery), the authorization code flow with PKCE S256, refresh token rotation, token revocation (RFC 7009), dynamic client registration (RFC 7591), resource indicators (RFC 8707) and the iss response parameter (RFC 9207). Implicit and password grants do not exist.

Next: the quick start runs this end to end.