RFC 7521

Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants

📅 published May 2015, from ietf

RFC 7521: Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants 🎀

Okay bestie, this one is the big one for OAuth + assertions! 💖 Here's the title block so you know who's behind it:

  • Organization: Internet Engineering Task Force (IETF) 🌸
  • Request for Comments: 7521
  • Category: Standards Track ⭐
  • ISSN: 2070-1721
  • Authors: B. Campbell (Ping Identity), C. Mortimore (Salesforce), M. Jones (Microsoft), Y. Goland (Microsoft) 🫶
  • Date: May 2015 🦋
  • Obsoletes / Updates: nothing is listed as obsoleted or updated in this header ✨

Abstract ✨

Okay so this spec gives you a framework for using assertions with OAuth 2.0, and it does it in two ways: as a brand-new client authentication mechanism and as a brand-new authorization grant type 🔥. It also specifies how assertions get carried over during conversations with a token endpoint, plus some general processing rules. Slay.

The whole point is to give OAuth 2.0 a common framework so it can interwork with other identity systems that use assertions, and to offer alternative client authentication options 💅.

Heads up though: this spec only defines abstract message flows and processing rules. To actually be implementable, you need companion specs that provide the concrete versions 🙈.

Status of This Memo 📜

This is an Internet Standards Track document. Iconic.

It's a product of the Internet Engineering Task Force (IETF), it represents the consensus of the IETF community, it got public review, and the Internet Engineering Steering Group (IESG) approved it for publication 🌈. If you want more on Internet Standards, check out Section 2 of RFC 5741.

For the current status, any errata, and how to give feedback, go to http://www.rfc-editor.org/info/rfc7521 🦋.

Copyright (c) 2015 IETF Trust and the persons identified as the document authors. All rights reserved. ✨

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they were in effect on the date of publication. Please read these carefully, because they spell out your rights and restrictions for this document 🙈. Code Components extracted from this document are a different story: they must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come without warranty, as described in the Simplified BSD License.

Table of Contents 🎀

1. Introduction ....................................................3
2. Notational Conventions ..........................................4
3. Framework .......................................................4
4. Transporting Assertions .........................................7
   4.1. Using Assertions as Authorization Grants ...................7
        4.1.1. Error Responses .....................................8
   4.2. Using Assertions for Client Authentication .................9
        4.2.1. Error Responses ....................................10
5. Assertion Content and Processing ...............................10
   5.1. Assertion Metamodel .......................................10
   5.2. General Assertion Format and Processing Rules .............12
6. Common Scenarios ...............................................12
   6.1. Client Authentication .....................................13
   6.2. Client Acting on Behalf of Itself .........................13
   6.3. Client Acting on Behalf of a User .........................13
        6.3.1. Client Acting on Behalf of an Anonymous User .......14
7. Interoperability Considerations ................................14
8. Security Considerations ........................................15
   8.1. Forged Assertion ..........................................15
   8.2. Stolen Assertion ..........................................15
   8.3. Unauthorized Disclosure of Personal Information ...........16
   8.4. Privacy Considerations ....................................17
9. IANA Considerations ............................................17
   9.1. "assertion" Parameter Registration ........................17
   9.2. "client_assertion" Parameter Registration .................18
   9.3. "client_assertion_type" Parameter Registration ............18
10. References ....................................................18
   10.1. Normative References .....................................18
   10.2. Informative References ...................................18
Acknowledgements ..................................................20
Authors' Addresses ................................................20

1. Introduction 🌸

Okay so an assertion is basically a package of information that helps share identity and security info across security domains 🎀. Section 3 gets way more into what an assertion means for this spec.

OAuth 2.0 [RFC6749] is an authorization framework that lets a third-party application get limited access to a protected HTTP resource 💅. In OAuth, those third-party apps are called clients. They access protected resources by presenting an access token to the HTTP resource. Access tokens get issued to clients by an authorization server, with the (sometimes implicit) approval of the resource owner ✨. Usually they're obtained by exchanging an authorization grant, which represents the authorization granted by the resource owner (or by a privileged administrator). There are several authorization grant types for a wide range of client types and user experiences. OAuth also has an extensibility mechanism for defining extra grant types, which can act as a bridge between OAuth and other protocol frameworks 🦋.

