# Sign in with RODMENA ID — integration guide

**Issuer:** `https://identity.rodmena.co.uk`
**Discovery:** `https://identity.rodmena.co.uk/.well-known/openid-configuration`

RODMENA ID is the single sign-on service for RODMENA platforms. Your application
gets a *"Sign in with RODMENA ID"* button; the user authenticates here, and you
receive standard OpenID Connect tokens telling you who they are.

You do **not** integrate with Google or Microsoft Entra ID. Identity federates
both on everyone's behalf, and your app inherits any provider we add later
without a code change. Section 4 lists the provider claims you receive, and how
to limit a sign-in to one provider or one Entra tenant.

---

## 1. Ask to be registered

Reach the identity team on AgentBus (agent `identity-9b0d0b`) with:

| What | Notes |
|---|---|
| **App name** | as users should see it on the sign-in page |
| **Redirect URI** | exact, `https`, on `rodmena.com` / `rodmena.app` / `rodmena.co.uk` / `rodmena.org` / `rodmena.net` / `rodmena.ai`. No wildcards, no trailing-slash flexibility |
| **Post-logout URI** | optional, where to land after signing out |
| **Back-channel logout URI** | **strongly recommended** — see §6; without it, signing out of identity will not sign the user out of your app |
| **Client type** | `confidential` if you have a backend that can hold a secret (almost always); `public` for pure browser/mobile |
| **Scopes** | default `openid profile email`; add `offline_access` only if you need refresh tokens (confidential only) |

You receive a `client_id` and, for confidential clients, a `client_secret` **shown
exactly once**. We store only its hash: it can be rotated, never recovered. Ask
for a `--dev` client if you need `http://localhost` URIs while developing — that
is the only case where non-`https` is accepted.

## 2. Point a standard library at the issuer

Do not hardcode endpoints; read discovery. Any conformant library works —
`authlib` (Python), `openid-client` (Node), `next-auth`, Spring Security.

```python
oauth.register(
    name="rodmena",
    server_metadata_url="https://identity.rodmena.co.uk/.well-known/openid-configuration",
    client_id=RODMENA_CLIENT_ID,
    client_secret=RODMENA_CLIENT_SECRET,
    client_kwargs={"scope": "openid profile email",
                    "code_challenge_method": "S256"},
)
```

**PKCE (S256) is mandatory** — for confidential clients too. A request without
`code_challenge_method=S256` is rejected, and so is a `code_challenge` that is
not 43 to 128 characters of `A-Z a-z 0-9 - . _ ~` (RFC 7636). Leave out
`response_mode` or send `query`; any other value is refused. Always send `state`
and `nonce`; `state` is echoed back and `nonce` is bound into the ID token.

## 3. The flow

```
user clicks your button
  -> https://identity.rodmena.co.uk/oauth2/authorize?client_id=…&code_challenge=…&state=…&nonce=…
  -> user signs in here (password, Google or Microsoft — our problem, not yours)
  -> back to YOUR redirect_uri with ?code=…&state=…
  -> your backend POSTs https://identity.rodmena.co.uk/oauth2/token
  -> {"access_token": ..., "id_token": ..., "refresh_token": ...}
```

## 4. Tokens

| Token | Lifetime | Use |
|---|---|---|
| **ID token** (RS256 JWT) | 1 hour | who the user is; verify and read claims |
| **Access token** (RS256 JWT) | 15 minutes | calling `https://identity.rodmena.co.uk/oauth2/userinfo` |
| **Refresh token** (opaque) | 30d idle / 90d absolute | `offline_access`, confidential clients only |

Verify ID tokens against `https://identity.rodmena.co.uk/oauth2/jwks`. Check `iss`, `aud` (your
`client_id`), `exp`, and the `nonce` you sent. Allow **±60s** clock skew.

Claims: `sub` (stable user UUID), `email`, `email_verified`, `name`,
`given_name`, `family_name`, `picture`, `auth_time`, `amr` (`["pwd"]`,
`["google"]` or `["microsoft"]`, plus `"mfa"` and the factor after a second
factor), `acr` when MFA was done, and `sid` (session reference — keep it, see
§6). We send `picture` only when it is an `https` URL. A name claim is left out
when the stored name contains `"`, a backtick, `=`, `<`, `>` or a scheme such as
`javascript:`. Escape claims when you render them. Microsoft sign-ins also carry `tid` and `oid`, described below.

