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

Subscriber-Controlled Wallets

This section is normative.

A subscriber-controlled wallet is an IdP for which the CSP makes the attributes of the subscriber account available through the issuance of attribute bundles, as described in Sec. 5.1. The subscriber activates the wallet using an activation factor or authenticator, as described in Sec. 5.4. Usually, the subscriber-controlled wallet runs on a device that is controlled by the subscriber and represents only a single subscriber. However, wallets can also be hosted on remote systems in a deployment pattern that is sometimes known as a cloud wallet.

Issuing Attribute Bundles to the Subscriber-Controlled Wallet

When the CSP issues attribute bundles to the subscriber-controlled wallet, the process SHALL include the following steps:

  1. The subscriber proves their identity to the CSP’s issuance functionality using the CSP’s identity proofing process or by authenticating to the subscriber account.
  2. The subscriber activates the wallet using an activation factor, which might entail authenticating to a hosted wallet service.
  3. The wallet generates or chooses a signing key and corresponding verification key. The wallet proves possession of its signing key to the CSP.
  4. The CSP creates one or more attribute bundles that include subscriber attributes and the wallet’s verification key (or a reference to that key).
  5. The wallet stores the attribute bundle for later presentation to RPs.

The subscriber-controlled wallet MAY generate and use a different signing key and verification key for each issuance request with the CSP.

The CSP SHALL create a unique attribute bundle for each requesting wallet and SHOULD create a unique attribute bundle for each request from an individual wallet.

Many subscriber-controlled wallets can carry attribute bundles from multiple CSPs simultaneously. The simultaneous presentation of attribute bundles from multiple CSPs in a single assertion is possible with some technologies. When this occurs, the assertion of multiple attribute bundles SHALL conform to the assertion requirements in this guideline.

\clearpage

Invalidating Attribute Bundles for the Subscriber-Controlled Wallet

The CSP SHALL provide a means of invalidating attribute bundles that are issued to a subscriber-controlled wallet. This process is used when:

To accomplish this, the CSP SHOULD issue attribute bundles with a limited time validity window. The CSP SHOULD provide a means to independently verify the status of attribute bundles (i.e., whether a specific bundle has been revoked by the CSP). If such a service is offered, the service SHALL be deployed in a privacy-preserving way such that the CSP is not alerted to the use of a specific attribute bundle at a specific RP.

Federation Transaction

A federation transaction with a subscriber-controlled wallet establishes the subscriber’s device as an IdP for the subscriber account and creates an authenticated session for the subscriber at the RP. The process is shown in Fig. 13.

Fig. 13. Federation with a subscriber-controlled wallet

Overview diagram of federated authentication process using a subscriber-controlled wallet.

A federation transaction with a subscriber-controlled wallet takes place over several steps:

  1. The CSP identity-proofs the subscriber and creates a subscriber account.
  2. The CSP issues attribute bundles from the subscriber account to the wallet in a process that includes the subscriber verifying an authenticator in their subscriber account or completing an abbreviated proofing process (e.g., using a biometric captured at proofing to verify identity).
  3. The wallet receives a signed attribute bundle from the CSP that allows the wallet to act as an IdP.
  4. The RP requests a federated authentication transaction from the wallet, usually through subscriber action.
  5. The subscriber activates the wallet through an activation factor. In the case of a hosted wallet, this is an authentication to the wallet service.
  6. The wallet creates an assertion based on the RP request, subscriber actions, and attribute bundles that are available to the wallet.
  7. The wallet presents the assertion to the RP.
  8. The RP validates the assertion and creates an authenticated session for the subscriber. This process includes validating the attribute bundle from the CSP.

Trust Agreements

