View this document as: a single page | multiple pages.

General-Purpose IdPs

This section is normative.

A general-purpose IdP is an IdP that the CSP uses to make the subscriber account available through a process of provisioning the IdP, as described in Sec. 4.1. The subscriber provides an authentication event to the IdP using one or more authenticators that are bound to the subscriber account, as described in Sec. 4.5. Usually, a general-purpose IdP is hosted on a remote service and not on the subscriber’s device. Often, a general-purpose IdP supports multiple subscribers.

IdP Account Provisioning

In order to make subscriber accounts available through an IdP, the subscriber accounts need to be provisioned at the IdP. The means by which the subscriber account is provisioned to the IdP SHALL be disclosed in the trust agreement.

Due to the requirement for the IdP to be able to authenticate the subscriber, the IdP is often a service of the CSP and has some level of access to the attributes and authenticators in the subscriber account. Such IdPs are generally in the same security domain as the identity and access management system that houses the subscriber account.

In other cases, one or more authenticators in the subscriber account can be verified outside of the security domain, such as authenticators tied to a common PKI. In these cases, the IdP can pull subscriber attributes and account information from the authenticator to provide a federated login to RPs.

The IdP augments the subscriber account with federation-specific attributes, such as a federated identifier. The IdP can collect additional attributes for federation purposes subject to the privacy and storage requirements enumerated by the trust agreement.

The CSP can provide attributes from the subscriber account to the IdP as attribute values, derived attribute values, or attribute bundles. The CSP SHALL sign attribute bundles issued to the IdP.

After the subscriber account is provisioned to the IdP, the CSP is party to the trust agreement but is not directly involved in the federation transaction. Consequently, even if the RP fetches attributes through an identity API that is hosted by the CSP, the identity API is considered a function of the IdP and not the CSP for the purposes of these guidelines.

Federation Transaction

A federation transaction that involves a general-purpose IdP establishes the subscriber account at the IdP and culminates in an authenticated session for the subscriber at the RP. This process is shown in Fig. 6.

Fig. 6. Federation overview

Overview diagram of federated authentication systems showing parties involved and major steps in the process.

A federation transaction is a multi-stage process:

  1. Before federation can occur, the subscriber account is established by the CSP. This account binds the identity attributes collected by the CSP to a set of authenticators used by the subscriber.

  2. The subscriber account is provisioned at the IdP. The IdP augments the subscriber account with federation-specific attributes, such as a federated identifier.

  3. The IdP and RP begin a federated authentication transaction to authenticate a subscriber to the RP.

  4. The subscriber authenticates to the IdP using an authenticator that is bound to the subscriber account. If mandated by the trust agreement, the authorized party (often the subscriber) is prompted to approve the release of identity information at runtime.

  5. The IdP creates an assertion to represent the results of the authentication event. The assertion is based on the terms established by the trust agreement, the request from the RP, the capabilities of the IdP, the subscriber account known to the IdP, and the attributes permitted by the authorized party.

  6. The assertion is passed to the RP across the network.

  7. The RP processes this assertion from the IdP and establishes an authenticated session with the subscriber. Optionally, the RP receives identity attributes from the IdP that represents the subscriber account, either in the assertion or through an identity API.

Federated transactions are enabled by trust agreements, as described in Sec. 3.5. These trust agreements define which parties are fulfilling which roles, the terms under which the parties operate with each other, permission for the systems in question to connect, and the terms under which the parties interact with each other. A single trust agreement often covers multiple federation transactions. The list of available subscriber identity attributes, derived attributes, and attribute bundles is established in the trust agreement, though the decision of which attributes are released to a given RP for a given transaction is finalized during the federation transaction itself. The final set of attributes, derived attribute values, and attribute bundles to be passed to the RP is selected by processing the following:

The IdP and RP also need to perform discovery and registration to establish the cryptographic keys and identifiers that are needed for information to be securely exchanged between the parties in the federation protocol (see Sec. 4.4). While there may be an existing policy decision that represents a permission to connect (through a pre-established trust agreement), this step entails a connection and integration at the technical level. At any FAL, this stage can occur before subscribers try to access the RP. At FAL1 or FAL2, this stage could alternatively occur in response to a subscriber’s attempt to use an IdP at an RP.

In a federated identity transaction, the IdP is the source of identity and authentication attributes for the RP. The normal flow of information for a federation transaction is from the IdP to the RP. Due to the directional nature of this information flow, the IdP is considered to be upstream of the RP and the RP is considered to be downstream of the IdP. It is also possible for additional information to flow back up from the RP, particularly through the use of shared signals, as discussed in Sec. 4.8.

Trust Agreements

Trust agreements for general-purpose IdPs are generally expected to be established between the RP and the IdP, where the RP relies on the identity of the IdP to provide the basis of trust for federation transactions. It is expected that the trust agreement between the CSP and IdP is established independent of the federation transaction.

Trust agreements for general-purpose IdPs SHALL be established either:

Pre-Established Trust Agreements

When the trust agreement is established by the federated parties prior to the federation transaction, the trust agreement SHALL establish the following terms:

The terms of the trust agreement SHALL be available to the operators of the RP and the IdP upon its establishment. The terms of the trust agreement SHALL be made available to subscribers upon request to the IdP or RP.

The IdP and RP SHALL each assess their respective redress mechanisms for efficacy in resolving complaints or problems and disclose the results of this assessment as part of the trust agreement. See Sec. 3.5.3 for additional requirements and considerations for redress mechanisms.

If FAL3 is allowed within the trust agreement, the trust agreement SHALL stipulate the following terms regarding holder-of-key assertions (see Sec. 3.15) and bound authenticators (see Sec. 3.16):

If shared signaling is used by the IdP or RP (see Sec. 4.8), the terms of the trust agreement SHALL establish:

Runtime decisions at the IdP (see Sec. 4.6.1.3), MAY be used to further limit which subscriber attributes are sent between parties in the federated transaction (e.g., a runtime decision could opt to not disclose an email address, even though this attribute was included in the terms of the trust agreement).

The trust agreement SHALL be reviewed periodically to ensure that it is still fit for purpose and to avoid unnecessary data exchange and the over-collection of subscriber data.

Subscriber-Driven Trust Agreement Establishment

When the trust agreement is established as the result of a subscriber’s decision (e.g., a subscriber starting a federation transaction between an RP and their IdP without an established agreement), the trust agreement is anchored by the subscriber. In a subscriber-driven trust agreement, the trust agreement takes the form of a set of terms of use as opposed to a formal contract between parties. Consequently, the following terms SHALL be disclosed to the subscriber upon request:

The IdP SHALL assess its redress mechanisms for efficacy in resolving complaints or problems and disclose the results of this assessment to the subscriber. See Sec. 3.5.3 for additional requirements and considerations for redress mechanisms.

The release of subscriber attributes SHALL be managed using a runtime decision at the IdP, as described in Sec. 4.6.1.3. The authorized party SHALL be the subscriber.

The following terms of the trust agreement SHALL be disclosed to the subscriber during the runtime decision:

All information disclosed to the subscriber needs to be conveyed in a manner that is understandable and actionable, as discussed in Sec. 8.

Discovery and Registration

To perform a federation transaction with a general-purpose IdP, the RP has to perform discovery and registration with that IdP, as discussed in Sec. 3.6.

The RP SHALL associate the assertion validation keys and other relevant configuration information with the IdP’s identifier, as stipulated by the trust agreement. If the validation keys and configuration information are retrieved over a network connection, request and retrieval SHALL be made over an authenticated protected channel from a location that is associated with the IdP’s identifier by the trust agreement. In many federation protocols, this is accomplished by the RP fetching the public keys and configuration data from a URL that is specified in the trust agreement as being controlled by the IdP or offered on the IdP’s behalf. It is also possible for the RP to be configured directly with this information in a manual fashion, whereby the RP’s system administrator enters the IdP information directly into the RP software’s configuration.

In some systems, particularly those governed by multi-lateral trust agreements, the discovery process can be facilitated by a third-party discovery and registration service.

Additionally, the RP SHALL register its information with either the IdP or an authority that the IdP trusts, as stipulated by the trust agreement. In many federation protocols, the RP is assigned an identifier during this stage, which the RP will use in subsequent communication with the IdP.

Parties that seek to federate MAY use a trusted third party to facilitate the discovery and registration processes if that trusted third party is identified in the trust agreement. For example, a consortium could use a hosted service that collects the configuration records of IdPs and RPs directly from participants. Instead of going to the IdP directly for its discovery record, an RP would instead go to this service and retrieve the key material for its target IdP. The IdP would, in turn, go to this service to find the identifiers and configuration information for RPs that are needed to connect. This service is often managed by the same party that fulfills the federation authority role in multilateral trust agreements, as discussed in Sec. 3.5.2.

Manual Registration

At all FALs, the cryptographic keys and identifiers of the RP and IdP can be exchanged in a manual process, whereby the system administrator of the RP submits the RP’s configuration to the IdP either directly or through a trusted third party and receives the identifier to use with that IdP. The RP system administrator then configures the RP with this identifier and any additional information needed for the federation transaction to continue.

As this is a manual process, the registration happens prior to the federation transaction.

This process MAY be facilitated by some level of automated tooling, whereby the manual configuration points the systems in question to a trusted source of information that can be updated over time. If such automation is used, the trust agreement SHALL enumerate the allowable terms of the cryptographic key distribution and assignment, including allowable cache lifetimes.

Dynamic Registration

At FAL1 and FAL2, the cryptographic keys and identifiers of the RP can be exchanged in a dynamic process, whereby the RP software presents its configuration to the IdP either directly or through a trusted third party and receives the identifier to use with that IdP. This process is specific to the federation protocol in use but requires machine-readable configuration data to be made available over the network. All transmission of configuration information SHALL be made over a secure protected channel to endpoints that are associated with the IdP’s identifier by the trust agreement.

IdPs SHOULD consider the risks of information leakage to multiple RP instances and take appropriate countermeasures, such as issuing PPIs for subscribers who access dynamically registered RPs, as discussed in Sec. 3.4.1.

Dynamic registration SHOULD be augmented by attestations about the RP software and device, as discussed in Sec. 3.6.3.

[OIDC-Registration] defines a protocol for the dynamic registration of RPs at an OpenID Connect IdP.

Subscriber Authentication at the IdP

In a federation context, the IdP acts as the verifier for authenticators bound to the subscriber account, as described in [SP800-63B]. Verification of one or more authenticators creates an authentication event that begins the authenticated session at the IdP. This authentication event serves as the basis of the IdP’s claim that the subscriber is present.

The IdP SHALL require the subscriber to have an authenticated session before any of the following events:

Additional requirements for session management and reauthentication are discussed in Sec. 4.7.

Authentication and Attribute Disclosure

The authorized party stipulated by the trust agreement SHALL decide whether a federation transaction proceeds and, therefore, whether an assertion is issued and attributes are released to the RP. This decision can be calculated in a variety of ways, including:

The applicability of an allowlist, blocklist, or runtime decision can be influenced by aspects of the federation transaction, including the identity of the IdP and RP, the subscriber attributes requested, the xAL required, and other factors. These decisions can be facilitated by risk management systems, federation authorities, and local system policies.

For a non-normative example of an RP that has been allowlisted at an IdP for a set of subscribers to facilitate single sign-on for an enterprise application, see Sec. 9.5.