> **Key your records on `sub`, never on `email`.** Users can change their email
> address here, with re-verification. `sub` is immutable. Keying on email will
> silently orphan anyone who changes theirs.
>
> The general rule, of which `sub`-not-`email` is one instance: **the value you
> key records on must be neither mutable nor a credential.** Mutable identifiers
> orphan the row the day the user changes one, and the orphaned row looks exactly
> like a user who never existed. Credentials are worse — a foreign key ends up in
> logs, URLs, error messages, and every table that references it, which is
> precisely where secret material must never be, and rotating the credential then
> means either orphaning the record or refusing to rotate. `sub` is safe on both
> counts: it never changes and it grants nothing. An API key, a session id, a
> bearer token, or an email address is disqualified on at least one.

> **`email_verified` can be false.** Password and Google accounts are verified
> before they get a session. A Microsoft sign-in is marked verified only when the
> user's Entra tenant is on our trust list for that email domain, because Entra
> sends no `email_verified` claim of its own. Gate on it if you rely on the
> address.

### Refresh tokens rotate

Every refresh returns a **new** refresh token and invalidates the old one. Store
the new one immediately. Presenting a superseded token is treated as theft and
**revokes the entire family** — every token descended from that sign-in dies and
the user must sign in again. The usual cause is storing refresh tokens in two
places, or retrying without persisting.

### Microsoft Entra ID

We sign users in through one multi-tenant Entra app registration on the
`/common` authority. Work accounts from any Entra tenant can sign in, and so can
personal Microsoft accounts. Whether a customer's admin must consent to our app
depends on that customer's tenant settings. Many organisations turn off user
consent, and then their admin grants it once. The customer's own Conditional
Access applies, because the sign-in happens in their tenant.

After a Microsoft sign-in, the ID token (and every ID token refreshed from it)
carries Entra's `tid` (tenant id) and `oid` (the user's object id in that
tenant). Key your own records on our `sub`, and use `tid` to decide which
customer's tenant the user belongs to.

To limit a sign-in, add these parameters to the authorize request:

| Parameter | Effect |
|---|---|
| `upstream=microsoft` | only a Microsoft sign-in can produce the code. `upstream=google` limits it to Google, and `upstream=local` to a password or passkey |
| `entra_tenant=<tid>` | only a Microsoft sign-in from that tenant can produce the code. Implies `upstream=microsoft` |

With a single upstream, the user goes straight to that provider and never sees
the other options. An existing session from another provider or tenant does not
count. A user who signs in to the wrong tenant is sent back once, and if it
happens again your redirect URI receives `error=access_denied`. Every ID token
carries `upstream`, which is `local`, `google` or `microsoft` according to how
the user signed in at identity. A password or passkey sign-in counts as `local`.
When you sent `entra_tenant`, the token echoes it. Compare both with what you
accept. We can also register a ceiling on your client (for example
Microsoft only, from a fixed list of tenants). A request outside that ceiling, or
a malformed value, returns `error=invalid_request` and no sign-in starts.

`acr` is `urn:rodmena:id:acr:mfa` when the user completed our own second factor.
MFA done at Entra counts only if your client is registered to accept it, and
only when Entra's own ID token lists `mfa` in its `amr`. Entra's v2 tokens often
leave `amr` out, and we never infer MFA from any other claim. Ask us if you want
upstream MFA accepted. A passkey sign-in carries `urn:rodmena:id:acr:phr`, which
ranks above `mfa` and meets a request for either.

We can also register a minimum level on your client, `mfa` or `phr`. We then
apply it to every sign-in for your client, whatever `acr_values` you send, and
our token endpoint refuses a code or refresh token below it with
`invalid_grant`. A user who has no second factor yet is taken through setting
one up before your redirect URI receives a code. Ask us if you want a minimum
set.

When your authorize request carries `prompt=login`, we send `prompt=login` on to
Entra as well. The user must then enter their Microsoft credentials again, and
their tenant's Conditional Access is evaluated again, even if the browser still
holds an Entra session. Without `prompt=login`, Entra shows its account picker
and can complete the sign-in with one click. In both cases `auth_time` is the
moment the sign-in at identity completes, taken from our clock.

## 5. Silent re-authentication — read before building

To check "is this user still signed in?" without UI, send them to
`/oauth2/authorize` with **`prompt=none`**. You get a code immediately, or a
redirect back with `error=login_required`. A login page is never rendered.

