RFC KCC-0001: Document OIDC and KCC Issuance HTTP endpoints

[frankhinek]

Warning

STILL IN DRAFT

• Start Date: 2024-05-21
• RFC PR: Not yet submitted
• Issue: known-customer-credential#0001

Summary

There are several HTTP endpoints that are hosted by PFIs / credential issuers that facilitate interactions between wallets, issuers, and verifiers during the credential application flow defined in this repo.

To ensure interoperability and adherence to industry standards, we should document the HTTP endpoints used for the following:

• OpenID Connect (OIDC)
• Self-Issued OpenID Provider v2 (SIOPv2)
• OpenID for Verifiable Credential Issuance (OID4VCI)
• OpenID for Verifiable Presentations (OID4VP)

Motivation

In the Known Customer Credential (KCC) flow, a Participating Financial Institution (PFI) performs Know Your Customer (KYC) procedures and issues a KCC as a Verifiable Credential (VC) to a retail customer's Decentralized Identifier (DID). This KCC serves as proof of an actively compliant KYC verification, enabling the PFI to provide financial services to that DID in accordance with regulatory requirements.

The KCC issuance process involves several interactions between the wallet (controlled by the retail customer), the PFI's credential issuer, and a potential Identity Verification (IDV) vendor. These interactions rely on standard HTTP endpoints for exchanging information, such as:

• The wallet discovering the credential issuer's supported credentials, technical capabilities, and endpoint URLs through the Credential Issuer Metadata.
• The wallet initiating the credential issuance flow through a SIOPv2 (Self-Issued OpenID Provider v2) interaction to authenticate the applicant's DID.
• The wallet receiving the credential offer and pre-authorized code from the credential issuer.
• The wallet presenting Verifiable Credentials as input for identity verification.
• The wallet exchanging the pre-authorized code for an access token to authorize the credential issuance.
• The wallet receiving the issued KCC from the credential issuer's Credential Endpoint.
• The verifier (PFI) retrieving the issuer's public keys to verify the KCC presented by the wallet.

Documenting and standardizing the HTTP endpoints used for these interactions is crucial for interoperability. It ensures wallets and verifiers can dynamically discover and interface with any compliant credential issuer without needing proprietary integration.
Using endpoints defined by existing standards like OpenID for Verifiable Credential Issuance (OID4VCI), OpenID for Verifiable Presentations (OID4VP), and OAuth 2.0 promotes consistency and enables leveraging existing open source SDKs and libraries.

The expected outcome is a more seamless end-to-end experience for retail customers obtaining and using KCCs from their PFIs, while minimizing bespoke development required by wallet and verifier implementers to support each PFI.

Defining these endpoints allows TBD to provide clear guidance to PFIs acting as credential issuers on how to make their services interoperable with any standards-compliant wallet and verifier.

Detailed design

Based on published specifications, reference material, and the approach taken by established identity providers, the following HTTP endpoints are proposed by this RFC:

Name	Path
OpenID Connect Discovery	https://{yourDomain}/.well-known/openid-configuration
OAuth 2.0 Authorization Server Discovery	https://{yourDomain}/.well-known/oauth-authorization-server
OID4VCI Credential Issuer Discovery	https://{yourDomain}/.well-known/openid-credential-issuer

---

Warning

TODO Add the other endpoints in to the table

---

Drawbacks

While standardizing the HTTP endpoints for interactions between wallets, credential issuers, and verifiers in the Known Customer Credential (KCC) flow offers many benefits, there are some potential drawbacks to consider:

1. Compatibility issues: As the standards evolve, there may be compatibility issues between different versions of the specifications. This could lead to interoperability problems if wallets, credential issuers, and verifiers are not all updated to support the latest versions consistently.
2. Limited flexibility: By adhering to these HTTP endpoints, PFIs acting as credential issuers may have less flexibility in customizing the KCC issuance flow to their specific requirements. However, this limitation is necessary to ensure interoperability across the ecosystem.

Despite these potential drawbacks, the benefits of interoperability, reduced integration complexity for wallets and verifiers, and the ability to leverage existing open source SDKs and libraries make a compelling case for standardizing the HTTP endpoints in the KCC flow. The drawbacks can be mitigated through careful design, active participation in the standards development process, and a commitment to maintaining compatibility as the ecosystem evolves.

Rationale and alternatives

The proposed design of standardizing HTTP endpoints for interactions between wallets, credential issuers, and verifiers in the Known Customer Credential (KCC) flow is considered the best approach in the space of possible designs for the following reasons:

• Interoperability: By leveraging existing standards like OIDC, SIOPv2, OID4VCI, and OID4VP, the proposed design ensures interoperability between wallets, credential issuers, and verifiers. This allows for a more seamless integration and reduces the need for proprietary solutions.

• Reusability: Standardizing the endpoints enables the use of existing open source SDKs, libraries, and tools that support these standards. This reduces the development effort required by PFIs, wallet providers, and verifiers to implement the KCC flow.