The IdP SHALL provide effective mechanisms for the redress of subscriber complaints or problems (e.g., subscriber identifies an inaccurate attribute value). See Sec. 3.5.3 for additional requirements and considerations for redress mechanisms.

IdP-Controlled Decisions

IdP Allowlists of RPs

In a pre-established trust agreement, IdPs MAY establish allowlists of RPs that are authorized to receive authentication and attributes from the IdP without a runtime decision from the subscriber. When placing an RP on its allowlist, the IdP SHALL confirm that the RP abides by the terms of the trust agreement. The IdP SHALL determine which identity attributes are passed to the allowlisted RP upon authentication. IdPs SHALL make allowlists available to subscribers, as described in Sec. 7.2.

IdP allowlists SHALL uniquely identify RPs through fully qualified domain names, cryptographic keys, or other identifiers that are applicable to the federation protocol in use. Any entities that share an identifier SHALL be considered equivalent for the purposes of the allowlist. Allowlists SHOULD be as specific as possible to avoid unintentional impersonation of an RP. An allowlist entry for an RP SHALL NOT use a wildcard domain identifier.

IdP allowlist entries for an RP SHALL indicate which attributes are included as part of an allowlisted decision. If additional attributes are requested by the RP, the request SHALL be:

IdP allowlist entries MAY be applied based on aspects of the federation transaction, such as the xALs required for the transaction. For example, an IdP could use an allowlist entry to bypass a consent screen for an FAL1 transaction but require confirmation of consent from the subscriber during an FAL3 transaction.

IdP Blocklists of RPs

IdPs MAY establish blocklists of RPs that are not authorized to receive authentication assertions or attributes from the IdP, even if requested to do so by the subscriber. If an RP is on an IdP’s blocklist, the IdP SHALL NOT produce an assertion that targets the RP in question under any circumstances.

IdP blocklists SHALL uniquely identify RPs through the means of fully qualified domain names, cryptographic keys, or other identifiers that are applicable to the federation protocol in use. Any entities that share an identifier SHALL be considered equivalent for the purposes of the blocklist. For example, a wildcard domain identifier of “*.example.com” would match the domains “www.example.com”, “service.example.com”, and “unknown.example.com” equally. All three of these sites would be blocked by the same blocklist entry.

IdP Runtime Decisions

Every RP that is in a trust agreement with an IdP but not on an allowlist with that IdP SHALL be governed by a default policy in which runtime authorization decisions will be made by an authorized party that is identified by the trust agreement. Since the runtime decision occurs during the federation transaction, the authorized party is generally a person and, in most circumstances, is the subscriber. However, it is possible for another party such as a system administrator to be prompted on behalf of the subscriber. In a subscriber-driven trust agreement, a runtime decision with the subscriber is the only allowable means to authorize the release of subscriber attributes.

When processing a runtime decision, the IdP interactively prompts the authorized party during the federation transaction. The authorized party provides consent to release an authentication assertion and specific attributes to the RP. The IdP SHALL provide the authorized party with explicit notice and prompt them for positive confirmation before any attributes about the subscriber are transmitted to the RP. At a minimum, the notice SHOULD be provided by the party in the position to provide the most effective notice and obtain confirmation, consistent with Sec. 7.2. The IdP SHALL disclose which attributes will be released to the RP if the transaction is approved. If the federation protocol in use allows for optional or selective attribute disclosure at runtime, the authorized party SHALL be given the option to decide whether to transmit specific attributes to the RP without terminating the federation transaction entirely.

If the authorized party is the subscriber, the IdP SHALL provide mechanisms for the subscriber to view the attribute values and derived attribute values to be sent to the RP. To mitigate the risk of unauthorized exposure of sensitive information (e.g., shoulder surfing), the IdP SHALL, by default, mask sensitive information displayed to the subscriber. For more details on masking, see Sec. 8 on usability considerations.

An IdP MAY employ mechanisms to remember the authorized party’s decision and re-transmit the same set of attributes to the same RP. This mechanism is associated with the subscriber account as managed by the IdP. If such a mechanism is provided, the IdP SHALL disclose to the authorized party that the storage mechanism is in use and SHALL allow the authorized party to revoke such remembered access at a future time.

RP-Controlled Decisions

RP Allowlists of IdPs

RPs MAY establish allowlists of IdPs from which the RP will accept authentication and attributes without a runtime decision from the subscriber to use the IdP. In practice, many RPs interface with only a single IdP, and this IdP is allowlisted as the only possible entry for that RP. When placing an IdP in its allowlist, the RP SHALL confirm that the IdP abides by the terms of the trust agreement. This confirmation can be facilitated by a federation authority or undertaken directly by the RP.

RP allowlists SHALL uniquely identify IdPs through fully qualified domain names, cryptographic keys, or other identifiers that are applicable to the federation protocol in use. Allowlists SHOULD be as specific as possible to avoid unintentional impersonation of an IdP. An allowlist entry for an IdP SHALL NOT use a wildcard domain identifier.

RP allowlist entries MAY be applied based on aspects of the federation transaction, such as the xALs required for the transaction. For example, an RP could use a runtime decision for FAL1 transactions but require an allowlisted IdP for FAL3 transactions.

RP Blocklists of IdPs

RPs MAY establish blocklists of IdPs from which the RP will not accept authentication or attributes, even when requested by the subscriber. A blocklisted IdP can otherwise be in a valid trust agreement with the RP, such as when both are under the same federation authority.

RP blocklists SHALL uniquely identify IdPs through fully qualified domain names, cryptographic keys, or other identifiers that are applicable to the federation protocol in use. Any entities that share an identifier SHALL be considered equivalent for the purposes of the blocklist. For example, a wildcard domain identifier of “*.example.com” would match the domains “www.example.com”, “service.example.com”, and “unknown.example.com” equally. All three of these sites would be blocked by the same blocklist entry.