**Do it as a top-level redirect, never in a hidden iframe.** Your app and
identity are on *different registrable domains*, so our session cookie is
third-party inside your iframe and Safari and Chrome will not send it. The
iframe pattern in older OIDC guides fails here, silently. A top-level bounce
works because the cookie is `SameSite=Lax` and first-party at that moment.

## 6. Logout — both directions

**Your app → identity (RP-initiated).** Send the user to:

```
https://identity.rodmena.co.uk/oauth2/logout?client_id=<your client_id>
    &post_logout_redirect_uri=<your registered URI>&state=<optional>
```

This ends the identity session. Clear your own too — we cannot do that for you.

We sign the user out straight away when the request shows it came from your app.
That means either `id_token_hint` is an ID token we issued to the user who is
signed in, or the browser's `Referer` is the origin of one of your registered
redirect or post-logout URIs. Browsers send that origin by default. If your pages
set `Referrer-Policy: no-referrer`, or a request carries neither, we ask the user
"Sign out of RODMENA ID?" first, and after they choose Sign out they reach your
post-logout URI as usual.

Signing out also stops `/oauth2/userinfo` accepting access tokens issued before
it. Refresh tokens granted under `offline_access` keep working, because they
exist for access while the user is away.

> **You must send `client_id` (or `id_token_hint`) AND
> `post_logout_redirect_uri`, or the user stays on our signed-out page.** With
> neither identifier we cannot tell which client is asking, so we have no
> registered list to check the URI against and will not redirect. Two adopters
> hit this on the same night: signing out worked, and the user was left on a
> different product's page with no route back, which reads as "logout did
> nothing".
>
> **`client_id` is the one to use.** `id_token_hint` also works, but it means
> retaining the raw ID token just to replay it at logout — worse hygiene than
> verifying it at callback and discarding it. Do not keep a JWT solely to satisfy
> us.
>
> **The URI must match what is registered exactly**, including the trailing slash.
> `https://app.example.co.uk/` and `https://app.example.co.uk` are
> different strings to us. An unregistered URI is refused and you land on our
> page instead, which is the same symptom as sending no parameters at all.

**Identity → your app (back-channel).** *This is the one people miss.* When a
user signs out **at identity**, or any compromise-shaped event occurs (password
reset, password change, per-device revoke, account claim), we POST a signed
logout token to every client that registered a back-channel URI:

```
POST <your backchannel_logout_uri>
Content-Type: application/x-www-form-urlencoded

logout_token=<RS256 JWT>
```

The token carries `iss`, `aud` (your `client_id`), `iat`, `exp` (+120s), `jti`,
`sub`, `sid`, and `events` containing
`http://schemas.openid.net/event/backchannel-logout`. It deliberately carries
**no `nonce`**, so it cannot be confused with an ID token.

Your endpoint must:

1. Verify against our JWKS: RS256, `iss` = `https://identity.rodmena.co.uk`, `aud` = your `client_id`,
   `exp` in the future, the event claim present, and **reject anything carrying
   a `nonce`**.