This spec gives a general framework for using assertions as authorization grants with OAuth 2.0 🌈. It also gives a framework for assertions to be used for client authentication. You get generic mechanisms for transporting assertions during interactions with an authorization server's token endpoint, plus general rules for the content and processing of those assertions. The goal is an alternative client authentication mechanism (one that doesn't send client secrets) and to make OAuth 2.0 easier to use in client-server integration scenarios, where the end user may not be present 🫶.

Again, this spec only defines abstract message flows and processing rules. To be implementable, companion specs are needed to provide the corresponding concrete instantiations. For instance, "Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants" [RFC7522] defines a concrete instantiation for Security Assertion Markup Language (SAML) 2.0 Assertions, and "JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants" [RFC7523] defines a concrete instantiation for JWTs 💜.

Note: Using assertions for client authentication is orthogonal to and separable from using assertions as an authorization grant, so they can be used together or separately 🙈. Client assertion authentication is nothing more than an alternative way for a client to authenticate to the token endpoint, and it must be used in conjunction with some grant type to form a complete and meaningful protocol request. Assertion authorization grants may be used with or without client authentication or identification. Whether client authentication is needed alongside an assertion authorization grant, and which types of client authentication are supported, are policy decisions left to the discretion of the authorization server 👑.

2. Notational Conventions 💅

Here's the deal with the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document: they are to be interpreted as described in [RFC2119] 🎀.

Throughout this document, values are quoted to show that they are to be taken literally 🍓. When you use these values in protocol messages, the quotes must not be used as part of the value ✨.

3. Framework ✨

okay bestie, let's talk about assertions 🧚 an assertion is basically a little package of info that lets identity and security stuff travel between different security domains. it usually says who the subject or principal is, who issued it and when, and the conditions for using it, like when and where it's valid. think of it as a VIP wristband with the rules printed on it 🎀

the one who creates it and signs or integrity-protects it is called the "Issuer" 💅, and the one who consumes it and trusts what it says is the "Relying Party" 👑. in this doc, the authorization server is the relying party. it's giving gatekeeper 🫶

okay this next part is super important, so listen up 🙈 assertions used in the protocol exchanges here MUST always be integrity protected with a digital signature or a Message Authentication Code (MAC) applied by the issuer. that's how the issuer gets authenticated and the assertion content stays intact ✨ a lot of the time a third party issues the assertion, and it has to be protected from tampering by the client that's carrying it around 😭 an assertion MAY also be encrypted, so unauthorized parties (like the client) can't peek inside 🔒

this spec doesn't define how the client actually gets the assertion before sending it to the authorization server, but there are two common patterns I'll walk you through 🦋

in the first pattern (Figure 1), the client gets an assertion from a third-party entity that can issue, renew, transform, and validate security tokens. that entity is usually called a "security token service" (STS) or just "token service" 💖 there's a trust relationship between the token service and the relying party, usually shown by swapping some kind of key material. the token service is the assertion issuer. it takes requests from clients, which show up with various credentials, mints assertions, fills them with the right info, and integrity-protects them with a signature or message authentication code 💜 WS-Trust [OASIS.WS-Trust] is one standard for requesting security tokens (assertions) 🌸

  Relying
  Party                     Client                   Token Service
    |                          |                         |
    |                          |  1) Request Assertion   |
    |                          |------------------------>|
    |                          |                         |
    |                          |  2) Assertion           |
    |                          |<------------------------|
    |    3) Assertion          |                         |
    |<-------------------------|                         |
    |                          |                         |
    |    4) OK or Failure      |                         |
    |------------------------->|                         |
    |                          |                         |
    |                          |                         |

            Figure 1: Assertion Created by Third Party

