System design · Concept 12
Identity and Secrets
Authentication vs authorization, OAuth 2.0 and OIDC flows, access, refresh and ID tokens, scopes and roles, workforce vs customer identity, workload identity without stored secrets, secrets stores and rotation, least privilege and multi-tenant concerns.
In short
- Authentication says who; authorization says what
- Auth code + PKCE for apps, client credentials for services
- Validate
iss,aud,exp; require a scope or role - Workload identity and federation instead of stored secrets
- A secrets store for the rest: cache, overlap, alert
Every request in a system answers three questions: who is the user, which app is calling, and what are they allowed to do. An identity provider answers the first two with tokens, your API answers the third, and a secrets store holds the few secrets you can't get rid of. The goal for a new design is simple to say: no secrets in code or config, and every identity holds only the access it needs.
Authentication vs authorization
- Authentication (authn) proves who is calling: a user, a service, or a user through a client app. The output is an identity, usually inside a signed token. A failure is 401 Unauthorized (badly named: it means "unauthenticated").
- Authorization (authz) decides whether that identity may do this action on this resource. A failure is 403 Forbidden, or 404 when you don't want to reveal that the resource exists.
Outsource authentication to an identity provider (IdP): passwords, MFA, account recovery and federation are hard to get right and easy to get catastrophically wrong. Authorization stays mostly in your code, because only your service knows that order 42 belongs to Alice.
Tokens and the vocabulary
OAuth 2.0 is about delegated access: a client app gets a token to call an API. OpenID Connect (OIDC) adds sign-in on top: a standard ID token and user info. Most modern IdPs speak both.
| Term | What it is | Who reads it |
|---|---|---|
| ID token | A JWT saying who signed in and how. Its aud is the client app | The client app only. Never send it to an API as a bearer token |
| Access token | A short-lived credential for one API: its aud names that API | The API (the client treats it as opaque) |
| Refresh token | A longer-lived credential the client trades for new access tokens | The IdP only |
| Scope | What a client app may do on a user's behalf, e.g. orders.read. In the scope claim (Entra ID uses scp) | The API |
| Role / permission | What a principal is or may do, e.g. orders.approver. Usually a roles or permissions claim | The API |
Issuer (iss) | The IdP (and tenant) that signed the token | The API, to check it trusts the signer |
Subject (sub) | A stable ID for the principal, unique within that issuer | The API, as the user key |
Access tokens are usually JWTs validated locally: fast, but they can't be revoked before they expire. Keep them short (5-60 minutes) and let refresh tokens carry the session. Some IdPs issue opaque access tokens instead, which the API checks through an introspection endpoint: revocable, at the cost of a call per request (or a short cache). Many IdPs rotate refresh tokens on each use and revoke the whole chain if an old one is replayed.
Which flow for which caller
| Caller | Flow | Client type |
|---|---|---|
| SPA (React, Angular) or mobile app | Authorization code + PKCE | Public: can't keep a secret |
| Server-rendered web app or BFF | Authorization code (+ PKCE) | Confidential: authenticates to the IdP |
| Worker, timer, daemon, service-to-service (no user) | Client credentials, ideally with a workload identity instead of a stored secret | Confidential |
| API calling another API as the user | Token exchange (Entra ID calls its version on-behalf-of) | Confidential |
| CLI or TV without a browser | Device authorization (device code) | Public |
PKCE (Proof Key for Code Exchange) protects public clients. The app makes a random code_verifier, sends its hash as the code_challenge when it redirects to the IdP, and must present the original verifier when it redeems the code. An attacker who intercepts the code can't redeem it.
1. App → IdP /authorize?response_type=code&client_id=spa&scope=openid orders.read
&redirect_uri=...&state=xyz&code_challenge=<SHA-256(verifier)>&code_challenge_method=S256
2. User signs in (MFA, SSO); IdP redirects back with ?code=abc&state=xyz
3. App → IdP POST /token grant_type=authorization_code&code=abc&code_verifier=<verifier>
4. IdP → App { id_token, access_token (aud: orders API), refresh_token }
The implicit flow (tokens in the redirect URL) is deprecated, and the password grant (the app collects the user's password) bypasses MFA and SSO. Don't use either for new work. For SPAs, a BFF that keeps tokens server-side and gives the browser an HttpOnly cookie is the safest option for high-value apps (see Frontend Architecture).
Validating an access token
- Signature, with the issuer's public keys from its OIDC discovery document (
jwks_uri). Keys rotate, so fetch and cache them; never pin one. - Algorithm: accept only the ones you expect. Never let the token pick, and never accept
none. issis an issuer you trust;audis this API;expandnbfwith a little clock skew.- Then authorize: scope or role, then your own rules.
import { createRemoteJWKSet, jwtVerify } from 'jose';
// The library caches the keys and refetches when the IdP rotates them.
const jwks = createRemoteJWKSet(new URL('https://idp.example.com/.well-known/jwks.json'));
export async function authenticate(bearer: string) {
const { payload } = await jwtVerify(bearer, jwks, {
issuer: 'https://idp.example.com/',
audience: 'https://api.example.com/orders', // this API, not the SPA
algorithms: ['RS256'],
}); // throws on a bad signature, issuer, audience, exp or nbf
return { userKey: `${payload.iss}|${payload.sub}`, scopes: String(payload.scope ?? '').split(' ') };
}
Key users by issuer + subject, never by email or username: those change, get reused, and on some IdPs can be edited by the user. (Entra ID's sub differs per app; use its oid claim when several apps must agree on who a user is.)
Scopes, roles and your own rules
| Scope (delegated) | Role / app permission | |
|---|---|---|
| Says | This client app may act for the signed-in user for this purpose | This principal (a user, or a service with no user) is something |
| Granted by | User or admin consent to the client | An admin assigns users, groups or services |
| Typical use | The SPA asks for orders.read | Staff get orders.approver; the reporting job gets orders.read.all |
| Effective access | The intersection of what the client was granted and what the user may do | What the role says |
A scope is not permission for the user. orders.read means "the SPA may read orders for this user"; your API still decides which orders that user may see.
GET /orders/{id}
caller = authenticate(token) -- 401 if the token is bad
require "orders.read" in caller.scopes -- 403: this client may not read orders
order = db.find(id)
require order.ownerKey == caller.userKey -- 403 (or 404): not this user's order
or "orders.admin" in caller.roles
- Authenticated is not authorized. An API that only checks signature, issuer and audience accepts every client the IdP will issue a token to. Some IdPs do that by default: Entra ID, for example, lets any app in the tenant get an app-only token for your API, with no roles in it. Require a scope or role on every endpoint, and restrict which clients may get tokens for the API at all.
- Keep separate roles for people and for services, so a job can't pass as a user role or the other way round.
- Don't authorize on group lists in tokens. Tokens have size limits (Entra ID drops the
groupsclaim when a user is in more than 200 groups). Map groups to a few app roles in the IdP and check those.
Calling another API as the user
The SPA calls the Orders API with a token whose aud is the Orders API. Orders now needs the Inventory API, which applies per-user rules and audits who reserved stock.
- Forwarding the incoming token is wrong. Its audience is Orders, so a correct Inventory API rejects it, and an API that accepts tokens meant for someone else can be replayed against.
- Token exchange (OAuth token exchange, RFC 8693; Entra ID's on-behalf-of flow) trades the incoming token at the IdP for a new token whose audience is Inventory and that still represents the user. Supported by Entra ID, Keycloak and Okta among others; check your IdP.
- Or use the service's own identity (client credentials) and pass the user ID as data. Simpler, but Inventory must fully trust Orders to have checked the user. Fine inside one trust boundary; not when the downstream service enforces per-user rules itself.
Workforce vs customer identity
| Workforce (staff) | Customer (CIAM) | |
|---|---|---|
| Who | Employees, contractors | Your users: millions, self-service |
| Sign-in | Corporate SSO, MFA, device and location policies | Email or phone, social logins, passkeys, branded pages |
| Lifecycle | HR joiner/mover/leaver, provisioning with SCIM | Self sign-up, profile editing, account deletion, consent |
| Services | IAM Identity Center / Entra ID / Cloud Identity or Google Workspace / Okta | Cognito / Entra External ID / Identity Platform or Firebase Authentication / Auth0 or Keycloak |
Don't put customers in the company directory, and don't build the company's admin portal on the customer pool. Separate pools give separate policies, separate blast radius and separate audits.
Multi-tenant identity
In B2B SaaS, every request also carries which tenant:
- Take the tenant from the token, or check the user's membership of the tenant in the URL. Never trust a tenant ID from a path, header or body on its own: changing
/tenants/a/to/tenants/b/is the classic cross-tenant leak. - Filter every query by tenant, ideally enforced below the app code (row-level security, or a repository layer that requires a tenant ID).
- Validate the issuer per tenant when customers sign in through their own IdP: accept only the tenants or issuers you've onboarded, not "any valid token from this provider".
- Roles are per tenant. An admin of tenant A is nobody in tenant B.
- IdPs model tenants differently: Entra ID multi-tenant apps (
tidclaim), Identity Platform tenants, Auth0 Organizations, Keycloak realms, or one Cognito user pool per tenant. Pick one per design and say why.
Workload identity: services without stored secrets
A service needs credentials too. The bad answer is a client secret or access key in config. The good answer is an identity the platform issues to the running workload, with short-lived credentials it rotates for you.
| Where the code runs | AWS | Azure | Google Cloud |
|---|---|---|---|
| On the platform (VMs, containers, functions) | IAM role (instance profile, ECS task role, Lambda execution role) | Managed identity (system- or user-assigned) | Service account attached to the resource |
| Kubernetes pods | EKS Pod Identity, or IAM roles for service accounts (IRSA) | Microsoft Entra Workload ID on AKS | Workload Identity Federation for GKE |
| Outside the cloud (CI, other clouds, on-premises) | IAM OIDC identity provider + AssumeRoleWithWebIdentity; IAM Roles Anywhere for X.509 | Federated identity credential on an app registration or user-assigned managed identity | Workload Identity Federation |
Workload identity federation removes the last stored secret. A GitHub Actions job (or a Kubernetes pod, or a workload in another cloud) already holds a signed OIDC token from its own platform. The cloud is configured to trust that issuer, and to accept only tokens whose claims match, such as one repo and one branch or environment. The job exchanges the token for short-lived cloud credentials. Nothing to store, nothing to rotate. Outside the big clouds, SPIFFE/SPIRE issues workload identities, and HashiCorp Vault can authenticate workloads by their platform identity.
- Use the SDK's default credential chain: the AWS SDKs' default credential provider chain,
DefaultAzureCredentialon Azure, Application Default Credentials on Google Cloud. The same code signs in as the developer locally and as the workload identity when deployed. In production, pin it to the workload identity so it fails fast instead of silently picking up something else. - One identity per service per environment. A dev identity must never have rights in production, and a shared identity makes audit logs useless.
- Block the old way: avoid IAM users with access keys on AWS, block service account key creation with an organization policy on Google Cloud, and disable key-based (local) auth on Azure data services once apps use their identities.
- Revocation isn't instant. Credentials already issued stay valid until they expire. Azure caches managed identity tokens for up to about 24 hours, so a group change can take that long to bite; AWS lets you revoke a role's active sessions. In an incident, stop or isolate the workload rather than only editing its permissions.
Secrets stores
What's left after workload identity: third-party API keys, webhook signing secrets, the odd password for a system that can't use your identities. They go in a secrets store: AWS Secrets Manager, Azure Key Vault, Google Cloud Secret Manager, or HashiCorp Vault. The service reads them at runtime with its own identity, so the store's access policy is the only list of who can read what.
What should never be a secret in the first place
- Database and queue credentials when the service supports identity auth: RDS IAM authentication, Microsoft Entra auth for Azure SQL and PostgreSQL, Cloud SQL IAM database authentication. Or let Vault issue dynamic database credentials that expire on their own.
- Cloud credentials for your own services: that's what workload identity is for.
- Anything shipped to a browser or app: a SPA's client ID, a publishable key, a public API key. If it's in the bundle, it's public; design so it doesn't need to be secret (restrict it by origin, scope it to publishable actions).
- Private keys your code signs with: keep them in a key management service (AWS KMS, Key Vault keys or Managed HSM, Cloud KMS, Vault's transit engine) and ask it to sign or decrypt. The private key never leaves.
Getting secrets into apps
- Load at startup, or cache with a TTL. Secrets stores rate-limit and charge per call; fetching per request adds latency and makes the store a hard dependency of every request.
- Platform integrations inject them as env vars or files: ECS task definitions reference Secrets Manager secrets, App Service and Container Apps have Key Vault references, Cloud Run mounts Secret Manager secrets. On Kubernetes, the Secrets Store CSI Driver or External Secrets Operator syncs them from any of the stores. Plain Kubernetes Secrets are only base64-encoded, so turn on encryption at rest and restrict who can read them.
- Know each consumer's refresh delay. "The new version is in the store" is not "every instance uses it". Azure App Service, for example, re-reads Key Vault references every 24 hours unless the app restarts.
- Scan for leaks: secret scanning and push protection in the repo, and scrub
Authorizationheaders and tokens in URLs out of logs.
Rotation
The best rotation is having nothing to rotate. For the rest:
- Overlap, then revoke. Create the new credential while the old one still works (many providers allow two active keys), publish it as a new version, wait until every consumer has picked it up, check the old one is unused, then revoke it.
- Automate it: Secrets Manager runs rotation functions on a schedule; Key Vault rotates keys by policy and emits near-expiry events for secrets; Secret Manager sends rotation reminders to Pub/Sub for your function to act on; Vault's dynamic secrets expire by lease.
- Set expiry dates and alert before they pass. An expired certificate is a classic self-inflicted outage.
Least privilege in practice
- Grant data actions on specific resources, not admin roles on the account, subscription or project. A role that can read account keys or reset credentials is effectively full data access.
- Scope narrowly: one resource beats a group of resources, which beats the whole account.
- No standing admin for humans: time-bound, approved elevation, logged.
- Pipelines that create role assignments may assign only the roles they need, not "Owner".
- Review unused permissions regularly, from your cloud's access analysis tools or its audit logs, and remove them.
Common mistakes
| Mistake | Why it hurts | Do this instead |
|---|---|---|
Secrets in code, .env files, images or pipeline variables | They leak through git history, logs, screenshots and laptops | Workload identity; a secrets store for the rest |
| A stored client secret or access key for a service that runs on the cloud | A secret to rotate, store and leak | The platform's workload identity, or federation |
| Sending the ID token to the API | Wrong audience; it describes a sign-in, not access | An access token whose aud is the API |
| The API checks only "is authenticated" | Every client the IdP serves gets in | Scope or role per endpoint, plus your own rules |
| Users keyed by email | Emails change and get reused | Issuer + subject |
| Forwarding a user's token to another API | Wrong audience; enables replay | Token exchange, or the service's own identity |
| Tenant ID taken from the URL | One edited URL reads another customer's data | Tenant from the token or a membership check; filter every query |
| Long-lived access tokens "so users stay signed in" | Can't be revoked; a stolen token works for days | Short access tokens, rotated refresh tokens, a BFF for high-value apps |
| Revoking the old key at the same moment as publishing the new one | Consumers still holding the old one fail | Overlap, wait for consumers, then revoke |
| Admin roles for an app "to get it working" | One compromised app owns everything | Data roles on specific resources |
Cloud mappings
Side note
| Concern | AWS | Azure | Google Cloud | Other |
|---|---|---|---|---|
| Workforce identity | IAM Identity Center | Entra ID | Cloud Identity / Google Workspace | Okta |
| Customer identity | Cognito | Entra External ID | Identity Platform, Firebase Authentication | Auth0, Keycloak |
| Workload identity | IAM roles | Managed identities | Service accounts | SPIFFE/SPIRE, Kubernetes service accounts |
| Federation from CI and other clouds | IAM OIDC identity providers, IAM Roles Anywhere | Federated identity credentials | Workload Identity Federation | Vault JWT/OIDC auth |
| Permission model | IAM policies | Azure RBAC role assignments | IAM allow policies (role bindings) | Vault policies |
| SDK credential chain | Default credential provider chain | DefaultAzureCredential | Application Default Credentials | |
| Secrets store | Secrets Manager | Key Vault | Secret Manager | HashiCorp Vault |
| Keys and signing | KMS, CloudHSM | Key Vault keys, Managed HSM | Cloud KMS, Cloud HSM | Vault transit engine |
| Passwordless database auth | RDS IAM authentication | Entra auth for Azure SQL / PostgreSQL | Cloud SQL IAM database authentication | Vault dynamic credentials |
How to say it in a design review
"Staff sign in through our workforce IdP and customers through a separate customer identity service, both with OIDC: authorization code with PKCE for the SPA and the mobile app. The Orders API validates issuer, audience and expiry, requires a scope or role on every endpoint, and then checks that the user owns the order, with the tenant taken from the token. Inventory needs the user, so Orders uses token exchange; everything else calls with its own identity. Every service runs as a workload identity with data roles on its own resources, CI deploys through federation, and the only stored secret, the payment provider's key, lives in the secrets store with expiry alerts and overlap rotation."
Checklist
- An IdP for authentication; authorization in the API: scope or role per endpoint, then resource rules
- Auth code + PKCE for SPAs and mobile; client credentials (secretless) for services; no implicit or password grant
- APIs validate signature, algorithm,
iss,aud,exp; users keyed by issuer + subject - Short-lived access tokens, rotated refresh tokens; token exchange where downstream needs the user
- Workforce and customer identities separated; tenant from the token and enforced in every query
- Workload identity per service per environment; federation for CI; key-based auth blocked
- Secrets store for what's left: cached reads, expiry alerts, overlap rotation, scanning
- Least privilege: data roles on specific resources, no standing admin, unused permissions reviewed
Practise this concept
In the app: a short video and a 12-question concept check. Free with a GitHub account.
Open in the app