Your organization's issuer
Give your organization its own OIDC issuer and signing keys, so your apps accept only tokens minted for your organization; choose the signing algorithm, rotate and retire keys, brand your sign-in pages, and sign people in on a domain you own.
By default every organization on a deployment shares one issuer
(https://<auth host>/api/auth) and one set of signing keys. An app that
checks only the issuer and the signature, which is what most libraries do,
would then also accept a token minted for another organization's app.
Turn on your organization's issuer and your apps get tokens that only your organization's keys verify, under an issuer that is only yours:
https://<auth host>/api/auth/o/<organization id>The organization id never changes, so the issuer never changes either, even if you rename the organization.
What it covers
The issuer applies to the OAuth clients (Apps) your organization owns. Scrydon's own apps, and clients your organization does not own, keep the deployment's issuer.
| Purpose | URL |
|---|---|
| OIDC Discovery | <issuer>/.well-known/openid-configuration |
| Authorization server metadata (RFC 8414) | <issuer>/.well-known/oauth-authorization-server |
| JWKS (your public signing keys) | <issuer>/jwks |
Discovery names the deployment's shared authorize, token, userinfo,
introspection, revocation and end-session endpoints, as OIDC Discovery allows.
Point your app at the Discovery URL and it finds the rest. Every iss
your apps see carries your issuer: ID tokens, access tokens, logout tokens,
error redirects and the authorization response (RFC 9207).
If an organization's issuer is off, or the organization id does not exist, both documents answer 404. They are public, as discovery must be.
Turn it on
Organizations created after this release start with their issuer on. Existing organizations stay on the deployment issuer until an owner or admin turns theirs on, under Settings → Platform → Identity → Issuer.
Turning the issuer on changes the issuer and the keys every one of your apps sees. An app configured against the deployment issuer stops accepting tokens until you give it your organization's Discovery URL. Reconfigure each app, then turn the issuer on. Turning it off reverses the change the same way. Both switches are recorded in the audit log.
Signing algorithm and keys
| Algorithm | Key |
|---|---|
RS256 (default) | RSA 3072-bit |
PS256 | RSA 3072-bit |
ES256 | P-256 |
ES384 | P-384 |
RS256 works with every relying party, Microsoft Entra included. EdDSA, HMAC
and none are not offered.
- Rotation. A key signs for 30 days and stays in your JWKS for 30 more, so tokens it signed keep verifying. Rotate now starts a new key at once.
- Changing the algorithm mints a new key in the new algorithm. The old key stays published until its grace ends.
- Retiring a key (for example after a suspected compromise) removes it from your JWKS at once. Every token it signed stops verifying, which is what a compromise calls for.
- Your private keys are sealed by your organization's secrets custody. With Vault Transit or Azure Key Vault, your organization holds the key that wraps them.
Turning the issuer on, or changing the algorithm, mints a key at once. A new organization, whose issuer starts on, gets its first key when it signs its first token, so its JWKS is empty until then. There is no token to verify before that point. Libraries that fetch the JWKS again when they meet an unknown key id pick the key up on their own.
Sign-in branding
Under Settings → Platform → Identity → Branding, an owner or admin can set what people see when they sign in to one of your organization's apps or on your sign-in domain:
- a display name and a short welcome text (plain text);
- a support link (
https://only); - an accent colour for the main button. It must stand out at least 3:1 against the page in both light and dark themes. The button's label is black or white, whichever reads better, and always reaches at least 4.5:1;
- your organization's logo, which is the logo set on the organization.
Branding is never shown on the deployment's own sign-in page, and it is never markup: no HTML, CSS or script.
Sign in on your own domain
You can have people sign in on a host name you own, such as
login.example.com:
- Verify the domain the host name is, or is under.
- Register the host name under Settings → Platform → Identity → Sign-in domains. The page shows the CNAME target to point it at.
- Create the CNAME record at your DNS provider, then select Check now.
- Ask your deployment's operator to add the host name to the deployment. Scrydon serves it only once both the operator has added it and the CNAME check passes.
On your sign-in domain the sign-in pages and their session cookie belong to that host alone. Your issuer does not change: Discovery sends the browser to your sign-in domain to sign in, and your apps keep exchanging codes with the deployment's token endpoint.
Scrydon re-checks every sign-in domain daily. It stops serving the host when the CNAME no longer points at the target, or when its domain is no longer verified.