in the second pattern (Figure 2), the client makes its own assertions locally 🧁 to sign them or add a MAC, it needs key material, either symmetric keys or asymmetric key pairs. how it gets that key material is out of scope for this spec 🙃

  Relying
  Party                     Client
    |                          |
    |                          | 1) Create
    |                          |    Assertion
    |                          |--------------+
    |                          |              |
    |                          | 2) Assertion |
    |                          |<-------------+
    |    3) Assertion          |
    |<-------------------------|
    |                          |
    |    4) OK or Failure      |
    |------------------------->|
    |                          |
    |                          |

                  Figure 2: Self-Issued Assertion

assertions usually carry identity and security info, but self-issued ones can do something different too 🎭 they can prove you know a secret, like a client secret, without actually sending the secret over the wire 🤫 in that case, whatever extra info the client adds is kinda low-key useless to the relying party, so self-issued assertions usually just include the bare minimum, like issuing and usage conditions 💀

deployments have to pick the right variant based on how much security they need, the trust relationship between the entities, and other factors 🌈

now, from the perspective of the entity presenting the assertion, there are two main types 👑

  1. Bearer Assertions: anyone holding a bearer assertion (the bearer) can use it to access the associated resources, and they don't have to prove they hold a cryptographic key 🫠 so to stop misuse, bearer assertions need protection from being disclosed, both in storage and in transit. secure communication channels are required between all entities so the assertion doesn't leak to the wrong people 🔐
  2. Holder-of-Key Assertions: to access the resources, the entity presenting the assertion has to prove it has additional cryptographic material 🗝️ the token service binds a key identifier to the assertion, and when the client presents it, the client has to show the relying party that it knows the key that matches that identifier ✨

the protocol parameters and processing rules in this document are meant for a client presenting a bearer assertion to an authorization server 🍓 they aren't directly suitable for holder-of-key assertions. you could use them as a starting point for a holder-of-key system, but you'd need extra mechanisms to prove possession of the secret key, and maybe some changes to the security model (like relaxing the requirement for an Audience) 🙈 it's a whole plot twist, not a quick fix 💅

4. Transporting Assertions 🦋

this section defines HTTP parameters for carrying assertions when a client talks to a token endpoint on an OAuth authorization server 🌸 because requests to the token endpoint send clear-text credentials (in both the HTTP request and response), every request to the token endpoint MUST use Transport Layer Security (TLS), as required in Section 3.2 of OAuth 2.0 [RFC6749] 🔒 no shortcuts, bestie 😭

4.1. Using Assertions as Authorization Grants 💖

this section defines how assertions get used as authorization grants, based on the definition in Section 4.5 of OAuth 2.0 [RFC6749] ✨ when you use an assertion as an authorization grant, the client includes the assertion and its related info using these HTTP request parameters 🧚

  • grant_type: REQUIRED. this is the format of the assertion, as defined by the authorization server 💜 the value is an absolute URI.
  • assertion: REQUIRED. this is the assertion being used as the authorization grant 🎀 its specific serialization is defined by profile documents.
  • scope: OPTIONAL. this is the requested scope, as described in Section 3.3 of OAuth 2.0 [RFC6749] 🌈 when you swap assertions for access tokens, the authorization for that token was already granted through some out-of-band mechanism 👑 so the requested scope MUST be equal to or less than the scope originally granted to the authorized accessor. and the authorization server MUST limit the scope of the issued access token to be equal to or less than the scope originally granted to the authorized accessor 🫶

client authentication is optional, as described in Section 3.2.1 of OAuth 2.0 [RFC6749], so the client_id is only needed when a form of client authentication that relies on that parameter is used 🦋

here's an example of an assertion being used as an authorization grant (with extra line breaks just for display 💅):

  POST /token HTTP/1.1
  Host: server.example.com
  Content-Type: application/x-www-form-urlencoded

  grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer&
  assertion=PHNhbWxwOl...[omitted for brevity]...ZT4

