Open frankhinek opened 1 month ago
cc: @tomdaffurn
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?
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.
This is a great point that is ambiguous right right now.
I suggest we follow RFC8414 on this, and do not diverge path handling any further. I created #32 for this
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:
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:
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:
https://{yourDomain}/.well-known/openid-configuration
https://{yourDomain}/.well-known/oauth-authorization-server
https://{yourDomain}/.well-known/openid-credential-issuer
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:
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
OAuth 2.0 Authorization Server Discovery
OID4VCI Credential Issuer Discovery
Unresolved questions
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.