The broker portal is getting a new login page, and a sprint is almost over. A developer proposes the quickest path: put a username and password form on the portal itself, post the broker's password from the portal backend to the identity provider, and receive tokens in the response. Two calls, no redirects, no new screens to style. Nothing about it looks dangerous; the connection is TLS, and the portal is the insurer's own application.
That proposal is a retired design, and the reasons it was retired are the content of this page. The portal would see the broker's password, so every portal bug becomes a password leak. The identity provider could not add a passkey or a phishing-resistant step, because the portal's form only knows passwords. And nothing would distinguish "the broker signed in" from "the portal obtained a token". Standard (RFC 9700, OAuth 2.0 Security Best Current Practice, read 2026-11-18): "The resource owner password credentials grant ... MUST NOT be used." The rest of this page builds what replaces it, for the broker, for the services, and for the underwriting agent that needs a token for one task.
OAuth and OpenID Connect, in plain words#
Start with a question the previous pages left open: where does the broker's access token come from? Someone must check the broker, then hand the portal a token that the quote API will accept. The insurer does not want every application to check passwords itself. So one service, the identity provider, does the checking, and applications receive tokens from it.
OAuth is the framework for that hand-over: a program obtains a limited, revocable permission to call a service, issued by a server both trust. It names four roles. Standard (RFC 6749, read 2026-11-18): the resource owner is "An entity capable of granting access to a protected resource"; the resource server is "The server hosting the protected resources"; the client is "An application making protected resource requests on behalf of the resource owner"; the authorization server is "The server issuing access tokens to the client after successfully authenticating the resource owner". In the example: the broker (or the insurer, for its own data) is the resource owner, the quote API is the resource server, the portal backend svc-portal-bff is the client, and https://idp.insurer.example is the authorization server.
OAuth answers "may this client call this API?". It does not tell the client who the person is. OpenID Connect (OIDC) adds that: it runs on top of OAuth and returns an ID token, a signed statement for the client about who authenticated, when and how. A tiny example: the portal asks for scope=openid quotes.read quotes.submit; the word openid turns the OAuth request into an OIDC login. Standard (OIDC Core 1.0, errata set 2): "OpenID Connect requests MUST contain the openid scope value".
A scope is a coarse permission name carried in the request and the token (quotes.read). It says what kind of thing the client may do, never which record. Consent is the resource owner agreeing that this client may have those scopes. A tiny example: a third-party analytics app asking a broker for quotes.read shows a consent screen; the insurer's own portal, a first-party client, shows none in the example. Consent is about delegating access, not about proving who you are.
Before AI. A backend engineer has seen both halves. Applications that bound to LDAP with the user's password were the "every app checks passwords" world this replaces. SAML single sign-on, with an identity provider and service providers, was the enterprise answer for browsers; Spring Security's OAuth client and resource server modules are the same split in today's form. The agent does not change the flows. It adds a principal that needs its own token and, sometimes, a narrower token derived from a person's.
The smallest exchange: an authorization request with PKCE#
The replacement for the password form is a redirect. The portal sends the broker's browser to the identity provider with a request; the broker signs in there; the identity provider sends the browser back with a one-time authorization code, which the portal's backend trades for tokens over a direct back-channel call. A tiny example: code=code-2d43ffb6b742 in the redirect back to https://portal.insurer.example/callback.
A code in a browser URL can leak: through logs, a malicious app registered for the same redirect, or an injected page. PKCE (Proof Key for Code Exchange) makes a leaked code useless. Before redirecting, the portal creates a random secret, the code_verifier, keeps it on the server, and sends only its hash, the code_challenge. At the token call it presents the verifier; the identity provider hashes it and compares. A thief with the code but not the verifier gets invalid_grant.
Standard (RFC 7636, read 2026-11-18): the verifier is a "high-entropy cryptographic random STRING using the unreserved characters", 43 to 128 characters; S256 means code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier))); "If the client is capable of using "S256", it MUST use "S256"". RFC 9700 tightens it: "Public clients MUST use PKCE", for confidential clients it "is RECOMMENDED", and "Currently, S256 is the only such method" that does not expose the verifier.
The example computes S256 for real with hashlib, and checks itself against the RFC's own test vector before trusting its output. This snippet demonstrates both; it proves the hash is computed as RFC 7636 says, not that any identity provider accepts it.
import oauth
from clock import START_EPOCH_S as NOW
print(oauth.pkce_challenge(oauth.RFC7636_VERIFIER)["code_challenge"] == oauth.RFC7636_CHALLENGE)
trace = oauth.auth_code_trace(NOW)
print("verifier: ", trace["code_verifier"])
print("challenge:", trace["code_challenge"])
for step in trace["steps"]:
print(f"{step['n']}. {step['from']} -> {step['to']}: {step['message']}")
print("id_token aud: ", trace["id_token_claims"]["aud"])
print("access_token aud:", trace["access_token_claims"]["aud"])
Run in a scratch copy of examples/uw-auth/ on 2026-11-18 (no identity provider runs; the trace is a deterministic teaching model, and the example's agent is a scripted stand-in, so results show the access controls, not any model):
True
verifier: ksLka-tqKENkEHBIuZsc1LOaiVPf_MTQxocs4w3eX0k
challenge: CKzIz29kyr9VO2Q85M2tjWaMdppWHRgy5o-Gpm71OXo
1. broker browser -> portal BFF: GET /login
2. portal BFF -> broker browser: 302 to the authorization endpoint
3. broker browser -> identity provider: the broker authenticates (password + one-time code)
4. identity provider -> broker browser: consent
5. identity provider -> broker browser: 302 back to the redirect_uri
6. portal BFF -> identity provider: POST /token (back channel)
7. identity provider -> portal BFF: 200 tokens
8. portal BFF -> broker browser: session established
9. portal BFF -> API gateway: GET /quotes/Q-5531
id_token aud: svc-portal-bff
access_token aud: https://api.uw.insurer.example
True means the example's S256 function reproduces RFC 7636 Appendix B (verifier dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk, challenge E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM).
The broker's login, message by message#
Step 2, the redirect, is the request the identity provider receives. Written out from the trace's parameters (line breaks added for reading):
GET /authorize?response_type=code
&client_id=svc-portal-bff
&redirect_uri=https%3A%2F%2Fportal.insurer.example%2Fcallback
&scope=openid%20quotes.read%20quotes.submit
&state=1300bd10fd272b25
&nonce=ea1f441f6132ada4
&code_challenge=CKzIz29kyr9VO2Q85M2tjWaMdppWHRgy5o-Gpm71OXo
&code_challenge_method=S256
Host: idp.insurer.example
state ties the response to this browser's request (RFC 6749: it "SHOULD be used for preventing cross-site request forgery"); nonce ties the ID token to this login (OIDC: "used to associate a Client session with an ID Token, and to mitigate replay attacks"). The BFF keeps code_verifier, state and nonce server-side.
Step 3 is where authentication happens: at the identity provider, with password plus a one-time code in this example. The portal never sees the password, which is the whole point. Step 6, the back channel:
POST /token HTTP/1.1
Host: idp.insurer.example
Content-Type: application/x-www-form-urlencoded
(client authentication for the confidential client svc-portal-bff)
grant_type=authorization_code&code=code-2d43ffb6b742
&redirect_uri=https%3A%2F%2Fportal.insurer.example%2Fcallback
&client_id=svc-portal-bff&code_verifier=ksLka-tqKENkEHBIuZsc1LOaiVPf_MTQxocs4w3eX0k
Step 7 returns two tokens with two audiences and two purposes. This is the distinction most integration bugs come from:
| ID token (OIDC) | Access token (OAuth) | |
|---|---|---|
| Answers | who signed in, and how | what this client may call |
| Audience in the example | svc-portal-bff (the client) | https://api.uw.insurer.example (the API) |
| Key claims | sub u-broker-n1, nonce, acr, amr ["pwd","otp"], auth_time | sub, scope quotes.read quotes.submit, tenant brk-north, client_id |
| Checked by | the BFF: issuer, audience, expiry, nonce | the quote API: the ordered checks on Tokens |
| Lifetime (illustrative) | 300 s | 900 s |
The ID token validation rules are OIDC's. Standard (OIDC Core §3.1.3.7): the issuer "MUST exactly match the value of the iss (issuer) Claim"; the token "MUST be rejected if the ID Token does not list the Client as a valid audience"; the current time "MUST be before the time represented by the exp Claim"; and if a nonce was sent, "a nonce Claim MUST be present" and must match. Step 8 sets the session cookie described on Sessions; step 9 uses only the access token. The API never accepts the ID token: its audience is the client, so the audience check refuses it.
Diagram: The broker signs in · authorization code with PKCE and OIDC, two channels
Time runs down the page. Messages through the browser carry only references: a code challenge, a state, a one-time code. The secrets travel on the back channel: the BFF sends the code verifier and receives an ID token for itself and an access token for the API. Authentication happens at the identity provider; the portal never sees the password. The API receives only the access token and still decides on the record.
- Broker's browser to Portal BFF: GET /login. The broker asks to sign in.
- Portal BFF to Broker's browser: 302 to /authorize · code_challenge, state, nonce. The redirect carries only the S256 hash of the verifier, plus state and nonce. The verifier stays on the server.
- Broker's browser to Identity provider: broker authenticates. Password plus one-time code in the example, at the identity provider. The identity provider could require a passkey here without any change to the portal.
- Identity provider to Broker's browser: 302 to callback · code, state. A one-time code, useless without the verifier.
- Portal BFF to Identity provider: POST /token · code + code_verifier. Back channel, with client authentication. The identity provider recomputes S256 of the verifier and compares it with the challenge.
- Identity provider to Portal BFF: ID token (aud BFF) + access token (aud API). Two tokens, two audiences, two purposes. The BFF validates the ID token: iss, aud, exp, nonce.
- Portal BFF to Quote API: GET /quotes/Q-5531 · Bearer access token. Only the access token goes to the API; the ID token never does.
Notice the two channels in the diagram. Everything that passes through the browser (steps 2 and 5) is visible and forgeable, so it carries only references: a challenge, a state, a one-time code. Everything secret (the verifier, the tokens) travels on the back channel between the BFF and the identity provider.
The OAuth lab#
The lab animates both flows of this page: the broker's authorization code with PKCE and OIDC, and the assessment service's client credentials. Step through the actors, watch which token each message carries, and toggle between "consent" and "authentication" to see that they are different questions.
The same two flows as a table, from examples/uw-auth/oauth.py:
| Flow | Who | Person present | Tokens returned | Who decides on the record |
|---|---|---|---|---|
| Authorization code + PKCE + OIDC | portal BFF for u-broker-n1 | yes, signs in at the identity provider | ID token (aud svc-portal-bff) + access token (aud quote API) | quote service, rule R-AZ-03 |
| Client credentials | svc-assessment as itself | no | access token only (sub svc-assessment, scope uw.read) | quote service, on SUB-1004 |
Machines and devices: two more grants#
A workload has no person to sign in. Client credentials is the grant in which a client requests an access token using only its own credentials, acting as itself. A tiny example from the trace: the assessment service posts grant_type=client_credentials&client_id=svc-assessment&scope=uw.read, authenticating with a workload credential (a certificate or signed assertion), and receives an access token whose subject is svc-assessment. No ID token comes back: nobody signed in. Standard (RFC 9700 §2.5): "It is RECOMMENDED to use asymmetric cryptography for client authentication" (mTLS or private_key_jwt). The quote service still decides on the record; a valid service token reads only what the policy lets that service read. How the workload proves itself without a stored secret is on Workload identity and Cloud IAM.
A device with no browser, such as a kiosk in a brokerage office or a command-line tool, uses the device flow (device authorization grant): the device shows a short code, and the person approves it on a phone or laptop. Standard (RFC 8628, read 2026-11-18): the device receives device_code, user_code, verification_uri, optional verification_uri_complete, expires_in and interval, then polls the token endpoint with grant type urn:ietf:params:oauth:grant-type:device_code, hearing authorization_pending until the person approves, or slow_down ("the interval MUST be increased by 5 seconds"). An illustrative response:
{
"device_code": "dc-illustrative-0001",
"user_code": "WDJB-MJHT",
"verification_uri": "https://idp.insurer.example/device",
"expires_in": 900,
"interval": 5
}
The flow has a known weakness, written into the standard: "It is possible for the device flow to be initiated on a device in an attacker's possession." An attacker starts a flow and sends the code to a victim with a convincing message. This site's recommendation: use the device flow only for devices that need it, show on the approval page which device and client asked, and never for high-value scopes such as uw.decide.
Discovery, UserInfo and logout#
A client should not hard-code the identity provider's endpoints. A discovery document is a JSON file the provider publishes at a well-known URL, listing its endpoints, keys and supported features. A tiny example: https://idp.insurer.example/.well-known/openid-configuration returns issuer, authorization_endpoint, token_endpoint, jwks_uri and more.
Standard (OIDC Discovery 1.0, errata set 2): the path is the issuer with /.well-known/openid-configuration appended, so an issuer with a path, https://example.com/issuer1, is discovered at https://example.com/issuer1/.well-known/openid-configuration. OAuth's own metadata (RFC 8414) inserts the well-known segment before the path instead: /.well-known/oauth-authorization-server/issuer1. Both require the returned issuer to be identical to the one used to build the URL, which stops one provider from impersonating another through its metadata. Required discovery fields include issuer, authorization_endpoint, jwks_uri, response_types_supported, subject_types_supported and id_token_signing_alg_values_supported.
The UserInfo endpoint is "an OAuth 2.0 Protected Resource that returns Claims about the authenticated End-User"; its sub "MUST be verified to exactly match the sub Claim in the ID Token". And email_verified true means only that the provider "took affirmative steps to ensure that this e-mail address was controlled by the End-User": control of an address, not a verified real-world identity (People explains why that matters). OIDC Back-Channel Logout lets the provider POST a signed logout_token to the BFF so that a sign-out at the provider ends the portal session too.
SAML and federation: when the brokerage brings its own login#
Some brokerages are large and run their own corporate identity provider. Their brokers should sign in with their company account, not a separate portal password, and when a broker leaves the brokerage, access should end with their company account. Trusting another organization's identity provider for your application is federation: two organizations agree that one asserts identities and the other relies on those assertions, across a boundary neither controls alone.
Federation for browsers in enterprises often runs on SAML 2.0, an older XML-based standard. Standard (OASIS SAML 2.0 technical overview, read 2026-11-18): "An asserting party is a system entity that makes SAML assertions"; "A relying party is a system entity that uses assertions it has received"; the roles are identity provider (IdP) and service provider (SP); assertions "carry statements about a principal that an asserting party claims to be true" (authentication, attribute and authorization decision statements). In the Web Browser SSO profile, "the SP will send the user to the IdP with an authentication request" and receives a signed response through the browser (HTTP POST or Redirect binding). The overview read is a non-normative 2008 committee draft summarizing the 2005 standard.
The design that keeps the portal simple is identity brokering: the insurer's identity provider federates with each brokerage's provider (SAML or OIDC), and issues the portal its usual OIDC tokens. Product (Keycloak 26.8.2, as documented on 2026-11-18): lists "Identity Brokering - Authenticate with external OpenID Connect or SAML Identity Providers". Product (Auth0, as documented on 2026-11-18): Organizations "best supports business-to-business (B2B) implementations", with per-organization connections. The portal and the quote API never see SAML at all.
Security note. Federation moves authentication to the brokerage; it never moves authorization. A broker whose company identity provider assertstenant=brk-southgetsbrk-south's quotes only if the insurer's mapping says that provider may assert that tenant. Bind each federated provider to the tenants it may speak for, or one compromised brokerage provider can claim to be any brokerage.
Token exchange: a narrower token for the next hop#
Now the agent. The underwriter u-uw-w1 opens SUB-1004 in the cockpit and asks the underwriting agent to prepare a recommendation. The agent application needs to call the MCP server https://mcp.uw.insurer.example, which wants a token naming the underwriter, because the underwriter is the person the work is for. The shortcut is to forward the underwriter's own token. It is the wrong shortcut: that token has the wrong audience, carries uw.decide, and would make every call look like the underwriter acting alone.
Token exchange is the standard alternative: a client presents a token it holds (and optionally its own token as the actor) to the authorization server, and asks for a new token for one audience, with equal or fewer scopes. Standard (RFC 8693, read 2026-11-18): grant type urn:ietf:params:oauth:grant-type:token-exchange; subject_token and subject_token_type are required; actor_token is optional; resource, audience, scope say what the new token is for. The standard names two semantics: in impersonation the actor is indistinguishable from the subject; in delegation the actor keeps its own identity, recorded in an act claim. This site's recommendation: an agent never impersonates a person; it uses delegation, narrowed to one audience and one task.
This site's own case UW-A22 runs the exchange in tokens.token_exchange, a stand-in shaped after RFC 8693 (no real authorization server). The agent application sends the underwriter's access token as the subject and its own workload token as the actor. The request the stand-in records:
{
"grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
"subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
"audience": "https://mcp.uw.insurer.example",
"scope": "uw.read uw.recommend",
"actor_token_type": "urn:ietf:params:oauth:token-type:access_token"
}
The claims of the token it issued (real output):
{
"iss": "https://idp.insurer.example",
"sub": "u-uw-w1",
"aud": "https://mcp.uw.insurer.example",
"iat": 1794992400,
"nbf": 1794992400,
"exp": 1794993300,
"scope": "uw.read uw.recommend",
"principal_type": "person",
"client_id": "wl-underwriting-agent",
"jti": "jti-d5ecb5057011",
"business_unit": "commercial-west",
"act": {"sub": "wl-underwriting-agent"},
"task": {
"run_id": "run-7f3a",
"submission_id": "SUB-1004",
"actions": ["assessment.read", "guidance.search", "precedent.search", "recommendation.record"],
"expires_at": 1794994200
}
}
Three things narrowed. The audience is one server. The scope dropped uw.decide. And act records that wl-underwriting-agent is acting for u-uw-w1, so the policy decision point treats the agent as the principal, on behalf of the underwriter, inside the task. (The task claim is this example's addition, not a standard claim.) The same exchange, asked to widen, is refused; asked for the LLM gateway as audience, it is refused too:
WIDENING {"issued": false, "status": 400, "error": "invalid_scope", "error_description": "requested scope uw.decide is beyond what an agent may hold (uw.read uw.recommend)"}
LLM GW {"issued": false, "status": 400, "error": "invalid_target", "error_description": "no token can be issued for audience https://llm-gw.internal.example"}
Diagram: Token exchange narrows · one audience, fewer scopes, the actor recorded, refusals possible
Read left to right. The agent application presents two tokens: the underwriter's as the subject and its own workload token as the actor. The authorization server decides by policy what it will issue: a token for the MCP server only, with uw.read and uw.recommend, an act claim naming the agent and a task. Asking for uw.decide is refused with invalid_scope; asking for the LLM gateway is refused with invalid_target. Nothing is forwarded.
- Presented
- subject token: The underwriter's own access token, which carries uw.decide and is meant for the quote API. It is evidence of the person's authority, not something to pass along.
- actor token: The agent application's own workload token, with the token endpoint as audience. It proves who will act.
- Authorization server policy
- audience allowed? scope within limits?: The server checks both tokens, the requested audience against its list of delegation targets, and each scope against the subject's scopes and the agent's maximum.
- Issued or refused
- token for the MCP server: Audience one server, scopes narrowed, act names the agent, task names run-7f3a and SUB-1004 and expires.
- uw.decide · invalid_scope: Widening and a forbidden audience are refused with HTTP 400. A refusal is an audit event.
That is what token exchange must mean in every design: the authorization server decides, by policy, which narrower token it will issue, and it can refuse. It is never "the service passes the caller's token along", and never an unrestricted conversion of one token into any other. Standard (RFC 8693): invalid_target "SHOULD be used" when the server cannot issue a token for the requested resource or audience. Product (Keycloak, as documented on 2026-11-18): standard token exchange V2 is "enabled by default", supports only internal-to-internal exchange within one realm, and its audience parameter is "effectively used for "downscoping" the token"; the legacy V1 is preview and deprecated. Product (Microsoft Entra ID, as documented on 2026-11-18): the on-behalf-of flow uses grant type urn:ietf:params:oauth:grant-type:jwt-bearer (not RFC 8693's), "only uses delegated scopes and not application roles", and warns "DO NOT send access tokens that were issued to the middle tier to anywhere except the intended audience". The full agent delegation design (task tokens, maximum authority, approval before record_underwriter_decision) is on Agents.
What this is not. MCP's own authorization rules (protected resource metadata, the resource parameter, no token passthrough) are summarized on MCP and taught in depth on mcp.sammuthu.com. This page gives the OAuth mechanics they build on.
What goes wrong without these rules#
The retired flows are the clearest failures, because the standards now name them. Standard (RFC 9700): the password grant "MUST NOT be used" (the opening proposal); "clients SHOULD NOT use the implicit grant (response type token)", which returned the access token in the browser's URL fragment; "Clients MUST NOT pass access tokens in a URI query parameter". Three other rules close the holes those flows had:
- Redirect URIs match exactly. Authorization servers "MUST utilize exact string matching" (localhost ports for native apps excepted). A wildcard such as
https://*.insurer.example/lets an attacker who controls any subdomain receive codes. - Codes are bound to their requester. PKCE (and
stateornonce) stops a stolen or injected code from being redeemed by another session. - Clients talking to several authorization servers defend against mix-up. RFC 9700 makes a mix-up defense "REQUIRED" and says clients "SHOULD use the iss parameter" of the authorization response.
Common confusion. "OAuth 2.1 replaced all this." SURPRISING: OAuth 2.1 is still an Internet-Draft: draft-ietf-oauth-v2-1-17, dated 31 October 2026, "Obsoletes: 6749, 6750 (if approved)". It consolidates the same rules (PKCE required; implicit and password grants "not specified") but it is not yet an RFC. Cite RFC 6749 plus RFC 9700 for what is required today.
Choosing a flow#
The recurring decision of this site applies directly: what is the simplest credible design for this principal and this delegation model?
| Principal and situation | Simplest credible flow | Grow when | Never |
|---|---|---|---|
| Person in a browser, your own app | authorization code + PKCE + OIDC, at a BFF | many apps: one identity provider and SSO | password grant, implicit grant |
| Customer organization with its own identity provider | federation (SAML or OIDC) at your identity provider, tokens to your apps as usual | many customers: identity brokering per tenant | letting a customer provider assert any tenant |
| Service acting as itself | client credentials with asymmetric client authentication | cross-boundary calls: workload identity federation | a person's token |
| Device without a browser | device flow, low-value scopes | device flow for uw.decide | |
| Service or agent acting for a person at the next hop | token exchange to a narrower token, one audience, act claim | multi-hop chains: task tokens, maximum authority | forwarding the received token |
| Scheduled job, no person | client credentials only | requiring a user identity that does not exist |
The last row is easy to get wrong in the other direction. A nightly reconciliation job has no end user; demanding a "user token" for it produces a shared fake user account, which is worse than an honest workload identity.
In a coding agent. A coding agent's pipeline is OAuth-shaped too. The agent works through a GitHub App installation token scoped to one repository, not a person's personal access token; CI exchanges a short-lived OIDC token for cloud credentials instead of storing keys. Both are "client credentials for a workload" plus "exchange, do not forward". A person with merge rights still merges. Details: Coding agents.
Security notes#
- The portal never sees passwords; authentication happens at the identity provider.
- PKCE with
S256for every client; exact redirect URIs;stateornoncechecked. - ID tokens stay with the client; access tokens go to their audience only.
- Token exchange narrows by policy and refuses; refused requests are audit events.
- Federation binds each external identity provider to the tenants it may assert.
Monday checklist#
- List every OAuth client and its grant types; remove any password or implicit grant.
- Every redirect URI registered exactly, no wildcards; a test that a near-miss URI is refused.
- PKCE
S256enforced at the identity provider (checkcode_challenge_methods_supportedin metadata). - The BFF validates ID tokens:
issexact,audcontains itsclient_id,exp,nonce. - Services that call other services use their own tokens or an exchange; grep for code that copies an incoming
Authorizationheader to an outgoing call. - Device flow, if used, limited to low-value scopes.
Exercises#
Exercise 1. The cockpit's API calls the assessment service by copying the underwriter's incoming Authorization header. Name two things wrong, and the fix.
AnswerWrong audience, too much authority; exchange instead
The token's audience is the quote API, so a correct assessment service must refuse it (and one that accepts it is broken); and it carries the person's full scopes, including uw.decide, to a service that needs uw.read. Exchange it for a token with the assessment service as audience and only the needed scope, or call as the service itself if no person's authority is needed.
Exercise 2. A partner app asks brokers to sign in "with the portal" and wants quotes.read. Which flow, and which screen must appear that the first-party portal skips?
AnswerCode + PKCE, with consent
Authorization code with PKCE, with the partner as its own registered client; the consent screen, because the broker is delegating access to a third party. The quote API still checks the tenant on every record the partner reads.
Exercise 3. Why does UW-A22 refuse https://llm-gw.internal.example as an exchange audience even though the request is otherwise valid?
AnswerPolicy: the gateway is never a delegation target
The example's authorization server policy lists the services that may receive delegated tokens, and the LLM gateway is not one: the gateway is reached with the agent application's own workload identity, never with a person's authority. invalid_target is the standard error for an audience the server will not serve.
Advanced perspective#
Resource indicators and pushed authorization requestsSay which API the token is for, and keep the request off the URL
Standard (RFC 8707): the resource parameter "MUST be an absolute URI" naming the target API, at the authorization and token endpoints, and the server "SHOULD audience-restrict issued access tokens" to it. Without it, an identity provider serving many APIs may issue one token valid at all of them. Standard (RFC 9126, PAR): the client pushes the authorization request to the server over the back channel, authenticating "in the same way as at the token endpoint", and receives a request_uri to put in the redirect. The browser then carries a reference instead of the parameters, so they cannot be read or altered in transit. High-assurance profiles such as FAPI 2.0 (listed Final on the OpenID specifications page) build on both.
SAML or OIDC for a new federationMeet the customer where they are; issue your own tokens
A brokerage with an established SAML identity provider will not change it for your portal. Accept SAML at your identity provider, map the assertion's attributes to your tenant model, and issue OIDC tokens internally; your applications then see one protocol. Prefer OIDC for new federations: JSON, discovery, and the same token validation as everything else. The operational risks are the same in both: certificate or key rollover at the partner (publish dates, monitor expiry), attribute changes that silently change tenancy, and offboarding a partner (remove the trust, and revoke sessions it created). The OpenID specifications page lists OpenID Federation 1.0 and 1.1 as Final, for multi-party trust chains; this site read that list once and has not studied the specifications.
Refresh tokens across the flowsWhere they live decides how bad a theft is
In the BFF design the refresh token never leaves the server, so theft needs a server compromise. A browser-only client holds it in JavaScript, which is why RFC 9700 requires public clients to sender-constrain refresh tokens or rotate them with reuse detection: the server "issues a new refresh token with every access token refresh response" and, if an old one comes back, treats it as theft and revokes the family. Client credentials normally need no refresh token at all; the workload asks again. Token exchange results should not come with refresh tokens for agents: a task token that expires with the task is the point.
Where products put these conceptsSame standards, different nouns; read the defaults
Neutral, one line each, as documented on 2026-11-18. Keycloak: a realm "manages a set of users, credentials, roles, and groups"; clients may define client roles. Okta: custom authorization servers let you "define your own OAuth 2.0 scopes, claims, and access policies"; the built-in org server cannot apply policies to your own APIs. Auth0: one tenant per environment is recommended. Microsoft Entra ID: scp carries delegated scopes "Only included for user tokens"; roles carries application permissions for client-credential tokens. Amazon Cognito: machine-to-machine tokens via client credentials authorize "only custom scopes from resource servers", and a resource binding (RFC 8707) cannot be requested with client-credentials grants. The deeper comparison is on Frameworks.
In one breath#
OAuth lets a client obtain a limited token from an authorization server; OpenID Connect adds an ID token so the client learns who signed in; SAML does the sign-in half for enterprise federation. People use authorization code with PKCE at a backend, services use client credentials, devices may use the device flow, and the password and implicit grants are retired. A service that needs to act for someone at the next hop asks for a narrower token by exchange and accepts a refusal; it never forwards what it received. Prove who, then decide what, on the record itself.
The broker, the services and the agent now each hold a token that says who they are, for which audience, with which coarse scopes. None of those tokens says whether the broker may read Q-6620 or whether the peer underwriter may decide SUB-1004. Authorization takes that question on directly: subject, action, resource and context, decided on every request.