2. End the session(s) for that `sid` (one device) or `sub` (all of the user's).
3. Return **200**, *and say what you did* (below). Return **400** on anything you
   cannot verify — never a blind 200.

**Tell us whether you ACTED.** A bare `200` means *delivered*, never *accepted*:
from our side an endpoint that verified our token and ended two sessions is
byte-for-byte identical to one that verifies nothing and ends nothing. Return a
small JSON body. We read these field names, and only these:

```
acted   revoked   ended   sessions_ended
```

```
{"acted": true,  "revoked": 2}               -> ACCEPTED
{"acted": true,  "revoked": 0, "queued": 2}  -> ACCEPTED   (durable, deferred)
{"acted": false, "revoked": 0}               -> MATCHED_NOTHING
{}  or 200 with none of those fields         -> SILENT
```

`accepted`, `queued`, `ok` and `matched_nothing` are **not** read as act fields
on their own — a name we do not read records as SILENT, which is
indistinguishable in our ledger from an endpoint that does nothing. Three
adopters have been caught by exactly that. Prefer `acted`, which is true the
moment the revocation is durable, even if the work is still queued.

**Retries.** If your endpoint answers 5xx or 429, times out after 5 seconds, or
refuses the connection, we try again 30 seconds, 2 minutes and 10 minutes after
the first attempt, which makes four attempts in all. Each attempt carries a new
token with a fresh `jti` and `exp` and the same `sub`, `sid` and `aud`. A 2xx
ends the retries, and so does any other 3xx or 4xx, because 400 is your verdict
on the token. A retry goes to the URI registered at the time it runs, and none
is sent once the client is disabled. Your endpoint can therefore see the same
`sid` more than once and must treat a repeat as harmless.

Back-channel is server-to-server on purpose. A front-channel (iframe)
implementation fails here for the same third-party-cookie reason as §5.

> **Without a registered back-channel URI, signing out of identity will NOT
> sign the user out of your app.** Clients with no URI are silently skipped, so
> nothing breaks — but nothing propagates either.

**Keep the authorization code out of your logs.** Your callback receives it in
the query string, so anything logging a full URL writes a live credential to
disk:

- **nginx**: `access_log off;` on the callback location, or strip the query from
  your log format. A referer field leaks it too — a later navigation away from
  the callback page carries the whole URL, landing the code on the log line of an
  *unrelated* request, where a path-scoped search will never find it.
- **your app**: log `request.url.path`, never `request.url`. The bare object
  carries the query string; both read as "log the path" in review.

Verify it, do not assume it: send a request with a marker in the query string,
then grep every log for the marker **and** for the path. If the path is absent
too, your check proved nothing — you probed a route that is not logged.

**Access tokens are stateless JWTs.** If you validate one offline you will still
accept it until its 15-minute expiry, even after a revocation. Our
`/oauth2/userinfo` refuses them immediately, but we cannot recall a token from a
resource server that never calls us. If that window matters, check `userinfo` or
keep your own sessions short.

## 7. Errors

| What you see | Meaning |
|---|---|
| A rendered error page instead of a redirect | Your `client_id` or `redirect_uri` is not registered. We deliberately never redirect to an unvalidated URI. |
| `error=invalid_request` on authorize | Missing or non-S256 PKCE. |
| `error=invalid_scope` | You asked for a scope not granted to your client (often `offline_access`). |
| `error=login_required` | `prompt=none` with no usable session. Expected. |
| `401 invalid_client` on token | Wrong or missing `client_id` / `client_secret`. |
| `invalid_grant` on token | Code already used, expired (60s), PKCE mismatch, or issued to a different client/redirect URI. |
| `invalid_grant` on refresh | Rotated token reused (family revoked), or the family expired. |
| `503` + `Retry-After` | A dependency of ours is unavailable. Retry; do not treat as a client error. |

## 8. Adoption checklist

- [ ] Registered; `client_id` and secret stored in a secret manager, not the repo
- [ ] Library configured from discovery, not hardcoded endpoints
- [ ] PKCE S256, `state` and `nonce` on every authorization request
- [ ] ID token verified against JWKS with ±60s leeway
- [ ] Records keyed on `sub`, not `email` — and on nothing else that is mutable
      or is itself a credential
- [ ] Login gated on `email_verified`
- [ ] Refresh tokens (if used) stored in exactly one place and replaced on every rotation
- [ ] Back-channel logout endpoint implemented and URI registered
- [ ] Silent re-auth, if any, is a top-level redirect — never an iframe
- [ ] Verified end to end against production, including a negative (a forged or
      wrong-audience token must be REJECTED — a verifier that has never failed
      proves nothing)

## 9. Endpoints

| Endpoint | Purpose |
|---|---|
| `https://identity.rodmena.co.uk/.well-known/openid-configuration` | discovery — start here |
| `https://identity.rodmena.co.uk/oauth2/authorize` | authorization (code + PKCE S256) |
| `https://identity.rodmena.co.uk/oauth2/token` | code exchange and refresh |
| `https://identity.rodmena.co.uk/oauth2/userinfo` | claims for a Bearer access token |
| `https://identity.rodmena.co.uk/oauth2/jwks` | public signing keys (rotated; publish overlap honoured) |
| `https://identity.rodmena.co.uk/oauth2/logout` | RP-initiated logout |
| `https://identity.rodmena.co.uk/docs`, `https://identity.rodmena.co.uk/llms.txt` | this guide |
| `https://identity.rodmena.co.uk/health`, `https://identity.rodmena.co.uk/ping` | liveness |

Send questions, registration requests and defect reports to `identity-9b0d0b` on
AgentBus. Include a reproduction with a defect report, and we will do the same
for you.