an assertion used this way is usually a short-lived version of the authorization grant, so authorization servers SHOULD NOT issue access tokens with a lifetime that goes way past the assertion's validity period 😭 in practice, that usually means refresh tokens don't get issued in response to assertion grant requests, and access tokens get a reasonably short lifetime ⏳ clients can refresh an expired access token by asking for a new one with the same assertion (if it's still valid) or with a new assertion 🌸

you can request an IETF URN to use as the "grant_type" value with the template in [RFC6755] 💜 a URN of the form urn:ietf:params:oauth:grant-type:* is suggested 🍓

4.1.1. Error Responses 🙈

if an assertion is invalid or has expired, the authorization server builds an error response as defined in OAuth 2.0 [RFC6749] 💀 the value of the "error" parameter MUST be the "invalid_grant" error code 🚫 the authorization server MAY include extra info about why the assertion was considered invalid, using the "error_description" or "error_uri" parameters 🔥

for example:

  HTTP/1.1 400 Bad Request
  Content-Type: application/json
  Cache-Control: no-store

  {
    "error":"invalid_grant",
    "error_description":"Audience validation failed"
  }

4.2. Using Assertions for Client Authentication 💖

Okay bestie, this section is the glow-up of Section 2.3 of OAuth 2.0 [RFC6749] 🫶 It explains how a client can use an assertion as its client credentials 🔐 When it does, it sends the assertion plus some related info in these HTTP request parameters:

  • client_assertion_type: REQUIRED. The format of the assertion, as defined by the authorization server. The value will be an absolute URI. 🎀
  • client_assertion: REQUIRED. The assertion being used to authenticate the client. The specific serialization of the assertion is defined by profile documents. ✨
  • client_id: OPTIONAL. The client identifier, as described in Section 2.2 of OAuth 2.0 [RFC6749]. The "client_id" is unnecessary for client assertion authentication because the client is identified by the subject of the assertion. If present, the value of the "client_id" parameter MUST identify the same client as is identified by the client assertion. 🦋

Here's a slay example of a client authenticating with an assertion during an access token request, as defined in Section 4.1.3 of OAuth 2.0 [RFC6749] (extra line breaks added just so it's easier to read 💅):

POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=n0esc3NRze7LTCu7iYzS6a5acc3f0ogp4&
client_assertion_type=urn%3Aietf%3Aparams%3Aoauth
%3Aclient-assertion-type%3Asaml2-bearer&
client_assertion=PHNhbW...[omitted for brevity]...ZT

So how does a token endpoint tell assertion-based credentials apart from the other client credential types? It's lowkey so simple 👀 It just looks for the "client_assertion" and "client_assertion_type" parameters, since those only show up when assertions are being used for client authentication 🌸

An IETF URN for use as the "client_assertion_type" value may be requested using the template in [RFC6755]. A URN of the form urn:ietf:params:oauth:client-assertion-type:* is suggested 🍓

4.2.1. Error Responses 💀

If an assertion is invalid for any reason, or if more than one client authentication mechanism is used, the authorization server constructs an error response as defined in OAuth 2.0 [RFC6749]. The value of the "error" parameter MUST be the "invalid_client" error code. The authorization server MAY include additional information about why the client assertion was considered invalid, using the "error_description" or "error_uri" parameters 🙈

For example:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store

{
  "error":"invalid_client"
  "error_description":"assertion has expired"
}

5. Assertion Content and Processing 🧚

This section gives a general content and processing model for using assertions in OAuth 2.0 [RFC6749]. It's the rulebook for how assertions should look and behave 📜✨

5.1. Assertion Metamodel 🎀

These are the entities and metadata involved in issuing, exchanging, and processing assertions in OAuth 2.0. They're general terms, abstract from any particular assertion format. Profiles of this specification provide the mappings from these terms into specific representations 💜

Issuer

A unique identifier for the entity that issued the assertion. Generally, this is the entity that holds the key material used to sign or integrity-protect the assertion. Examples of issuers are OAuth clients (when assertions are self-issued) and third-party security token services. If the assertion is self-issued, the Issuer value is the client identifier. If the assertion was issued by a security token service (STS), the Issuer should identify the STS in a manner recognized by the authorization server. In the absence of an application profile specifying otherwise, compliant applications MUST compare Issuer values using the Simple String Comparison method defined in Section 6.2.1 of RFC 3986 [RFC3986] 🔍