Due to the architectures and design of subscriber-controlled wallets, the trust agreements that support federated transactions are less direct than with general-purpose IdPs. To maintain privacy outcomes and prevent the tracking of user transactions, CSPs and RPs do not typically have direct communication with each other. The following requirements apply to all subscriber-controlled wallet scenarios:

  1. The release of subscriber attributes SHALL be managed using a runtime decision managed by the wallet, as described in Sec. 4.6.1.3.
  2. The authorized party SHALL be the subscriber.
  3. The following terms SHALL be disclosed to the subscriber during the runtime decision:
    • The set of subscriber attributes, derived attributes, and attribute bundles that the RP will request (a subset of the attributes made available)
    • The purpose of each attribute requested by the RP

The xALs required by the RP MAY also be disclosed to the subscriber at runtime.

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

CSPs and RPs

Trust between the CSP and RP in subscriber-controlled wallet scenarios will not typically be bidirectional. In the general case, the RP trusts the CSP as the source of attribute bundles that are presented by subscriber-controlled wallets during a federation transaction, while the CSP is not expected to have direct knowledge of the RP. This trust relationship between the RP and CSP MAY be facilitated by a federation authority (see Sec. 3.5.2) that defines overarching trust agreements between members of an ecosystem representing RPs, CSPs, and subscriber-controlled wallets. Such trust agreements SHALL contain:

Trust MAY also be established unilaterally by RP evaluation of publicly available information about CSPs and their processes for issuing attribute bundles. To facilitate this, CSPs SHALL publish the following information to a trusted location for RPs to evaluate:

This information MAY be made available by a trusted third party, such as a federation authority that assesses and evaluates CSP attribute bundle issuance and makes CSP features available through a discovery service.

Trust between RPs and CSPs MAY be accomplished in either a pre-established (see Sec. 4.3.1) or subscriber-driven fashion (see Sec. 4.3.2). For example, an RP could be statically configured to accept attribute bundles from only a specific set of CSPs for its purposes, or the RP could alternatively accept attribute bundles from any CSP by prompting the subscriber for consent at runtime. This trust relationship could also be made more explicit by the RP being provided a means of verifying CSP-approved subscriber-controlled wallet identifiers beyond the verification of the attribute bundle, such as a discovery service provided through a federation authority.

CSPs and Subscriber-Controlled Wallets

The trust relationship between the CSP and the subscriber-controlled wallets will always be direct in nature. As such, there SHALL be a trust agreement between the CSP and the subscriber-controlled wallets into which they issue attribute bundles. At a minimum, this trust agreement SHALL include the following:

RPs and Subscriber-Controlled Wallets

The primary extension of trust in a subscriber-controlled wallet scenario is through the RP’s evaluation of the attribute bundles and their issuance process by the CSP. However, wallets play an important role in the degree to which RPs trust the information being presented to them in assertions that contain attribute bundles signed by the CSP.

Information about the features and capabilities of a subscriber-controlled wallet can help inform the degree to which RPs trust a given transaction. This information can demonstrate confidence that the subscriber presenting an attribute bundle is the individual represented by that attribute bundle. For example, information about how the wallet locally authenticates the subscriber, protects verification keys, and enforces trust agreement requirements indicated by the CSP or RP all support improved RP federation and access decisions. As such, subscriber-controlled wallets SHALL disclose to RPs:

This information MAY be provided at runtime or through discovery mechanisms for wallet metadata. For more on this topic, see Sec. 5.8.

FAL3 for Subscriber-Controlled Wallets

Since assertions from a subscriber-controlled wallet always contain a reference to one of the wallet’s verification keys inside the signed attribute bundle from the CSP, subscriber-controlled wallets that run on a subscriber-controlled device are capable of issuing holder-of-key assertions if all of the requirements for holder-of-key assertions are met (see Sec. 3.15). These assertions MAY be used to reach FAL3 if all requirements for FAL3 are met (see Sec. 2.4).