RP Runtime Decisions

Every IdP that is in a trust agreement with an RP but not on an allowlist with that RP SHALL be governed by a default policy in which runtime authorization decisions will be made by the authorized party indicated in the trust agreement. In this mode, the authorized party is prompted by the RP to select or enter which IdP to contact for authentication on behalf of the subscriber. This process can be facilitated by a discovery mechanism that allows the subscriber to enter a human-facing identifier, such as an email address that is then used to programmatically select the IdP for the entered address. Since the runtime decision occurs during the federation transaction, the authorized party is generally a person and, in most circumstances, the subscriber.

The RP MAY employ mechanisms to remember the authorized party’s decision to use a given IdP. Since this mechanism is employed prior to authentication at the RP, the manner in which the RP provides this mechanism (e.g., a browser cookie outside of the authenticated session) is separate from the RP subscriber account, as described in Sec. 3.8. If such a mechanism is provided, the RP SHALL disclose to the authorized party that the storage mechanism is in use and SHALL allow the authorized party to revoke such remembered access at a future time.

Provisioning Models for RP Subscriber Accounts

The life cycle of the provisioning process for an RP subscriber account varies based on factors including the trust agreement discussed in Sec. 3.5 and the deployment pattern of the IdP and RP. However, in all cases, the RP subscriber account SHALL be provisioned at the RP prior to the establishment of an authenticated session at the RP in one of the following ways:

Just-In-Time Provisioning
An RP subscriber account is created the first time that the RP receives an assertion with an unknown federated identifier from an IdP, an RP subscriber account does not exist, or an existing RP subscriber account can be resolved using an account resolution process, as described in Sec. 3.8.2. Any identity attributes learned during the federation process, either within the assertion or through an identity API as discussed in Sec. 3.12.3, MAY be associated with the RP subscriber account. Accounts that are provisioned in this way are bound to the federated identifier in the assertion used to provision them. This is the most common form of provisioning in federation systems, as it requires the least coordination between the RP and IdP. However, in such systems, the RP SHALL be responsible for managing any cached attributes it might have. See Fig. 7.

Fig. 7. Just-in-time provisioning

Diagram of the stages of a just-in-time provisioning of an RP subscriber account based on a subscriber account.

Pre-Provisioning
An RP subscriber account is created or linked to an existing RP subscriber account by the IdP pushing the attributes to the RP or the RP pulling attributes from the IdP. Pre-provisioning of accounts generally occurs in bulk through a provisioning API (see Sec. 4.6.5), as the provisioning occurs prior to the represented subscribers authenticating through a federation transaction. Pre-provisioned accounts SHALL be bound to a federated identifier at the time of provisioning, unless an alternative means of access is defined by the trust agreement, such as an account linking policy (see Sec. 3.8.1), an account resolution policy (see Sec. 3.8.2), or alternative authentication mechanisms (see Sec. 3.8.3). This form of provisioning requires infrastructure and planning on the part of the IdP and RP, but these processes can be facilitated by automated protocols. Additionally, the IdP and RP must keep the set of provisioned accounts synchronized over time, as discussed in Sec. 4.6.4. See Fig. 8.

In this model, the RP also receives attributes about subscribers who have not yet interacted with the RP and who may never do so. This is in contrast to other models in which the RP only receives information about the subset of subscribers that use the RP, and then only after the subscriber uses the RP for the first time. The privacy considerations of the RP having access to this information prior to a federation transaction SHALL be accounted for in the trust agreement.

Fig. 8. Pre-provisioning

Diagram of the stages of a pre-provisioned RP subscriber account based on a subscriber account.

Ephemeral Provisioning
When processing an assertion, the RP establishes a link between that assertion and a new or existing RP subscriber account but removes that link when the authenticated session ends. This process is similar to just-in-time provisioning, but the RP keeps no long-term record of the subscriber when the session is complete, in accordance with Sec. 3.11.3. This form of provisioning is useful for RPs that fully externalize access rights to the IdP, allowing the RP to be more simplified with less internal state. If this form of provisioning is used, the federated identifier is not required in the assertion. If a federation identifier is supplied in the assertion, the RP SHALL remove any linkage of the federated identifier from an RP subscriber account. See Fig. 9.

Fig. 9. Ephemeral provisioning

Diagram of the stages of an ephemeral RP subscriber account based on a subscriber account.

Other Provisioning Methods
While other RP subscriber account provisioning models are possible, the details of such models are outside of the scope of these guidelines. However, the details of any alternative provisioning model SHALL be included in the privacy risk assessments of the IdP and RP.

All organizations SHALL document their provisioning models as part of their trust agreement.

Attribute Synchronization

In a federated process, the IdP and RP each have their own stores of identity attributes that are associated with the subscriber account. The IdP has a direct view of the subscriber account’s attributes, but the RP subscriber account is derived from a subset of attributes that are presented during the federation transaction. Therefore, it is possible for the IdP and RP’s attribute stores to diverge from each other over time.

From the RP’s perspective, the IdP is the trusted source for any attributes that the IdP asserts as being associated with the subscriber account at the IdP. However, the RP MAY collect and optionally verify other attributes to associate with the RP subscriber account, as discussed in Sec. 4.6.6.

While it is possible for the IdP to proactively push updated attributes to the RP with every assertion, this practice exposes personal information on every transaction. To limit the amount of personal information sent at each transaction, the IdP SHOULD signal downstream RPs when the attributes of a subscriber account available to the RP have been updated. RPs MAY respond to this signal by requesting the new attributes from the IdP and updating the RP subscriber account. This synchronization can be accomplished by using shared signaling (see Sec. 4.8), through a provisioning API (see Sec. 4.6.5), or by signaling the RP (e.g., by providing a timestamp of when the subscriber account attributes were last updated) to request updated attributes through an identity API (see Sec. 3.12.3).