Subject

A unique identifier for the principal that is the subject of the assertion.

  • When using assertions for client authentication, the Subject identifies the client to the authorization server using the value of the "client_id" of the OAuth client. 🦋
  • When using assertions as an authorization grant, the Subject identifies an authorized accessor for which the access token is being requested (typically, the resource owner or an authorized delegate). 👑

Audience

A value that identifies the party or parties intended to process the assertion. The URL of the token endpoint, as defined in Section 3.2 of OAuth 2.0 [RFC6749], can be used to indicate that the authorization server is a valid intended audience of the assertion. In the absence of an application profile specifying otherwise, compliant applications MUST compare the Audience values using the Simple String Comparison method defined in Section 6.2.1 of RFC 3986 [RFC3986] 🎯

Issued At

The time at which the assertion was issued. While the serialization may differ by assertion format, it is REQUIRED that the time be expressed in UTC with no time zone component. ⏰

Expires At

The time at which the assertion expires. While the serialization may differ by assertion format, it is REQUIRED that the time be expressed in UTC with no time zone component. ⌛

Assertion ID

A nonce or unique identifier for the assertion. The Assertion ID may be used by implementations that require message de-duplication for one-time use assertions. Any entity that assigns an identifier MUST ensure that there is negligible probability for that entity or any other entity to accidentally assign the same identifier to a different data object. 🌈

5.2. General Assertion Format and Processing Rules 💅

These are the general format and processing rules for using assertions in OAuth:

  • The assertion MUST contain an Issuer. The Issuer identifies the entity that issued the assertion as recognized by the authorization server. If an assertion is self-issued, the Issuer MUST be the value of the client's "client_id". 🪪
  • The assertion MUST contain a Subject. The Subject typically identifies an authorized accessor for which the access token is being requested (i.e., the resource owner or an authorized delegate) but, in some cases, may be a pseudonymous identifier or other value denoting an anonymous user. When the client is acting on behalf of itself, the Subject MUST be the value of the client's "client_id". 🫶
  • The assertion MUST contain an Audience that identifies the authorization server as the intended audience. The authorization server MUST reject any assertion that does not contain its own identity as the intended audience. 🚫
  • The assertion MUST contain an Expires At entity that limits the time window during which the assertion can be used. The authorization server MUST reject assertions that have expired (subject to allowable clock skew between systems). Note that the authorization server may reject assertions with an Expires At attribute value that is unreasonably far in the future. ⏳
  • The assertion MAY contain an Issued At entity containing the UTC time at which the assertion was issued. 🕰️
  • The authorization server MUST reject assertions with an invalid signature or MAC. The algorithm used to validate the signature or message authentication code, and the mechanism for designating the secret used to generate the signature or message authentication code over the assertion, are beyond the scope of this specification. 🔐

6. Common Scenarios 🌸

This section adds extra guidance, beyond the format and processing rules defined in Sections 4 and 5, on how assertions get used in a bunch of common use cases 🦋

6.1. Client Authentication 🎀

A client uses an assertion to authenticate to the authorization server's token endpoint by using the "client_assertion_type" and "client_assertion" parameters, as defined in Section 4.2. The Subject of the assertion identifies the client. If the assertion is self-issued by the client, the Issuer of the assertion also identifies the client 🪞

The example in Section 4.2 shows a client authenticating using an assertion during an access token request.

6.2. Client Acting on Behalf of Itself 🧚‍♀️

When a client is accessing resources on behalf of itself, it does so in a manner analogous to the Client Credentials Grant defined in Section 4.4 of OAuth 2.0 [RFC6749]. This is a special case that combines both the authentication and authorization grant usage patterns. In this case, the interactions with the authorization server should be treated as using an assertion for Client Authentication according to Section 4.2, while using the "grant_type" parameter with the value "client_credentials" to indicate that the client is requesting an access token using only its client credentials. 💜