The verification keys of a subscriber-controlled wallet on a hosted service do not meet the requirements for holder-of-key assertions on their own since the subscriber is not in control of the key material as they would be on a subscriber-controlled device. To reach FAL3, federation transactions with a subscriber-controlled wallet on a hosted service SHALL use either a holder-of-key assertion (see Sec. 3.15) or a bound authenticator (see Sec. 3.16). All requirements for FAL3 in Sec. 2.4 SHALL be met. For example, a holder-of-key assertion from a subscriber-controlled wallet on a hosted service could include the verification key of an authenticator separate from the wallet verification key. The subscriber would present this additional authenticator to the RP along with the wallet’s assertion.

Wallet Activation

The subscriber-controlled wallet SHALL require the presentation of an activation factor from the subscriber for the following actions that result in the creation of a signed artifact from the wallet’s signing keys:

The subscriber-controlled wallet SHOULD require the presentation of an activation factor before any other operations that result in the creation of a signed artifact from the wallet’s signing keys. For example, using the wallet as an authenticator at AAL2 or above requires the presentation of an activation factor as per Sec. 3.2.10 of [SP800-63B].

The wallet MAY request the reissuance of previously issued attribute bundles from the same CSP without requiring subscriber involvement.

For subscriber-controlled wallets that run on a device that the subscriber controls, the submission of the activation factor SHALL be a separate operation from the unlocking of the host device (e.g., smartphone), although the same activation factor used to unlock the host device MAY be used in the activation operation. Organizations MAY relax this requirement for subscriber-controlled wallets managed by or on behalf of the CSP (e.g., via mobile device management) and that are constrained to have short, organization-determined inactivity timeouts and device activation factors that meet the above requirements. Additional discussion of activation factors for authenticators is found in Sec. 3.2.10 of [SP800-63B].

For subscriber-controlled wallets that are hosted on a remote service, activation of the wallet is performed using an authenticator that is registered to the wallet service. This authenticator MAY be separate from those bound to the subscriber account at the CSP.

Key Storage

Keys used for signing assertions SHALL NOT be synced or shared across devices, and wallet implementations SHOULD use non-exportable key storage, as discussed in Sec. 3.6.2.

If the wallet’s signing key is used as a holder-of-key authenticator for FAL3, the key SHALL be stored in non-exportable key storage, as discussed in Sec. 3.6.2.

Discovery and Registration

To perform a federation transaction with a subscriber-controlled wallet, the RP SHALL first determine the attribute bundle verification key of the CSP through a secure process as stated by the trust agreement. In some systems, this is accomplished by retrieving the CSP’s attribute bundle verification keys from a URL that is known to be controlled by the CSP. In other systems, the RP is configured manually with the verification keys of the CSP before being deployed. In systems governed by multi-lateral trust agreements, this process can be facilitated by a third-party discovery and registration service, such as one provided by a federation authority.

The signed attribute bundle includes the CSP that issued the bundle and one or more verification keys that are associated with the subscriber-controlled wallet. Since the RP trusts the CSP’s process of issuing attribute bundles to subscriber-controlled wallets, the RP can trust the presentation of those bundles that are made using proof of one of the subscriber-controlled wallet’s signing keys.

In many cases, the process of the RP registering with the subscriber-controlled wallet is expected to be a dynamic process in which the RP exchanges its keys and metadata with the IdP during the federation transaction. The nature of a subscriber-controlled wallet makes it difficult for any specific RP to pre-register with an instance of the wallet, but this can be facilitated through the use of a trusted third party that is stipulated in the trust agreement.

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, consider an ecosystem has a centralized service for managing discovery and registration. When an RP joins the ecosystem, it registers itself with the trusted service, downloads the CSP’s verification keys, and receives an identifier to use with wallets. When the CSP issues attribute bundles to the subscriber-controlled wallet, the subscriber-controlled wallet is informed where it can find the list of valid RP identifiers within the ecosystem. When the RP connects to the wallet, the wallet can verify the RP’s identifier without the RP having to register itself directly with the wallet. Likewise, the RP can trust the wallet’s verification keys by verifying the CSP’s signature over the wallet’s verification keys or identifier.