• Extensibility: The chosen standards provide a solid foundation for future extensibility. As the standards evolve and new features are added, the KCC flow can benefit from these improvements without requiring significant changes to the core design.

• Alignment with industry trends: The selected standards are widely adopted and supported by major identity providers and platforms. By aligning with these trends, the KCC flow positions itself for better adoption and compatibility within the broader identity ecosystem.

Alternative designs considered:

• Proprietary API: One alternative approach would be to define a proprietary API for interactions between wallets, credential issuers, and verifiers. While this would provide more flexibility and control over the API design, it would hinder interoperability and require custom integrations for each PFI, wallet provider, and verifier. This approach was not chosen due to the increased complexity and reduced interoperability.

• Minimal standardization: Another alternative would be to standardize only a subset of the interactions, such as the credential issuance endpoint, while leaving other aspects of the flow up to proprietary implementations. While this approach would offer some level of interoperability, it would still require custom integrations for non-standardized parts of the flow and could lead to inconsistencies across implementations.

Prior art

These are the endpoints are commonly used by popular identity provider platforms:

OpenID Connect Discovery

• Specification: OpenID Connect Discovery 1.0
• Purpose: Provides the OpenID Provider's configuration information, including the location of other endpoints and supported features.

Provider	Path
Apaleo	https://identity.apaleo.com/.well-known/openid-configuration
Apple	https://appleid.apple.com/.well-known/openid-configuration
Auth0	https://auth0.auth0.com/.well-known/openid-configuration
Google	https://accounts.google.com/.well-known/openid-configuration
Okta	https://login.block.xyz/.well-known/openid-configuration
PingIdentity	https://signon.pingidentity.com/davinci/.well-known/openid-configuration
Microsoft	https://login.windows.net/common/.well-known/openid-configuration
SalesForce	https://login.salesforce.com/.well-known/openid-configuration

OAuth 2.0 Authorization Server Discovery

• Specification: RFC 8414
• Purpose: Enables OAuth 2.0 clients to obtain the information needed to interact with an OAuth 2.0 authorization server, including its endpoint locations and authorization server capabilities.

Provider	Path
Mastodon	https://mastodon.social/.well-known/oauth-authorization-server
Okta	https://login.block.xyz/.well-known/oauth-authorization-server
PingIdentity	https://sso.{hostedPingIdentity}.com/.well-known/oauth-authorization-server

OID4VCI Credential Issuer Discovery

• Specification: OpenID for Verifiable Credential Issuance
• Purpose: Provides information on the Credential Issuer's technical capabilities, supported Credentials, and (internationalized) display information.

---

Warning

TODO Add sections for the other endpoints that should be included in this RFC.

---

Unresolved questions

• How do we describe when it is and is not acceptable to prepend or append a path to the specified HTTP endpoints?
• Are there any other endpoints related to the KCC flow that should be specified?
• Should any of these endpoints be moved to an RFC in the tbDEX protocol specification repo?

Future possibilities

In the future, TBD could develop and host a website where implementers could enter their DID and click a button to validate that their endpoint conforms to the KCC specification and relevant standards.

[mistermoe]

cc: @tomdaffurn

[KendallWeihe]

The relevant specification's don't explicitly standardize to HTTP, but it's worth noting all of the examples are littered with HTTP. I view the proposal here as absolutely vital to the success of the project, because it maps the standards onto established technologies of which much of the web currently operates on. I'm in favor.

Can we add a more concrete directive of the form of the deliverable here? Would it be to an OpenAPI spec doc?

[tomdaffurn]

I'm not sure what is being proposed here. We have .well-known/oauth-authorization-server and .well-known/openid-credential-issuer required in this spec already. The mapping from Issuer Identifier to well-known URL is defined by OID4VCI and RFC8414. This spec is joining those (and a couple other) specs together, while delegating the details. What specific change does this ask for?

I don't think we should be using .well-known/openid-configuration. It serves the same purpose as .well-known/oauth-authorization-server. RFC8414 suggests that either or both can be used, but prefers the newer, more general .well-known/oauth-authorization-server:

Some OAuth applications will choose to use the well-known URI suffix
"openid-configuration". As described in Section 5, despite the
identifier "/.well-known/openid-configuration", appearing to be
OpenID specific, its usage in this specification is actually
referring to a general OAuth 2.0 feature that is not specific to
OpenID Connect.
...
Going forward, OAuth authorization server metadata locations should
use the transformation defined in this specification.

Path prepending/appending

This is a great point that is ambiguous right right now.

• OIDC Discovery allow paths: https://openid.net/specs/openid-connect-discovery-1_0.html#rfc.section.4.1
• RFC8414 (OAuth 2.0 metadata) allows paths, but DIFFERENTLY: https://datatracker.ietf.org/doc/html/rfc8414#section-3

I suggest we follow RFC8414 on this, and do not diverge path handling any further. I created #32 for this