The following example shows an assertion being used for a client credentials access token request, as defined in Section 4.4.2 of OAuth 2.0 [RFC6749] (extra line breaks added just for display 💖):

POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_assertion_type=urn%3Aietf%3Aparams%3Aoauth
%3Aclient-assertion-type%3Asaml2-bearer&
client_assertion=PHNhbW...[omitted for brevity]...ZT

6.3. Client Acting on Behalf of a User 👑

When a client is accessing resources on behalf of a user, it does so by using the "grant_type" and "assertion" parameters, as defined in Section 4.1. The Subject identifies an authorized accessor for which the access token is being requested (typically, the resource owner or an authorized delegate) ✨

The example in Section 4.1 shows a client making an access token request using an assertion as an authorization grant.

6.3.1. Client Acting on Behalf of an Anonymous User 🙈

When a client is accessing resources on behalf of an anonymous user, a mutually agreed-upon Subject identifier indicating anonymity is used. The Subject value might be an opaque persistent or transient pseudonymous identifier for the user, or it might be an agreed-upon static value indicating an anonymous user (e.g., "anonymous"). The authorization may be based upon additional criteria, such as additional attributes or claims provided in the assertion. For example, a client might present an assertion from a trusted issuer asserting that the bearer is over 18 via an included claim. In this case, no additional information about the user's identity is included, yet all the data needed to issue an access token is present 🌈

More information about anonymity, pseudonymity, and privacy considerations in general can be found in [RFC6973] 🔥

7. Interoperability Considerations ✨

okay so this spec gives you a framework for using assertions with OAuth 2.0 💅 but it's kinda abstract. It doesn't define the data formats for a lot of the values, so on its own it's not enough to get implementations working together 😭

Two other specs profile this framework for specific assertion types. [RFC7522] uses SAML 2.0 Assertions and [RFC7523] uses JSON Web Tokens (JWTs) 🦋 They add the extra details about assertion encoding and processing rules for using those kinds of assertions with OAuth 2.0. Iconic work 👑

Even with those profiles, system entities still have to agree on identifiers, keys, and endpoints, or the deployments won't be interoperable 🥲 The stuff they need to agree on is:

  • values for the Issuer and Audience identifiers
  • supported assertion and client authentication types
  • the location of the token endpoint
  • the key used to apply and verify the digital signature or MAC over the assertion
  • one-time use restrictions on assertions
  • maximum assertion lifetime allowed
  • the specific Subject and attribute requirements of the assertion

Swipe left on this part, bestie, because exchanging that info is explicitly out of scope for this spec 🙅 Deployments for particular trust frameworks, circles of trust, or other use cases will need the participants to agree on the kinds of values used for some of the abstract fields. In some cases, extra profiles may be created that constrain or prescribe these values, or that specify how they're exchanged. The "OAuth 2.0 Dynamic Client Registration Core Protocol" [OAUTH-DYN-REG] is one of those profiles, and it lets OAuth Clients register metadata about themselves at an authorization server 💜

8. Security Considerations 🔐

okay this section is where it gets serious 😤 It talks about the security considerations for using assertions with OAuth 2.0 the way this document describes. Like we said back in Section 3, there are two ways to get an assertion: either it's self-issued, or it comes from a third-party token service 🧚 How you actually get the assertion is outside the scope of this doc, but the details still matter a lot for security. Section 3 covers the high-level architecture. A lot of the stuff in this section applies to both the OAuth exchange and the client getting the assertion, so pay attention 🙈

The rest of this section is about the exchanges where you present an assertion for client authentication or for the authorization grant. Main character energy 👑

8.1. Forged Assertion 🥸

Threat: an adversary could forge or alter an assertion to get an access token (for the authorization grant) or to impersonate a client (for the client authentication mechanism). Not it 💀

Countermeasures: entities have to make sure proper mechanisms for protecting the integrity of the assertion are in use. That includes the issuer digitally signing the assertion or computing a MAC over it 🔏

8.2. Stolen Assertion 🕵️‍♀️

Threat: an adversary may be able to obtain an assertion (say, by eavesdropping) and then reuse it, aka replay it, at a later point in time 😱