If the RP is granted access to an identity API, the IdP SHOULD allow the RP to access the identity API for sufficient time to perform synchronization operations after the federation transaction has concluded. While an identity API is most often used during the first login, especially with a just-in-time provisioning process, on subsequent logins it is possible that attributes could have changed since the RP last fetched them. Therefore, the RP ought to be given access to the identity API beyond the initial login process to allow the RP to update its cache of attributes in the RP subscriber account. For example, if the assertion is valid for five minutes, access to the identity API could be valid for 30 minutes to allow the RP to fetch and update attributes out of band if the RP has determined that the RP subscriber account is out of date.

The IdP SHOULD signal downstream RPs when a subscriber account is terminated or when the subscriber account’s access to an RP is revoked. This can be accomplished through shared signaling (see Sec. 4.8), through a provisioning API (see Sec. 4.6.5), or through an out-of-band mechanism. Upon receiving such a signal, the RP SHALL process the RP subscriber account, as stipulated in the trust agreement and in accordance with Sec. 3.11.3. If the reason for termination is suspicious or fraudulent activity, the IdP SHALL notify the RP of the termination and include the reason in its signal to the RP to allow the RP to review the associated RP subscriber account’s activity for suspicious activity, if specified in the trust agreement with that RP.

Provisioning APIs

As part of pre-provisioning, the RP can be given access to subscriber attributes through a general-purpose identity API known as a provisioning API. This type of API allows an IdP to push attributes for a range of subscriber accounts and sometimes allows an RP to directly query the attributes of these subscriber accounts. Since access to the API is granted outside of the context of a federation transaction, access to the provisioning API for a given subscriber does not indicate to the RP that a given subscriber has been authenticated.

The attributes in the provisioning API that are available to a given RP SHALL be limited to only those necessary for the RP to perform its functions, including any audit and security purposes, as discussed in Sec. 3.10.1. As part of establishing the trust agreement, the IdP SHALL document when an RP is given access to a provisioning API, including at least the following:

Access to the provisioning API SHALL occur over a mutually authenticated protected channel. The exact means of authentication varies depending on the specifics of the API and whether it is a push model (i.e., the IdP initiates the connection to the RP) or a pull model (i.e., the RP initiates the connection to the IdP).

A provisioning API SHALL NOT be made available under a subscriber-driven trust agreement. The IdP SHALL NOT make a provisioning API available to any RP outside of an established trust agreement. The IdP SHALL provide access to a provisioning API only as part of a federated identity relationship with an RP to facilitate federation transactions with that RP and related functions, such as signaling revocation of the subscriber account. The IdP SHALL revoke an RP’s access to the provisioning API once access is no longer required by the RP for its functioning purposes or when the trust agreement is terminated.

Any provisioning API provided to the RP SHALL be under the control and jurisdiction of the IdP. External attribute providers MAY be used as information sources by the IdP to provide attributes through this provisioning API, but the IdP is responsible for the content and accuracy of the information provided by the referenced attribute providers.

When a provisioning API is in use, the IdP SHALL signal to the RP when the state of a subscriber account has been changed, such as when the account has been terminated or disabled. When receiving such a signal, the RP SHALL remove the binding of the federated identifier from the account. The RP MAY terminate the RP subscriber account if it can no longer be accessed by the subscriber. The RP SHALL treat all personal information sourced from the provisioning API in accordance with Sec. 3.11.3.

Provisioning APIs, such as SCIM [RFC7644], are often used in enterprise scenarios in which there is an established relationship between the IdP and RP, as shown in the example in Sec. 9.5.

Collection of Additional Attributes by the RP

The RP MAY collect and maintain additional attributes from the subscriber beyond those provided by the IdP. For example, the RP could collect a preferred display name directly from the subscriber that is not provided by the IdP. The RP could also have a separate agreement with an attribute provider that gives the RP access to an identity API that is not associated with the IdP. For example, the RP could receive a state license number from the IdP but use a separate attribute verification API to check whether a particular license number is currently valid. The assertion from the IdP binds the license to the subscriber, but the attribute verification API provides additional information beyond what the IdP can share or be authoritative for.

These attributes are governed separately from the trust agreement since they are collected by the RP outside of a federation transaction. However, all attributes in the RP subscriber account — regardless of source — SHALL be stored in accordance with Sec. 3.11.3.

The RP SHALL disclose to the subscriber the purpose for collecting any additional attributes. These attributes SHALL be used solely for the stated purposes of the RP’s functionality. The transmission of additionally collected attributes SHALL be handled in accordance with Sec. 3.10.1.

The RP SHALL provide a secure and effective means of redress for the subscriber to update and remove these additionally collected attributes from the RP subscriber account. See Sec. 3.5.3 for additional requirements and considerations for redress mechanisms.

The following requirement applies to federal agencies, regardless of whether they operate their own identity service or use an external CSP as part of their identity service:

Time-Based Removal of RP Subscriber Accounts

If an RP is using a just-in-time provisioning mechanism, the RP only learns of the existence of a subscriber account when that account is first used at the RP. If the IdP does not inform the RP of terminated subscriber accounts using shared signaling (see Sec. 4.8), an RP could accumulate RP subscriber accounts that are no longer accessible from the IdP. This poses a risk to the RP for holding personal information in the RP subscriber accounts and providing potentially exploitable accounts for an attacker to target. In such circumstances, the RP MAY employ a time-based mechanism to identify RP subscriber accounts for termination that have not been accessed after a period of time that is tailored to the usage patterns of the application. For example, an RP that is usually accessed on a weekly basis could set a timeout of 120 days since last access at the RP to mark the RP subscriber account for termination. An RP that expects longer gaps between access (e.g., a service used annually) should have a much longer time frame for time-based termination, such as five years.

