3.12.3 Identity APIs

Before · SP 800-63C

After · SP 800-63C-4

Identity APIs

Before · SP 800-63C

After · SP 800-63C-4

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.