3.12 Identity Attributes

Other protocols and specifications often refer to attribute bundles as credentials. However, this term would be in conflict with its use within these guidelines for a different concept. Consequently, these guidelines use the term “attribute bundle” instead.

As an alternative to sending attributes directly from the IdP in an assertion or identity API, attribute values and derived attribute values can be collected into bundles that are signed by the CSP. These attribute bundles can be verified by the RP using the cryptographic protections of the attribute bundle, independently of protections provided by the IdP. Attribute bundles are commonly used by subscriber-controlled wallets. Some examples of technologies used to bundle attributes are Selective Disclosure JSON Web Tokens [SD-JWT], the Verifiable Credentials Data Model defined in [VC], and the mDoc Mobile Security Object defined in [ISOIEC18013-5].

The presentation of an attribute bundle SHALL be protected by the IdP in the same manner as non-bundled attributes. That is, attribute bundles that are presented in an assertion are covered by the signature of the assertion, and attribute bundles that are made available by an identity API are protected by the limited access controls to that API.

Attribute bundles include one or more attribute values and derived attribute values along with an identifier for the issuing CSP. One of these attribute values could function as a subscriber identifier if the issuing CSP ensures the uniqueness of this value across its subscribers. Since attribute bundles are carried in the assertion from the IdP, the subscriber attributes within the bundle do not need to be fully disclosed to all RPs on every transaction and can instead be selectively disclosed to the RP. An attribute bundle using selective disclosure technology can increase the privacy of a system by limiting which attributes an RP can read from the attribute bundle without needing a new bundle to be issued to the IdP. The RP can still verify the signature of the attribute bundle as a whole and confirm the bundle’s source as the CSP without the IdP having to disclose all of the contents of the attribute bundle to the RP.

The RP SHALL validate the signature specific to the attribute bundle as well as any container signatures, such as the signature of the assertion as a whole.

An attribute bundle MAY optionally include a verification key for the IdP to which the bundle has been issued. In such cases, the RP SHALL confirm that the assertion is presented by the identity claimed in the attribute bundle by verifying the signature over the assertion using the IdP’s verification key in the signed attribute bundle.

For some use cases, knowing the actual value of an identity attribute is not strictly necessary for the RP to function, and a value derived from the identity attribute is sufficient. For example, if the RP needs to know whether the subscriber is above the age of majority, the RP could request the subscriber’s birth date and calculate the majority age question from this value. However, doing so reveals more specific information to the RP than is truly needed for the RP’s functional requirements. Instead, the IdP could calculate whether the subscriber’s age meets the definitions for majority at the time of the RP’s request and return a simple boolean for this derivation instead of the birth date value itself. The RP can then continue its processing without needing to see the underlying value.

Derived attribute values increase the privacy of a system since they allow a more focused release of information to the RP. While some federation systems allow the RP to dynamically query for an arbitrary derived attribute value at request time, many common use cases can be accommodated by the IdP pre-calculating common derived attribute values and offering them as alternatives to the full attribute value. To preserve privacy, derived attribute values SHALL NOT disclose the underlying attribute value to a requester. Selective disclosure technology, as found in some attribute bundles, can be used to carry both full attribute values and derived attribute values in the same response, disclosing only that which is necessary for the application.

Derived attribute values are directly included in assertions (see Sec. 4.9 and Sec. 5.8) or included in attribute bundles (see Sec. 3.12.1).

Attributes about the subscriber, including profile information, MAY be provided to the RP through a protected API known as the identity API. The RP is granted limited access to the identity API during the federation transaction in concert with the assertion. For example, in OpenID Connect, the UserInfo Endpoint provides a standardized identity API for fetching attributes about the subscriber. This API is protected by an OAuth 2.0 Access Token, which is issued to the RP along with OpenID Connect’s assertion, the ID Token. Identity APIs SHOULD require sender-constrained access to ensure that identity information is only made available to authorized RPs.

By making attributes available at an identity API, the IdP no longer has to use the assertion to convey as much information to the RP. This not only means that sensitive attributes do not have to be carried in the assertion itself but also makes the assertion smaller and easier to process by the RP. The contents of the assertion can then be limited to essential fields (e.g., unique subject identifiers), information about the authentication event at the IdP, and information about the federation transaction.

Identity APIs also make it possible for the RP to help manage the transmission of subscriber attributes from the IdP. The RP often caches attributes that are provided by the IdP in an RP subscriber account (see Sec. 3.8), and the RP can record when these attributes were last received from the IdP. The RP can request subscriber attributes only when needed to update the RP subscriber account, instead of receiving them on every federation transaction in the assertion. The IdP can aid this decision by indicating in the assertion the time at which any of the subscriber attributes available to the RP were updated at the IdP. This approach is particularly helpful when a subscriber’s attributes are stable over time, allowing the RP to function without fetching them on every request.

All possible use of identity APIs, including which provisioning models are available through the API, SHALL be recorded and disclosed as part of the trust agreement. Access to the identity API SHALL be time-limited by the trust agreement. Access to the identity API SHOULD be limited to the duration of the federation transaction plus the time necessary to synchronize attributes, as discussed in Sec. 4.6.4. Since the time limitation is separate from the validity time window of the assertion and the lifetime of the authenticated session at the RP, access to an identity API by the RP without an associated valid assertion SHALL NOT be sufficient for the establishment of an authenticated session at the RP.

A given identity API deployment is expected to be capable of providing attributes for all subscribers for whom the IdP can create assertions. However, when access to the identity API is granted within the context of a federation transaction, the attributes provided by an identity API SHALL be associated with only the single subscriber identified in the associated assertion. If the identity API is hosted by the IdP, the returned attributes SHALL include the subject identifier for the subscriber. This allows the RP to positively correlate the assertion’s subject to the returned attributes. When access to an identity API is provided as part of pre-provisioning RP subscriber accounts (see Sec. 4.6.3), the RP is usually granted blanket access to the identity API outside of the context of the federation transaction, and these requirements do not apply. For pre-provisioning use cases, the privacy considerations SHALL be evaluated and recorded as part of the trust agreement. If the identity API is hosted externally from the IdP, the requirements in Sec. 3.12.3.1 apply.