skip to content

During a phased migration, how can a service holding a SAML 2.0 assertion obtain an OAuth 2.0 access token?

level: seniorimportance: nice to knowfreq 25%

answer

  1. a bridge at the token endpoint
  2. one credential in, another out
  3. a generic assertion framework, profiled
  4. grant versus client authentication
  5. the assertion parameter, base64url-encoded

basics

~10 s

By using RFC 7522's authorization grant: the token request carries grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer with the base64url-encoded SAML 2.0 assertion in the assertion parameter, and the authorization server validates it and issues an access token.

solid answer

~40 s

`RFC 7522` profiles `RFC 7521`'s generic assertion framework for SAML 2.0, and it defines two separate uses that candidates routinely merge. As an **authorization grant**, the token request sends `grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer` with the base64url-encoded SAML 2.0 assertion in the `assertion` parameter; the authorization server validates that assertion and, if it trusts the issuer, returns an access token. As **client authentication**, a client proves itself with `client_assertion_type=urn:ietf:params:oauth:client-assertion-type:saml2-bearer` and the assertion in `client_assertion` — that is about the client, not the user. The migration value is the first one: a member organisation that already runs a SAML 2.0 identity provider keeps it, while newer resource servers are reached with access tokens, so the member does not have to re-integrate before you can move the services.

code

http · 6 lines
http
POST /token HTTP/1.1
Host: as.clearing-house.example
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer
&assertion=PEFzc2VydGlvbiB4bWxucz0i...[base64url-encoded SAML 2.0 assertion]

go deeper

for a junior

Recall that a standard bridge exists: an assertion a member already issues can be presented at a token endpoint and exchanged for an access token, rather than the member reintegrating.

for a middle

Explain the request precisely — the saml2-bearer grant URN in grant_type with the base64url-encoded assertion in the assertion parameter — and distinguish it from the client-assertion-type URN used for client authentication.

for a senior

Show the validation you would require before issuing: issuer, audience and validity window against your own clock, and name the case where a well-signed assertion is still refused.

for a principal

Treat it as a deliberate temporary coupling: it decouples service migration from member migration and gives you a progress metric, at the cost of a component that must be retired rather than inherited.

## The problem this solves A phased migration between federation standards stalls on a circular dependency. New services want access tokens. The member organisations that must log in still speak the XML-era standard and will not re-integrate on your schedule. Neither side can move first — unless something converts one credential into the other at a defined point. `RFC 7522` is that something. It profiles the generic assertion framework of `RFC 7521` for SAML 2.0, so an assertion a member's identity provider already issues can be presented to an authorization server and turned into an access token. ## Two uses, and merging them is the classic error The profile defines two things that share a name and do different jobs: | Use | Identifier | Parameter carrying the assertion | What is being established | |---|---|---|---| | Authorization grant | `urn:ietf:params:oauth:grant-type:saml2-bearer` in `grant_type` | `assertion` | That a resource owner's authorisation exists, evidenced by the assertion | | Client authentication | `urn:ietf:params:oauth:client-assertion-type:saml2-bearer` in `client_assertion_type` | `client_assertion` | That the client calling the token endpoint is who it claims to be | They are independent. A request may use the grant, the client-authentication method, both, or neither. Being able to say which one you mean, and which parameter carries it, is most of the value of knowing this profile at all. ## What the authorization server actually does The word *bearer* in the URN describes the assertion's role: possession of it is what is presented. That does **not** mean it is accepted unexamined. The authorization server is validating somebody else's signed statement, so it must satisfy itself of the usual things before minting anything: 1. **The signature**, against a key it already associates with that issuer. 2. **The issuer**, that it is one this authorization server is configured to accept assertions from at all. 3. **The intended audience**, that the assertion was meant for this authorization server rather than replayed from another relying party. 4. **The validity window**, against its own clock, with whatever skew allowance it permits. An assertion that verifies can still be refused — wrong audience, expired window, an issuer that is trusted for logins but not for token issuance. *Verified* and *accepted* are different outcomes, and saying so is the senior half of this answer. ## Where it fits in a migration The sequencing value is that it **decouples the two halves of the estate**: - Member organisations keep their existing identity providers and change nothing. - New and migrated services are built against access tokens only, with no XML path in them. - The conversion happens in one place you operate, which is also the one place you can instrument to see which members are still arriving over the old standard. That last point is what makes it a migration tool rather than a permanent bridge. The exchange point is where you measure progress: when the count of assertions converted for a given member reaches zero, that member has genuinely moved and the old path can be retired for them. ## What it is not Three honest limits: - **It is not a general standard translator.** It converts an assertion into a token at a token endpoint. It does not make the member's identity provider speak the other standard, and it does not carry logout behaviour across. - **It does not remove the trust decision.** Somebody still had to decide that this issuer's assertions may be turned into access tokens in your estate, and that decision is exactly as consequential as the original federation trust. - **It does not make the assertion an access token.** The assertion is evidence presented once at the token endpoint; what a resource server accepts afterwards is the token the authorization server issued. ## Saying it in an interview *A member already issues SAML 2.0 assertions. We accept one at the token endpoint under the saml2-bearer grant URN, in the assertion parameter, validate it as we would any federated statement, and issue an access token. The services only ever see tokens, the member changes nothing, and the exchange point tells us who has actually migrated.*

  • The assertion's signature verifies. Must the authorization server issue a token?
    No. A valid signature only establishes who wrote the statement. The authorization server still checks that this issuer is one it accepts assertions from, that the assertion's intended audience is this server rather than some other relying party it was minted for, and that the validity window has not passed against its own clock. Any of those can refuse a perfectly well-signed assertion.
  • How is this different from using the client-assertion-type URN?
    Different job, different parameter. The grant URN in grant_type with the assertion in assertion is about the resource owner's authorisation and results in an access token. The client-assertion-type URN with the assertion in client_assertion is how a client authenticates itself to the token endpoint, and says nothing about any user. Merging the two is the standard mistake with this profile.
  • Why is this a migration tool rather than a permanent design?
    Because it leaves the member organisation on the old standard indefinitely and concentrates the conversion in one component you must keep running. It is valuable precisely while the estate is split: it decouples service migration from member migration, and the volume flowing through it is your progress metric. When that volume reaches zero for a member, the old path can go.

saying these in an interview costs you the question

  • Thinks bearer means the assertion is accepted without validation
  • Uses the client-assertion-type URN when describing the authorization grant
  • Says the SAML 2.0 assertion is itself used as the access token
  • Assumes the exchange also carries logout or session behaviour across
  • Forgets the audience check and so permits an assertion replayed from another relying party