4.6 Authentication and Attribute Disclosure

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

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

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

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.

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.

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.

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:

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.