When processing an inactive account, the RP SHALL provide sufficient notice to the subscriber about the pending termination of the account and provide the subscriber with an option to re-activate the account prior to its scheduled termination. Upon termination, the RP SHALL remove all personal information associated with the RP subscriber account in accordance with Sec. 3.11.3.

Reauthentication and Session Requirements in Federated Environments

In a federated environment, the RP manages its sessions separately from any sessions at the IdP. The assertion is related to both sessions, but its validity period is ultimately independent of them.

As shown in Fig. 10, an assertion is created during an authenticated session at the IdP, and processing an assertion creates an authenticated session at the RP. The validity time window of an assertion is used to manage the RP’s processing of the assertion but does not indicate the lifetime of the authenticated session at the IdP or RP. If a request comes to the IdP for a new federation transaction while the subscriber’s session is still valid at the IdP, a new and separate assertion would be created with its own validity time window. Similarly, after the RP consumes the assertion, the validity of the RP’s session is independent of the validity of the assertion. In most cases, the authenticated session at the RP will far outlive the validity of the assertion. Access granted to an identity API is likewise independent of the validity of the assertion or the lifetime of the authenticated session at the RP.

Fig. 10. Session lifetimes

Diagram of the relationship between session lifetimes at the IdP and RP and assertion validity window.

The IdP terminating the subscriber’s session at the IdP will not necessarily terminate any sessions that subscriber might have at downstream RPs. The RP and IdP MAY communicate end-session events to each other if supported by the federation protocol or through shared signaling (see Sec. 4.8).

At the time of a federated transaction request, the subscriber could have a pre-existing authenticated session at the IdP that MAY be used to generate an assertion to the RP. The IdP SHALL communicate to the RP any information that the IdP has regarding the recency of the subscriber’s latest authentication event at the IdP, and the RP MAY use this information to make authorization and access decisions. Depending on the capabilities of the federation protocol in use, the IdP SHOULD allow the RP to request that the subscriber provide a fresh authentication at the IdP, such as requesting a maximum time since the subscriber’s last authentication event. For example, suppose that the subscriber authenticates at the IdP for one transaction. The subscriber then starts a federation transaction at the RP 30 minutes later. Depending on xAL requirements, the subscriber’s existing session at the IdP can be used to avoid prompting the subscriber for their authenticators. The resulting assertion to the RP will indicate that the last time the subscriber authenticated to the RP was 30 minutes in the past. The RP can then use this information to determine whether this is reasonable for the RP’s needs. If the authentication time is not sufficient for the RP, the RP can request the IdP to prompt the subscriber for a fresh authentication event.

If an RP is granted access to an identity API at the same that time the RP receives an assertion, the lifetime of the access to the identity API is independent of the lifetime of the assertion. As a consequence, the RP’s ability to successfully fetch additional attributes through an identity API SHALL NOT be used to establish or extend a session at the RP. Likewise, the inability to access an identity API SHOULD NOT be used to end the session at the RP.

While an RP could also be granted access to other non-identity APIs during the federation transaction (e.g., a subscriber’s calendar), non-identity APIs are out of the scope of these guidelines.

The RP MAY terminate its authenticated session with the subscriber or restrict access to the RP’s functions if the assertion, authentication event, or attributes do not meet the RP’s requirements. For example, if an RP is configured to allow access to certain high-risk functionality only if the federation transaction was at FAL3, but the incoming assertion only meets the requirements for FAL2, the RP could decide to deny access to the high-risk functionality while allowing access to a lower risk functionality, or the RP could choose to terminate the session entirely.

See [SP800-63B] Sec. 5 for more information about session management requirements that apply to both IdPs and RPs.

Shared Signaling

In some environments, it is useful for the IdP and RP to send information to each other outside of the federation transaction. These signals can communicate important changes in state between parties that would not otherwise be known, such as suspected fraud or an account status change. Shared signaling SHALL be limited to the allowable functions of the identity process, as discussed in Sec. 3.10.1. All uses of shared signaling SHALL be documented in the trust agreement and made available to the authorized party stipulated by the trust agreement. This documentation SHALL include the events under which a signal is sent, the type of information included in such a signal (including any personal information), any additional parameters sent with the signal, and the expected processing of a received signal. The use of shared signaling SHALL be subject to privacy review under the trust agreement. Shared signals SHALL NOT include personal information except what is necessary to identify the subscriber account in question (e.g., an account identifier or attributes that can be correlated by the receiving party).

Signaling from the IdP to the RP SHALL require a pre-established trust agreement. Signaling from the RP to the IdP MAY be used in both pre-established and subscriber-driven trust agreements.

The IdP SHOULD send a signal to the RP regarding the following changes to the subscriber account:

If the RP receives a signal that an RP subscriber account is suspected of compromise, the RP SHOULD review actions taken by that account at the RP for suspicious activity.

The RP SHOULD send a signal to the IdP regarding the following changes to the RP subscriber account:

If the IdP receives a signal that a subscriber account is suspected of compromise, the IdP SHALL review actions taken by that account at the IdP for suspicious activity. If suspicious activity is confirmed at the IdP, the IdP SHALL signal any additional RPs that the subscriber account was used for during the suspected time frame.

Additional signals from both the IdP and RP SHALL be subject to a security review, included in the privacy risk assessment, and addressed in the trust agreement.

If the RP allows for account linking to multiple IdPs, the RP SHALL document their practices regarding signals for linked accounts. The RP SHALL ensure that the shared signals do not reveal the identity of a subscriber’s linked IdPs.

Assertion Contents

