Skip to main content
Pylon can be the identity provider that other systems sign into. Internal tools, microservices, or third-party SaaS that accept any OIDC IdP point at Pylon’s discovery doc. They treat the id_tokens Pylon issues as the identity layer.

What ships

The full auth-code and PKCE flow:

Security stance

  • PKCE S256 is REQUIRED for every authorize request. Pylon rejects plain per OAuth 2.1 and rejects a request with no PKCE.
  • redirect_uri must match the client’s registered list by exact string compare. Pylon allows no path coercion, suffix matching, or scheme upgrades (a common OIDC open-redirect risk).
  • client_id and client_secret are constant-time compared. Public clients (no secret in registration) authenticate via PKCE alone.
  • id_token claims: iss, sub, aud, exp (10 min), iat, nonce (when supplied at /authorize), email, email_verified, name (subject to requested scopes).
  • access_token is opaque random (32-byte base64url), TTL 1 hour.
  • refresh_token is issued only when the client asks for the offline_access scope. See Refresh tokens.
  • Pylon stores access and refresh tokens as SHA-256 hashes in the auth database (SQLite or Postgres). They survive restarts and are shared by every machine. Auth codes stay in memory: they live 10 minutes and are single-use.
  • Clients authenticate at /oidc/token and /oidc/revoke with client_secret_post (form fields) or client_secret_basic (the Authorization: Basic header).

Configuration

PYLON_OIDC_CLIENTS is a JSON array of {client_id, client_secret?, redirect_uris[]}. client_secret is optional — omit it for SPAs / native apps that authenticate via PKCE only.

Signing key

On first start (with PYLON_OIDC_ISSUER set), Pylon generates a 2048-bit RSA key, persists it as PKCS#8 PEM at PYLON_OIDC_KEY_PATH, and chmods the file to 0600 so it is not world-readable. Pylon reuses the same key across restarts, so issued id_tokens stay verifiable. The JWKS endpoint publishes the matching public key with:
  • kid = first 16 hex chars of SHA-256(modulus) — stable across restarts, changes on rotation
  • kty: "RSA", alg: "RS256", use: "sig"
  • n + e = base64url-no-pad-encoded big-endian integers

Auth-code flow

A typical end-to-end exchange:

Refresh tokens

Ask for offline_access at /oidc/authorize and the code exchange also returns a refresh token:
Exchange it for new tokens:
  • The client authenticates the same way as for the code exchange. The refresh token must belong to that client.
  • scope is optional. It can narrow the scopes of the new access token, never widen them. The new refresh token keeps the grant’s scopes.
  • Every refresh returns a new refresh token, valid for 30 days. A grant stays alive while the client keeps refreshing.
  • The used refresh token still works for 60 seconds, so two requests from one app that refresh at the same moment both succeed.
  • A used refresh token that comes back after those 60 seconds counts as stolen. Pylon revokes the whole grant (every access and refresh token from that sign-in) and answers invalid_grant. The user signs in again.
  • A refresh for a user that no longer exists fails with invalid_grant.
A Pylon app signing in against a Pylon IdP asks for offline_access without configuration, because the discovery document lists it next to orgs. It stores the refresh token on the account link, and ctx.auth.providerToken refreshes it (OAuth).

Revocation

POST /oidc/revoke (RFC 7009) takes token (an access or a refresh token) and the client’s credentials. Pylon revokes the whole grant the token belongs to. The answer is 200 for unknown tokens and for tokens of other clients too. Pylon also revokes every grant of a user when the user:
  • signs out everywhere (DELETE /api/auth/sessions),
  • changes or resets the password, or changes the email,
  • deletes the account, or an admin deletes the user row or purges the user.

Verify a token in your functions

Another app sends the access token it got from your IdP to prove which person it acts for. Check it with ctx.auth.verifyOidcToken:
It returns null for an unknown, expired, or revoked token, and for a refresh token. It throws OIDC_NOT_CONFIGURED in an app that is not an IdP. It runs in actions and mutations.

Token exchange for native apps

A native app that signs in to the IdP (Sign in with Apple, Google, an email code) can sign in to a client app without a browser. It trades its IdP session for an id_token addressed to the client, with an RFC 8693 token exchange:
The answer carries id_token, access_token and issued_token_type. scope is optional and defaults to openid email profile orgs; it must include openid. A token exchange never returns a refresh token. Token exchange is off for every client. Turn it on per client in PYLON_OIDC_CLIENTS with "token_exchange": true. The request carries no client secret, because the caller is the person’s own device, so enable it only for your own apps. Guest sessions and API keys are refused. The app then posts the id_token to the client’s POST /api/auth/federated/<provider> (Native sign-in).

Userinfo claim projection

/oidc/userinfo projects the User row through the same auth.user.expose / auth.user.hide config that protects /api/auth/session from leaking secrets. passwordHash and underscore-prefixed fields never reach a downstream service through userinfo. Claims returned per scope:

Where to go next

  • JWT sessions — minting the tokens app-internal services verify
  • SSO — the other direction (external IdPs signing INTO Pylon)
  • Sessions — the cookie that gates /oidc/authorize