Authentication and Attribute Disclosure

The decision of whether a federation transaction proceeds and, therefore, an assertion is issued and attributes are released to the RP SHALL be determined by the subscriber acting in the role of the authorized party. The decision MAY be augmented by the use of allowlists and blocklists to allow the wallet to help the subscriber make a decision based on configured policies and trust agreements. The subscriber-controlled wallet MAY remember the subscriber’s decision to allow for future actions at the same RP without separate authorization from the subscriber. The use of a stored authorization decision does not supersede the requirement for wallet activation, as discussed in Sec. 5.4.

The subscriber-controlled wallet MAY provide a mechanism to remember a disclosure decision by the authorized party (i.e., the subscriber) to apply to future requests from the same RP. If such a mechanism is provided, the subscriber-controlled wallet 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.

The subscriber-controlled wallet SHOULD provide a means to selectively disclose a subset of the attributes in the attribute bundle from the CSP.

The CSP SHALL provide secure and effective means of redress of subscriber complaints or problems (e.g., subscriber identifies an inaccurate attribute value, the need to invalidate attribute bundles that were previously issued to a subscriber-controlled wallet). See Sec. 3.5.3 for additional requirements and considerations for redress mechanisms.

Assertion Requests

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

  1. An identifier for the RP
  2. A cryptographic nonce
  3. The set of identity attributes, derived attributes, and attribute bundles requested by the RP and their purpose of use at the RP

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 Contents

Assertions from a subscriber-controlled wallet SHALL contain:

  1. A signed attribute bundle from the CSP.
  2. Audience identifier: An identifier for the party that is intended to consume the assertion (i.e., the RP).
  3. Issuance time: A timestamp that indicates when the wallet 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. For example, this can be a unique nonce generated by the wallet and included in the assertion.
  6. Signature: A digital signature that uses asymmetric cryptography and covers the entire assertion.

Assertions MAY contain:

  1. Subject identifier: An identifier for the party to which the assertion applies (i.e., the subscriber)
  2. Issuer identifier: An identifier for the issuer of the assertion (i.e., the subscriber-controlled wallet)

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 of the subscriber account being represented in the assertion, an indication of the issuance processes, or an indication that no IAL is asserted
  2. The nature of the activation method used to activate the wallet.
  3. The wallet’s intended FAL of the federation process that is represented by the assertion

If a subscriber-controlled wallet is hosted as a remote service, the AAL of the subscriber’s current session at the hosted wallet service SHALL be provided through information contained in the assertion contents or the applicable trust agreement. In this case, 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 this 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:

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

The signed attribute bundle from the CSP SHALL contain:

  1. Keys: A verification key or key identifier for the key used by the subscriber-controlled wallet to sign assertions
  2. Issuer identifier: An identifier for the issuer of the attribute bundle (i.e., the CSP)
  3. Issuance time: A timestamp that indicates when the CSP issued the attribute bundle
  4. IAL: Indicator of the IAL of the subscriber account being represented in the attribute bundle or an indication that no IAL is asserted
  5. Signature: A digital signature that uses asymmetric cryptography and covers the entire attribute bundle
  6. Attribute values and derived attribute values: Information about the subscriber

If the RP subscriber account does not use an ephemeral provisioning process (see Sec. 4.6.5) or an account resolution process (see Sec. 3.8.2), the subscriber SHALL be identified in the assertion using a federated identifier (see Sec. 3.4). The issuer identifier SHALL be of the CSP that issued the signed attribute bundle, and the subject identifier SHALL be contained in the signed attribute bundle and processed in the namespace of the CSP that issued the attribute bundle.

The signed attribute bundle from the CSP SHOULD contain a validity time window, which is defined as a period of time outside of which the attribute bundle 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 attribute bundle in addition to the issuance timestamp.