An assertion is a statement from the IdP to the RP that contains information about an authentication event for an authenticated subscriber as well as a set of attribute values, derived attribute values, or attribute bundles about or associated with that subscriber. In addition to attribute information, assertions comprise a variety of data, including assertion metadata, information about the subscriber’s authentication at the IdP, and other information that the RP can leverage (e.g., restrictions, validity time window). While the assertion’s primary function is to authenticate the user to an RP, the information conveyed in the assertion can be used by the RP for a number of use cases (e.g., identity proofing, authorization, personalization of a website). These guidelines do not restrict RP use cases nor the type of protocol or data payload used to federate an identity, provided that the chosen solution meets all mandatory requirements contained herein.

Assertions SHALL represent a discrete authentication event of the subscriber at the IdP and SHALL be processed as a discrete authentication event at the RP.

All assertions SHALL include the following attributes:

  1. Issuer identifier: An identifier for the issuer of the assertion (i.e., the IdP).
  2. Audience identifier: An identifier for the party intended to consume the assertion (i.e., the RP). An assertion can contain more than one audience identifier at FAL1.
  3. Issuance time: A timestamp that indicates when the IdP issued the assertion.
  4. Validity time window: A period of time outside of which the assertion SHALL NOT be accepted as valid by the RP for the purposes of authenticating the subscriber and starting an authenticated session at the RP. This is usually communicated by means of an expiration timestamp for the assertion in addition to the issuance timestamp.
  5. Assertion identifier: A value that uniquely identifies this assertion and is used to prevent attackers from replaying prior assertions.
  6. Authentication time: A timestamp that indicates when the IdP last verified the presence of the subscriber at the IdP through a primary authentication event.
  7. Signature: Digital signature or MAC, including verification key identifier, that covers the entire assertion.

If the RP subscriber account does not use an ephemeral provisioning process, the subscriber SHALL be identified in the assertion using a federated identifier (see Sec. 3.4) or through an account resolution process (see Sec. 3.8.2).

If the subscriber is identified using a federated identifier, the assertion SHALL include:

The following aspects of the federation transaction SHALL be provided through information contained in the assertion contents or the applicable trust agreement:

  1. The IAL as well as the type of verification used during the identity proofing process (e.g., biometric, address verification), an indication of the identity proofing processes used to establish the subscriber account, or an indication that no IAL is asserted
  2. The AAL used when the subscriber authenticated to the IdP or an indication that no AAL is asserted
  3. The IdP’s intended FAL of the federation process represented by the assertion

The assertion SHOULD contain additional information about the authentication method used at the IdP, if available (e.g., whether the authenticator used is phishing-resistant). Some technologies that can carry information include Vectors of Trust [RFC8485] or authentication class references in [OIDC] and [SAML].

At FAL2 and above, the assertion SHALL include:

  1. Nonce: A cryptographic nonce from the RP’s federation request

At FAL3, the assertion SHALL include one of the following:

  1. The public key, key identifier, or other identifier for a holder-of-key assertion or
  2. An indicator that the verification of a bound authenticator is required to process this assertion.

Assertions SHALL NOT contain subscriber authentication secrets (e.g., passwords).

Assertions MAY also include additional items, including:

  1. Attribute values and derived attribute values: Information about the subscriber
  2. Attribute bundles: Collections of attributes in a signed bundle from the CSP
  3. Subscriber account: Additional details about the subscriber account, such as the set of controls used to obtain the IAL
  4. Attribute metadata: Additional information about one or more subscriber attributes, such as those described in [NISTIR8112]
  5. Authentication event: Additional details about the authentication event, such as the class of authenticators used

The RP SHALL validate the assertion by checking that all of the following are true:

  1. Signature validation: Ensure that the signature of the assertion is valid and corresponds to a verification key that belongs to the IdP sending the assertion.
  2. Issuer verification: Ensure that the assertion was issued by the expected IdP.
  3. Time validation: Ensure that the validity time window is within acceptable limits of the current timestamp.
  4. Audience restriction: Ensure that this RP is the intended recipient of the assertion.
  5. Nonce: Ensure that the cryptographic nonce included in the RP’s request (if applicable) is included in the presentation.
  6. Transaction terms: Ensure that the IAL, AAL, and FAL represented by the assertion are allowable under the applicable trust agreement and are suitable for the RP’s needs.
  7. Assertion identifier: Ensure that the assertion has not been replayed within its validity time window at this RP.

An RP that uses the federated identifier to identify the subscriber SHALL NOT treat subject identifiers as inherently globally unique across IdPs. Instead, the value of the assertion’s subject identifier is processed in a namespace under the assertion issuer’s control, as discussed in Sec. 3.4. This allows an RP to talk to multiple IdPs without incorrectly conflating subjects from different IdPs.

Any release of identity attributes to the RP is subject to the terms of the trust agreement. Section 3.10 contains privacy requirements for presenting attributes in assertions. The RP MAY be given limited access to an identity API (see Sec. 3.12.3), either in the same response as the assertion is received or through some other mechanism. The RP can use this API to fetch additional identity attributes for the subscriber that are not included in the assertion itself. These attributes are also subject to the terms of the trust agreement.

The assertion’s validity time window is the time between its issuance and its expiration. This window needs to be large enough to allow the RP to process the assertion and create a local application session for the subscriber but should not be longer than necessary for such establishment, including reasonable clock drift between the IdP and RP. Long-lived assertions have a greater risk of being stolen or replayed; a short assertion validity time window mitigates this risk. Assertion validity time windows SHALL NOT be used to limit the session at the RP. See Sec. 4.7 for more information.

Assertion Requests

When the federation transaction is initiated by the RP, the RP’s request for an assertion SHALL contain:

  1. An identifier for the RP
  2. A cryptographic nonce to be returned in the assertion

