This section is normative.
A federation protocol connects the IdP and RP together with a series of messages. These messages include assertions, which are passed between the IdP and RP to represent the federated authentication event, and the contents of identity APIs, which convey additional attribute information about the subscriber. This section enumerates requirements for these common components but is not intended to provide sufficient detail for any specific federation protocol.
As stated in Sec. 3, the trust agreement establishes the set of attributes that the IdP provides to the RP and the purposes the RP has for those attributes. Some attributes are required to be available at the IdP. Some of the available attributes are mandatory to be provided to all RPs. Other attributes are available at the IdP but accessible only to RPs if stipulated in the trust agreement. Other attributes are optional for the IdP to have available, and likewise optional to be provided to RPs if stipulated in the trust agreement. The identity attributes found in the PIV identity account that are made available from a PIV IdP are not limited to those available from the PIV authentication certificate.
The following set of identity attributes SHALL be provided by a PIV IdP to every RP within any trust agreement for PIV federation:
\clearpage
A PIV IdP SHALL have the following core identity attributes available as part of the account and SHALL make those attributes available to an RP if stipulated in the trust agreement:
A PIV IdP SHOULD have the following core identity attributes available as part of the account and SHOULD make those attributes available to an RP if stipulated in the trust agreement:
Except as otherwise stated in Sec. 6.2, the IdP SHOULD disclose attributes through an identity API rather than through the assertion itself. For example, in OpenID Connect, while it is possible to include subscriber attributes such as name and email within the ID token (the assertion), it is preferable to make such attributes available from the UserInfo Endpoint (an identity API). When attributes are available for a given account through more than one method at an IdP, the attribute values SHALL match.
A PIV IdP SHOULD allow for selective disclosure of attributes to different RPs, as determined by the authorized party listed in the trust agreement.
The last updated attribute is provided as a hint to the RP about the current freshness of the attributes available from the IdP to allow the RP to decide when to refresh any attributes kept in the RP subscriber account.
The timestamp is calculated by the IdP, and its source varies depending on implementation. For example, for the home agency IdP, this would include any modifications made to the PIV identity account that affect the attributes that the IdP makes available. For other PIV IdPs, the last updated timestamp indicates when the IdP’s copies of any attributes were last updated from their source. In all cases, the RP can track this timestamp as a value stored in the RP subscriber account. If the timestamp provided by the IdP is newer than that in the RP subscriber account, the RP can update its cached attributes from the IdP using any available mechanisms.
If multiple timestamps are available for different attributes, the latest timestamp SHALL be used.
As specified in [SP800-63C], the successful validation of a federated assertion is required to begin an authenticated session at the RP. The assertion contains a combination of attributes about the subscriber as well as attributes about the authentication event that the assertion represents.
At a minimum, the assertion in PIV federation SHALL contain the following attributes of the PIV identity account:
As an assertion is a short-lived message from the IdP to the RP, the assertion itself SHOULD only contain the minimum attributes required for its processing. To preserve privacy and minimize the information sent with each request, the assertion SHOULD NOT contain non-required or stable attributes from the PIV identity account (e.g., email address, display name). Additional attributes SHOULD be made available to the RP through a standard identity API.
At a minimum, the assertion in PIV federation SHALL contain the following attributes of the authentication event:
\clearpage
For FAL3 assertions in PIV federation, the assertion SHALL contain either:
The mapping of these required attributes to specific fields within a given federation protocol is out of scope for this specification.
The assertion created by a PIV IdP includes a federated identifier for the PIV identity account, as defined in [SP800-63C]. The federated identifier consists of the logical combination of both a subject identifier for the PIV identity account assigned by the IdP and a global issuer identifier for the IdP.
The subject identifier SHALL be unique to the PIV identity account at the IdP such that no identifier is the same for any two PIV identity accounts at an IdP.
The subject identifier SHALL be stable for a PIV identity account over time and SHALL survive common life cycle events, such as reissuance of a PIV Card or changes to attributes (e.g., email addresses, usernames).
The subject identifier MAY be generated by the IdP in a pairwise fashion for a specific RP, as discussed in [SP800-63C]. If such a pairwise identifier is used, it SHALL be used consistently with a given RP and SHALL NOT be used for multiple RPs except as allowed by [SP800-63C].
The subject identifier SHALL NOT include any personally identifiable or private information, such as a username, an certificate identifiers (see Sec 6.2.3), email addresses, the UUIDs of the PIV Card or cardholder, or an internal record number. These identifiers MAY be used as input to a one-way cryptographic function used to calculate a subject identifier. However, care should be taken to ensure that the resulting identifier is stable.
The issuer identifier SHALL be globally unique for the IdP. This identifier is usually the URL of the IdP, but it can also be a unique key identifier or other globally unique value that can be verified by the RP as part of the assertion.
The RP SHALL use this federated identifier to uniquely associate the PIV identity account with the RP subscriber account, as defined in [SP800-63C]. The RP SHALL NOT use other attributes alone for this purpose, including email addresses, certificate subject names, or PIV cardholder UUIDs.
The assertion MAY contain indicators for the authorizations and access rights that the subscriber has at the RP, such as a set of roles within an organization. The RP SHALL trust these only as subject to the details of the trust agreements between the IdP and RP.
As the point of enforcement, the RP MAY override these authorizations by additionally restricting access as necessary.
The PIV authentication certificate is issued to PIV identity cardholders as part of the PIV Card and can uniquely identify a PIV identity account, as described in [FIPS201]. Within PIV federation, the PIV authentication certificate is not used for primary authentication to the RP, but it can still be referred to from the federation protocol in some important ways. For example, when used as an IdP-managed bound authenticator, the PIV authentication certificate is verified by both the PIV IdP and subsequently by the RP. For this to work, the assertion needs to communicate the identity of the certificate and its included keys in a reliable manner. The exact method of referring to the PIV authentication certificate is out of scope for this document and subject to profiling of the federation technology in use, but some common options include:
Each of these options has different tradeoffs and considerations, and an interoperable technical profile of this specification SHOULD define which of these are supported.
The IdP SHALL publish its configuration information in a standard machine-readable format and location that are appropriate to the federation protocol in use. The information in the configuration document SHALL be sufficient to allow for the automated configuration of an RP contacting the IdP even when the RP is statically registered.
IdPs operating at FAL2 and below SHOULD allow RPs to register dynamically, as described in [SP800-63C]. Assertions issued to dynamically registered RPs SHALL contain pairwise subject identifiers.
The IdP SHALL support back-channel assertion presentation, if possible within the federation protocol. All back-channel presentation methods SHALL require authentication of the RP.
At all FALs, RPs SHOULD use back-channel presentation to fetch the assertion directly from the IdP, where available.
If front-channel presentation is used and the assertion contains PII, the contents of the assertion SHALL be encrypted using a key specific to the RP, as required in [SP800-63C].
The IdP SHALL make identity attributes for the subscriber available through a standard identity API, if possible within the federation protocol in use. The identity API SHALL require protected access from the RP.
The IdP SHALL allow limited disclosure of attributes through this API, such that federation agreements that connect the IdP and RP (including runtime decisions by an authorized party) can dictate which attributes are disclosed to the RP for a given request.
The RP SHALL use the account update timestamp to manage its cache of attribute information in the RP subscriber account, particularly when using a just-in-time provisioning model. That is, if the account update timestamp in the assertion is later than the last cache update value, the RP knows that it should fetch updated information from the identity API. If the timestamp is not later than the cache time, the RP can determine that an additional call to the identity API would be redundant.
The IdP MAY provide a provisioning API to the RP, subject to a trust agreement. When a provisioning API is used, the trust agreement SHALL include a justification for the intended use of all attributes provided to the RP by the provisioning API.
An identity proxy acting in a PIV federation context SHALL disclose the IdPs used as sources of attributes to the downstream RP. For example, if an assertion contains attributes for a PIV identity account from IdP A and IdP B, the proxy will list both IdPs as sources within the assertion. Note that the proxy, in its role as an IdP to downstream RPs, is still the issuer of the assertion and will identify itself as such.
See Sec. 3.3 for more information about the trust agreement requirements of identity proxies.