The signed attribute bundle from the CSP MAY contain additional information about the subscriber account, such as the set of controls used to determine the IAL.

Additional identity attributes and derived attribute values MAY be included in the attribute bundle. These attributes SHALL be made available to the RP using a selective disclosure method if such a method is made available by the underlying attribute bundle. In selective disclosure, a subset of attributes is revealed rather than the entire set. This may be driven by a minimum set required to complete a transaction as defined by the RP or through selection by the subscriber at runtime.

Identity attributes that are in the assertion but outside of a signed attribute bundle SHALL be considered self-asserted. The RP MAY validate these additional attributes using its own validation process.

Assertion Presentation

Assertions SHALL be presented to the RP through an authenticated protected channel.

The presentation SHALL include the cryptographic nonce from the RP’s request, if present (this is required at FAL2 and above). The RP SHALL verify the nonce in accordance with the federation protocol.

If the presentation mechanism passes the assertion through a component other than the wallet or RP, personal information in the assertion SHOULD be encrypted by the wallet using the RP’s encryption key, as discussed in Sec. 3.13.3.

To enhance privacy, the presentation mechanism SHOULD provide features to enable unlinkability of the subscriber and their information at different RPs.

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. When possible, subscriber-controlled wallets that run on a subscriber-controlled device SHOULD use platform APIs instead of HTTP redirects when delivering an assertion to the RP.

Assertion Validation

The RP SHALL validate the signature on all signed attribute bundles in the assertion using the verification key from the CSP that issued the signed attribute bundle. The RP SHALL validate the signature of the assertion using the verification key of the subscriber-controlled wallet contained in the signed attribute bundle.

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

  1. Bundle verification: Ensure that the bundle was issued to the wallet that is presenting the assertion to the RP.
  2. Issuer verification: If a specific wallet was requested by the RP, ensure that the assertion was issued by the requested wallet.
  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 is also 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 by validating a transaction specific assertion identifier, such as a wallet-provided nonce.

Additionally, if a mechanism for invalidating attribute bundles is provided by the CSP, the RP SHOULD use this mechanism to determine whether the attribute bundle has been invalidated by the CSP since its issuance, as discussed in Sec. 5.1.1. This validation mechanism is particularly suited for attribute bundles with long or indeterminate lifetimes, since proactive invalidation by the CSP could occur long before expiration of the attribute bundle.

RP Subscriber Accounts

Due to expected architectures and trust agreements for subscriber-controlled wallets, it is likely that RP subscriber accounts will be managed with a just-in-time or ephemeral provisioning model (see Sec. 4.6.3). In each of these cases, the RP creates the RP subscriber account and associates it with the federated identifier (if available) after the successful validation of the assertion from the wallet. A pre-provisioning model could also be used, such as when the RP has an established account linking process (see Sec. 3.8.1) that would allow linking of a wallet-based identity to an existing account using a known unique attribute or set of attributes.

For many RPs that use wallet-based attribute bundles, the RP will use an account resolution process to link the information in the attribute bundle to a set of functionality at the RP, as discussed in Sec. 3.8.2. If the RP subscriber account is not ephemeral and a federated identifier is present, the RP SHOULD associate the federated identifier presented by the subscriber-controlled wallet with the RP subscriber account and use the federated identifier for future federated transactions with the same subscriber. If a federated identifier is not present (e.g., in the case of mDL), the RP will need to request the necessary attributes to resolve the subscriber to the RP subscriber account for each federated transaction. This attribute set SHALL be the minumum necessary to achieve accurate resolution. Linking to multiple federated identifiers SHALL be managed as discussed in Sec. 3.8.1.

The RP SHALL disclose its practices for managing subscriber information as part of the trust agreement. The RP SHALL provide effective means of redress to the subscriber for correcting information in the RP subscriber account. See Sec. 3.5.3 for additional requirements and considerations for redress mechanisms.