The RP’s request SHOULD additionally contain:

  1. The set of identity attributes requested by the RP and their purpose of use at the RP; this is a subset of what is allowed by the trust agreement
  2. The requirements for the authentication event at the IdP

When federation transactions are initiated by the IdP (at FAL1), these requirements do not apply. Federation transactions are always initiated by the RP at FAL2 or higher.

Assertion Presentation

In most federation protocols, the RP and the IdP communicate with each other in two ways, each of which can be used to pass an assertion from the IdP to the RP:

There are trade-offs with each model, but both require the proper validation of the assertion. Assertions MAY also be proxied to facilitate federation between IdPs and RPs using different presentation methods, as discussed in detail in Sec. 3.3.3.

Back-Channel Presentation

In the back-channel presentation model shown in Fig. 11, the subscriber is given an assertion reference to present to the RP, generally through the front channel. The assertion reference itself contains no information about the subscriber and SHALL be resistant to tampering and fabrication by an attacker. The RP presents the assertion reference to the IdP to fetch the assertion. Methods for achieving this vary based on the federation protocol in use. In the authorization code flow and some forms of the hybrid flow of [OIDC], the assertion (i.e., the ID Token) is presented in the back channel in exchange for the assertion reference (i.e., the authorization code). In the artifact binding profile of [SAML-Bindings], the SAML assertion is presented in the back channel.

Fig. 11. Back-channel presentation

Diagram of the back-channel presentation model for communicating assertions to the RP.

As shown in Fig. 11, the back-channel presentation model consists of three steps:

  1. The IdP sends an assertion reference to the subscriber through the front channel.
  2. The subscriber sends the assertion reference to the RP through the front channel.
  3. The RP presents the assertion reference and its RP credentials to the IdP through the back channel. The IdP validates the credentials and returns the assertion.

The assertion reference:

  1. SHALL be limited to use by a single RP
  2. SHALL be single-use
  3. SHALL be time-limited and SHOULD have a validity time window of no more than five minutes
  4. SHALL be presented along with authentication of the RP to the IdP
  5. SHALL NOT be predictable or guessable by an attacker

In this model, the RP directly requests the assertion from the IdP to minimize the chances of interception and manipulation by a third party, including the subscriber. More network transactions are required in the back-channel method than a front-channel method, but the information is limited to only those parties that need it. Since an RP only expects to get an assertion directly from the IdP as a result of its request, the attack surface is reduced. Consequently, it is more difficult to inject assertions directly into the RP, and this presentation method is recommended for FAL2 and above. Since the IdP and RP are already directly connected, the back-channel presentation method facilitates the use of identity APIs, as described in Sec. 3.12.3.

It is technically possible but unlikely for an assertion reference (which is single-audience by definition) to result in a multi-audience assertion. For this reason, back-channel presentation is practically limited to use with single-audience assertions.

Conveyance of the assertion reference from the IdP to the subscriber and from the subscriber to the RP SHALL be made over an authenticated protected channel. Conveyance of the assertion reference from the RP to the IdP and vice versa SHALL be made over an authenticated protected channel.

The RP SHALL protect itself against the injection of manufactured or captured assertion references by using cross-site scripting (XSS) and cross-site request forgery (CSRF) protection, rejecting assertion references outside of the correct stage of a federation transaction, or other accepted techniques discussed in Sec. 3.11.1. When assertion references are presented to the IdP, the IdP SHALL verify that the RP presenting the assertion reference is the same RP that made the assertion request that resulted in the assertion reference. Examples for this are discussed in Sec. 9.12, including authorization code flow of [OIDC] with additional security profiles, such as [FAPI] and [iGov].

In a federation proxy (see Sec. 3.3.3), the upstream IdP audience restricts the assertion reference and assertion to the proxy, and the proxy restricts any newly created assertion references or assertions to the downstream RP.

Front-Channel Presentation

In the front-channel presentation model shown in Fig. 12, the IdP creates an assertion and sends it to the RP by means of a third party, such as the subscriber’s user agent. In the implicit flow and some forms of the hybrid flow of [OIDC], the assertion (i.e., the ID Token) is presented in the front channel. In the SAML Web SSO profile defined in [SAML-WebSSO], the SAML assertion is presented in the front channel.

Fig. 12. Front-channel presentation

Diagram of the front-channel presentation model for communicating assertions to the RP.

Front-channel presentation methods expose the assertion to parties other than the IdP and RP, which increases the risk of leaking the personal information included in the assertion. Additionally, there is an increased attack surface for the assertion to be captured and replayed by an attacker. As a consequence, front-channel presentation is not recommended when other mechanisms are available.

The RP SHALL use the assertion identifier to ensure that a given assertion is presented at most once during the assertion’s validity time window.

The RP SHALL protect itself against the injection of manufactured or captured assertions by using XSS and CSRF protection, rejecting assertions outside of the correct stage of a federation transaction, or other accepted techniques discussed in Sec. 3.11.1.

Conveyance of the assertion from the IdP to the subscriber and from the subscriber to the RP SHALL be made over an authenticated protected channel.

With general-purpose IdPs, it is common for front-channel communications to be accomplished using HTTP redirects, where the contents of the assertion are made available as part of an HTTP request URL. Due to the nature of the HTTP ecosystem, these request URLs are sometimes available in unexpected places, such as access logs, web proxies, and browser histories. These artifacts tend to live on long past the federation transaction and are available in other contexts, which increases the attack surface for reading the assertion. As a consequence, an IdP that uses HTTP redirects for the front-channel presentation of assertions SHALL encrypt all personal information in the assertion, as discussed in Sec. 3.13.3. Other front-channel presentation mechanisms that do not share these characteristics (e.g., HTTP form-post binding, application-specific URLs) SHOULD encrypt all personal information in the assertion.