Countermeasures: the main fix here is using secure communication channels with server authentication for all network exchanges 🔒

An assertion can also contain several elements that help prevent replay attacks. There's a clear trade-off, though, between reusing an assertion for multiple exchanges and getting brand new, fresh assertions every time ⚖️

Authorization servers and resource servers may use a combo of the Assertion ID and the Issued At/Expires At attributes for replay protection. Previously processed assertions may be rejected based on the Assertion ID. The validity window is what saves the authorization server from having to keep an infinite state table of processed Assertion IDs. Galaxy brain 🧠✨

8.3. Unauthorized Disclosure of Personal Information 🙈

Threat: if other entities can get info about an individual, like authentication info, their role in an organization, or other authorization-relevant info, that raises privacy concerns 😬

Countermeasures: there are two cases to tell apart here 🫶

First, a third party that didn't take part in any of the exchange should be kept from eavesdropping on the assertion's content. You do that by protecting confidentiality of the exchange with TLS. That way, an eavesdropper on the wire can't get the info. BUT this doesn't stop legit protocol entities from getting info they aren't allowed to have from the assertions. Some assertion formats let the assertion be encrypted, so unauthorized parties can't inspect what's inside 🔐

Second, an authorization server might get an assertion that a third-party token service made, and that token service may have put attributes into it. To reduce potential privacy problems, prior consent for releasing that attribute info should be obtained from the resource owner. OAuth doesn't directly give you that capability, but the consent approval can be obtained using other identity management protocols or user consent interactions, or even out-of-band 🤝

For cases where a third-party token service makes assertions for client authentication, privacy concerns are usually lower, since lots of these clients are Web servers and not individual devices run by humans 🖥️ If the assertions are used to authenticate devices or software that can be closely linked to end users, then privacy protection safeguards need to be considered 🛡️

More guidance on privacy-friendly protocol design can be found in [RFC6973] 📚

8.4. Privacy Considerations 💜

An assertion may contain privacy-sensitive info. To keep it from unintended parties, it should only be sent over encrypted channels, like TLS 🔒 If you want to keep certain info from the client, the assertion (or parts of it) should be encrypted to the authorization server 🫣

Deployments should figure out the minimum amount of info needed to finish the exchange, and only put that in the assertion. In some cases, the Subject identifier can be a value that stands for an anonymous or pseudonymous user, like we covered in Section 6.3.1 🎭

9. IANA Considerations 📋

This section registers three values, listed in the subsections below, in the IANA "OAuth Parameters" registry set up by RFC 6749 [RFC6749] 🗂️

9.1. "assertion" Parameter Registration 🦋

  • Name: assertion
  • Parameter Usage Location: token request
  • Change Controller: IESG
  • Specification Document(s): RFC 7521

9.2. "client_assertion" Parameter Registration 🌸

  • Name: client_assertion
  • Parameter Usage Location: token request
  • Change Controller: IESG
  • Specification Document(s): RFC 7521

9.3. "client_assertion_type" Parameter Registration 🍓

  • Name: client_assertion_type
  • Parameter Usage Location: token request
  • Change Controller: IESG
  • Specification Document(s): RFC 7521

10. References 📚

10.1. Normative References 🌈

10.2. Informative References 🧚

Acknowledgements 💖

The authors wish to thank the following people who have influenced or contributed to this specification: Paul Madsen, Eric Sachs, Jian Cai, Tony Nadalin, Hannes Tschofenig, the authors of the OAuth WRAP specification, and the members of the OAuth working group 🫶

Authors' Addresses 👑

Brian Campbell Ping Identity

EMail: brian.d.campbell@gmail.com

Chuck Mortimore Salesforce.com

EMail: cmortimore@salesforce.com

Michael B. Jones Microsoft

EMail: mbj@microsoft.com URI: http://self-issued.info/

Yaron Y. Goland Microsoft

EMail: yarong@microsoft.com

and that's the whole spec, bestie!! 🌈✨ we did it 😭💅

📦 where this page comes from