Themis as a standalone OIDC service
Read this if you already have an identity system and need to connect Themis as an external OIDC provider. You can skip it for a standard deployment.
Themis as a standalone OIDC service
themis-auth is not just the sign-in backend for Agentic Hat; it is itself a standard OIDC
Provider (IdP). Once Themis is installed, the same set of accounts can serve your other
applications - internal admin consoles, mobile clients, partner systems - without building a
separate user table for each application.
This chapter is the complete checklist for "using it as an IdP": public endpoints, installation order, minimal configuration, RP registration, the integration flow, and acceptance checks. The full per-service deployment steps are still in "Path B: manual per-service deployment"; this chapter does not repeat database initialization or probes.
External endpoints
An RP accesses the IdP through a single public origin; five endpoints are passed through by
themis-web on the same origin and forwarded by themis-gateway to themis-auth on the
internal network:
| Method | Path | Purpose |
|---|---|---|
| GET | /.well-known/openid-configuration |
Discovery document, the source for RP configuration |
| GET | /jwks |
Public key set, used to verify the id_token signature |
| GET | /authorize |
Authorization entry point (full-page browser redirect) |
| POST | /token |
Exchange an authorization code for tokens; refresh tokens |
| GET | /logout |
RP-initiated sign out (full-page browser redirect) |
All endpoint URLs are derived from OIDC_ISSUER, so it must match the origin the browser
sees, character for character: https://accounts.titanides.com, with the scheme and without a
trailing slash. A mistake does not fail at startup; it only makes the RP fail when verifying
iss - this is the most common problem during integration.
/authorizeand/logoutare 302 redirects, not JSON APIs. The gateway must put them inREDIRECT_PROXIES; otherwise the 302 is swallowed as a response body and the browser sits on a blank page.
Installation order
Three services, a fixed order, none optional:
| Order | Service | Role in the OIDC chain | Detailed steps |
|---|---|---|---|
| 1 | themis-auth |
Issuer. Holds the database, signing private key, and RP allowlist; never leaves the internal network | See the themis-auth section |
| 2 | themis-gateway |
The only public entry point. Verifies signatures and forwards the five endpoints as-is | See the themis-gateway section |
| 3 | themis-web |
Login/signup pages for the identity domain + same-origin pass-through layer | See the themis-web section |
Even if you use Themis only as an IdP and do not run Agentic Hat, you must install all three
together: the OIDC issuer is a public domain, and by design themis-auth itself is not exposed.
themis-web is not an optional "login skin" - when someone visits /authorize while signed
out, the browser must land on its login page; the five endpoints under the same domain are also
forwarded through it.
Signup and password recovery also depend on rhea-email (the EMAIL_SERVICE_URL setting). If
all accounts are imported externally and you do not need self-service signup, you can leave this
variable empty (it does not block startup), but the "Sign up / Forgot password" entries on the
login page will be unavailable.
Minimal configuration
The following are the variables you must set to "run as an IdP and connect one RP." Anything not listed keeps its default; the full variable table is in each service's section.
themis-auth
| Variable | Value |
|---|---|
DATABASE_URL |
PostgreSQL connection string |
OIDC_ISSUER |
https://accounts.titanides.com |
OIDC_CLIENTS |
RP allowlist JSON; see the next section |
LOGIN_URL |
https://accounts.titanides.com/login - the themis-web login page, without a locale prefix; the middleware adds it |
IDP_SESSION_SECRET |
Random session key; no default, the application refuses to start when it is missing |
JWT_PRIVATE_KEY_PATH |
Path to the ES256 signing private key file |
JWT_PUBLIC_KEY_PATH |
Path to the corresponding public key file |
OIDC_KEY_ID |
The kid in JWKS; signing and public key must be consistent; default fewbox |
IDP_SESSION_TTL_SECONDS |
Session cookie lifetime; default 7 days |
AUTH_CODE_TTL_SECONDS |
Authorization code lifetime; default 60 seconds |
ID_TOKEN_EXPIRES_IN |
id_token lifetime; default 1h |
JWT_EXPIRES_IN / REFRESH_TOKEN_EXPIRES_IN |
Access token defaults to 24h; refresh token defaults to 7d |
Generate the key pair with openssl ecparam -name prime256v1 ...; for the full command see
"Generate a key pair" in the themis-auth section.
themis-gateway
| Variable | Value |
|---|---|
AUTH_OIDC_ENDPOINT |
{"protocol":"http","host":"themis-auth","port":80}, without basePath |
JWT_PUBLIC_KEY_PATH |
The same public key as auth (verifies access tokens) |
JWT_VERIFY_ALGORITHM |
ES256 |
REDIRECT_PROXIES |
/authorize, /logout |
POST_PROXIES |
/token |
GET_PROXIES |
/jwks, /.well-known/openid-configuration |
CORS |
Browser origins allowed to call the token endpoint directly; not needed when a backend exchanges tokens server-to-server |
The five endpoints must have publicPath written explicitly; otherwise the default paths become
things like /auth_oidc/authorize, and clients cannot find them from the discovery document:
REDIRECT_PROXIES=[{"endpoint":"AUTH_OIDC","path":"authorize","publicPath":"/authorize"},{"endpoint":"AUTH_OIDC","path":"logout","publicPath":"/logout"}]
POST_PROXIES=[{"endpoint":"AUTH_OIDC","path":"token","publicPath":"/token"}]
GET_PROXIES=[{"endpoint":"AUTH_OIDC","path":"jwks","publicPath":"/jwks"},{"endpoint":"AUTH_OIDC","path":".well-known/openid-configuration","publicPath":"/.well-known/openid-configuration"}]
themis-web
| Variable | Value |
|---|---|
GATEWAY_ENDPOINT |
http://themis-gateway |
themis-web's pass-through paths are a fixed list inside the image, not a configuration item.
If you upgrade the gateway allowlist without upgrading the themis-web image, new endpoints
fall through to Next's own 404.
Registering an RP
An RP (relying party) = the client application you want to connect. Registering means adding an
entry to OIDC_CLIENTS:
[
{
"client_id": "<rp-client-id>",
"redirect_uris": ["https://titanides.com/auth/callback"],
"post_logout_redirect_uris": ["https://titanides.com/"],
"name": "<RP display name>"
}
]
Rules:
- The RP chooses
client_iditself; it must be unique within this IdP; the RP sends it back unchanged when starting authorization. redirect_urisare matched exactly, character for character; scheme, host, port, path, and trailing slash all count. There is no prefix or wildcard matching - loosening this by one notch is an open redirect.- Write
post_logout_redirect_urisexplicitly if possible. When omitted, it falls back to "the same-origin root of the registeredredirect_uris," which effectively allows any path on that domain as a sign-out landing page; for new integrations, pin the specific page. - All RPs are public clients, with no
client_secret. Security comes from PKCE (S256); the RP must generate a newcode_verifierevery time and must not hardcode it. - Empty or a JSON parse failure = no usable client;
/authorizealways returnsunauthorized_client. - The registry is read only once per process. Restart
themis-authafter changingOIDC_CLIENTS; there is no hot reload.
RP-side integration flow
Discovery.
GET https://accounts.titanides.com/.well-known/openid-configuration; confirm thatissuermatches your configuration, then take the three endpoints from the document (authorization_endpoint,token_endpoint,jwks_uri). Do not hardcode endpoints into the RP.Start authorization. Send the browser on a full-page navigation to:
https://accounts.titanides.com/authorize
?client_id=<rp-client-id>
&redirect_uri=https://titanides.com/auth/callback
&response_type=code
&scope=openid
&state=<random per-request CSRF value>
&nonce=<random per-request replay-protection value>
&code_challenge=<BASE64URL(SHA-256(verifier))>
&code_challenge_method=S256
response_type only supports code; scope must include openid; code_challenge_method
must be S256. If any of these is wrong, the IdP redirects back with an error
(unsupported_response_type / invalid_scope / invalid_request).
When the user is signed out, the IdP 302s to LOGIN_URL and stuffs the entire authorization
request into the continue parameter; after a successful sign-in it returns to /authorize to
continue. The RP does not need to handle this intermediate step.
After authorization succeeds, the browser is sent back to redirect_uri with the parameters
code, the unchanged state, and iss. Validate state first, then verify that iss
equals OIDC_ISSUER.
- Exchange for tokens. On the RP backend,
POST /tokenwithContent-Type: application/x-www-form-urlencoded:
curl -s -X POST https://accounts.titanides.com/token \
-d grant_type=authorization_code \
-d code='<authorization code>' \
-d redirect_uri='https://titanides.com/auth/callback' \
-d client_id='<rp-client-id>' \
-d code_verifier='<original verifier from step 2>'
redirect_uri must match the one used at authorization character for character, and
client_id must match too. The authorization code is single-use and expires after 60
seconds by default; replaying the same code returns invalid_grant.
Successful response:
{
"access_token": "<ES256 JWT>",
"token_type": "Bearer",
"expires_in": 86400,
"refresh_token": "<opaque string>",
"id_token": "<ES256 JWT>"
}
- Verify
id_token. Verify the signature with the public key from/jwks, and check that:issequals the issuer,audequals your ownclient_id,exphas not passed, andnonceequals the value you sent in step 2. The currentid_tokencontains onlysub(user ID),aud,iss,nonce,exp,iat- no name or email; see "Capability boundaries."
access_token is signed with the same key and carries id, username, roles, and org_ids
in its payload; it has no iss / aud and is meant for business backends to identify users and
permissions. Do not hand it to a third party as a standard OIDC token for verification.
Refresh.
POST /tokenwith the form parametersgrant_type=refresh_token,refresh_token, andclient_id. Refreshing rotates: the old refresh token becomes invalid immediately and the response gives a new pair. The RP must replace its local storage atomically and handle the fallback path where "replacement fails and the old token is already invalid" (send the user back to sign in).Sign out. The RP first clears its own local session, then navigates the browser to:
https://accounts.titanides.com/logout
?id_token_hint=<id_token>
&post_logout_redirect_uri=https://titanides.com/
&state=<optional>
id_token_hint is only used to identify which RP this is; an expired one is still accepted.
Clients without an id_token can use client_id instead. post_logout_redirect_uri must be on
the allowlist; otherwise the IdP only clears the session, does not redirect, and returns a
"signed out" page.
This step must be a full-page navigation - the session cookie is HttpOnly + SameSite=Lax,
and only a response from the identity domain itself can clear it. Calling /logout with fetch
looks like it returns 200, but nothing actually happens.
Acceptance checklist
Run through this in order before integration; if any item fails, fix it before moving on:
- The discovery document returns 200 and
issuermatchesOIDC_ISSUERcharacter for character. /jwksreturns a key withkty=EC,alg=ES256, and akid.- Visiting
/authorize(with complete parameters) while signed out → 302 to the login page, with the original request insidecontinue. - After signing in, returning to
/authorize→ 302 toredirect_uriwithcode,state, andiss. - Exchanging the authorization code for tokens succeeds; exchanging the same code again
returns
invalid_grant. id_tokenverifies with JWKS, andnonce/aud/issall match.- Refreshing once succeeds and the old refresh token becomes invalid immediately.
- After signing out, visiting
/authorizeagain requires signing in again (proving the session really was cleared). - Change
redirect_urito an unregistered address;/authorizeshould return 400 directly and must not redirect.
Capability boundaries
The following are things this version deliberately does not do. They are parts your integration must work around or wait for a later version for, not configuration mistakes:
| What is missing | Current impact | Workaround |
|---|---|---|
No userinfo endpoint |
id_token has only sub; the RP cannot get name, email, or avatar |
Treat sub as the local user ID; get profile data from your own business API (such as the admin GraphQL) |
scope does not trim claims |
Requesting profile / email still returns no extra fields |
Send only openid for now; do not rely on other scopes |
| Discovery document fields are incomplete | Missing userinfo_endpoint, scopes_supported, claims_supported, token_endpoint_auth_methods_supported |
If an auto-configured client strictly validates these fields, fill in the endpoints by hand |
| Refresh tokens are stored in plaintext | A database leak equals a refresh token leak; there is also no reuse detection | Protect the database at the key level; shorten REFRESH_TOKEN_EXPIRES_IN |
| No revocation / introspection endpoint | The RP cannot invalidate a single token; disabling an account only takes effect at the next issuance | Sign out via /logout; after an admin disables a user, the access token lives at most until JWT_EXPIRES_IN |
| No consent page | Authorization means consent; the user sees no scope list | Explain it on the RP side before integration |
prompt / max_age / login_hint / ui_locales / response_mode are not supported |
No silent renewal, forced re-authentication, or specific account selection | When re-authentication is needed, /logout first, then start authorization |
| Public clients only | No client_secret; backend services can only use PKCE |
Implement the RP backend with PKCE as well; do not assume a secret exists |
| CORS is fully open | Any origin can call /token directly (though PKCE and an authorization code are still required) |
Narrow the allowed origins at the gateway in production |
OIDC responses have no Cache-Control: no-store |
A shared cache environment may cache token responses | Add that header to /token responses at the gateway |
These boundaries will converge over versions; if your integration depends on one of them, confirm the target version with us first.