New well known for issuing?

[David W Chadwick]

/.well-known/openid-configuration

is used when talking to an Open ID Provider (IdP)

and /.well-known/oauth-authorization-server

is used when talking to a standard oath authz server.

The former is an enhancement of the latter.

Should the OIDC4VCI spec define a new well known endpoint for verifiable credential issuing, such as

/.well-known/vc-issuer-configuration

??

If not, why not?

[Thomas Bellebaum]

I disagree that the former is an enhancement of the latter (quite to the contrary, remember that the latter was published later), but that’s beside the point.

I assume that most implementations working with VCs and this draft will have implemented OIDC or at least OAuth, which it is based on, so communicating any server information in the already specified documents may leverage synergies with extensions to the aforementioned protocols (OIDC Discovery or RFC 8414).
As it stands, in theory one could combine a credential request with some form of authentication needed anyway by the client application. It becomes unclear how to do this should the authorization_endpoint in the OIDCD Server Metadata differ from a similar claim in the vc-issuer-configuration document. Even if we require that the endpoints must match, the client still needs to retrieve two documents instead of one.

One benefit a new endpoint would have (in my opinion) would be to remove the reliance on both OIDC Discovery and RFC 8414. However, I struggle to see the benefit in defining a metadata document to avoid relying on a specification defining a metadata document.

Another potential problem of not using a new endpoint would be that it is unclear for an issuer which of those endpoints should be served. However:

• RFC 8414 covers this for the case where the issuer identifier has no path component by explicitly stating that AS may want to serve this document for openid-configuration

  • Most issuers will (need to) offer their services with permission from the hostmaster for their domain, so asking them to forward /.well-known/openid-configuration/my/path to /my/path/.well-known/openid-configuration should not be a problem either (Hit me with use cases disproving this :) )

• Most client implementations I have seen already query both endpoints to see if one matches, since RFC 8414 tried to depricate the path from OIDC Discovery, but legacy…

So by this analysis RFC 8414 would be sufficient, and OIDC Discovery would work out of the box most of the time

[Vladimir Dzhuvinov]

I have a question for David, what do you see as potential pros for having this VCI well-known endpoint?

The /.well-known/oauth-authorization-server was intended to specify metadata for generic OAuth 2.o servers that don’t have OIDC capabilities and hence don’t list supported ID token algorithms (in OIDC Discovery the id_token_signing_alg_values_supported field is REQUIRED, meaning a pure OAuth 2.o server cannot use an /.well-known/openid-configuration for its metadata without breaking its schema).

‌

[David W Chadwick]

The OIDC4VCI spec defines a new grant_types_supported - urn:ietf:params:oauth:grant-type:pre-authorized_code which neither an OP nor a pure OAuth2 server will support. In addition it defines a new endpoint: credential_endpoint which neither an OP nor OAuth2 server will support. Finally it specifies a complex credentials_supported metadata parameter as well. So if the metadata is different for an OIDC4VCI server, then I thought that perhaps a new well known should be defined for it as well.

[Thomas Bellebaum]

Actually, I have been thinking about using the pre-authorized code flow with pure OAuth2 and I think it is of independent interest. Potential Use Cases:

• An Email Provider offers a button to “Connect your own MUA”
• A website offers access to a protected API (offering, say, a calendar) to be imported into your devices local (calendar) application
• In general, transferring access to an account from a browser to a mobile application in “Do you want to view this site in our app?”-Messages

credential_endpoint is a different story, as it inherently deals with credentials, but I can see extensions further connecting it to OAuth2, say by allowing it to be used with new and existing grant types in potentially new flows.

My argument here is that we should be reasonably sure that the current RFC 8414 additions will be exclusive to OpenID4VCI for some time to come, so that a new metadata endpoint continues to be more than a simple alias to existing endpoints.

[Joseph Heenan]

The OIDC4VCI spec defines a new grant_types_supported - urn:ietf:params:oauth:grant-type:pre-authorized_code which neither an OP nor a pure OAuth2 server will support.

This isn’t really unique to OIDC4VCI though, e.g. https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#rfc.section.4 defines it’s own grant type and a new endpoint too.

The discovery document / server metadata is really a single point where you can discover all the servers oauth related mechanisms. The OIDC specific version of the document only exists for historical reasons (as Thomas says, OIDC discovery predates OAuth server metadata), and is technically essentially deprecated as per https://www.rfc-editor.org/rfc/rfc8414.html#section-5

I don’t see strong reasons to add a new OIDC4VCI specific discovery endpoint.

[David W Chadwick]

@ Thomas. I would think that the credentials_supported metadata is quite likely to be specific to OIDC4VCI for the forseeable future. I dont know if this on its own is sufficient to warrant a new endpoint or not. I defer to experts who have worked with OAuth2 for a long time to determine this.

[Torsten Lodderstedt]

How would a credential client, e.g. a wallet, process the issuer URL of a credential issuer in order to access its metadata?

1. It could try to append “/.well-known/openid-configuration”, but not all credential issuers will be OpenID Connect OPs.
2. It could append “/.well-known/oauth-authorization-server” and hope to find the “credential_endpoint” and credential related metadata.
3. It could append “something new” and determine whether there is a VCI specific configuration file.

I don’t think (1) is a good idea, I’m not sure (3) is needed (however I’m a bit leaning towards it).

[gffletch]

I’m fine with “openid-credential-issuer” for the .well-known metadata file.

[gffletch]

I also agree with Joseph’s comment that the credential issue should have it’s own unique issuer value that is separate from the OpenID Provider issuer value.

[Joseph Heenan]

I’m still not convinced a new endpoint is necessary.

Adding a new endpoint potentially makes it easier for people to have a single ‘iss’ value that is used for credential issuance and openid/general oauth2, which as per George’s comment I’m not convinced is a good idea. (If we didn’t define a new metadata filename, the natural conclusion of “I need to specify a different authorization endpoint” is “I need to configure a distinct issuer value”, e.g. adding a path ‘issuance’ to it so it becomes https://example.com/issuance/ and hence there is then an openid-configuration file that is specific to credential issuance.)

The fact that the new endpoint will, I think, use https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#authorization-server-metadata for it’s registry gives further scope for confusion (because there’s all kinds of values in that registry that are potentially relevant, jwks_uri, token_endpoint and grant_types_supported). The new vc-only values will potentially be legal to use in openid-configuration, unless there’s explicitly text when defining each value saying it’s only valid in openid-credential-issuer.

Additionally as discussed during the call, if there’s a new metadata filename used, we’d need to be clear that (as per Mike Jones comments) it uses the openid discovery style of mapping the path in the issuer value onto the well known url (i.e. https://example.com/foo → https://example.com/foo/.well-known/openid-credential-issuer, not https://example.com/.well-known/openid-credential-issuer/foo). [ https://datatracker.ietf.org/doc/html/rfc8414#section-5 is clear that the former method is only used for openid-configuration, which is why we need to be explicit.]

‌

‌

[Kristina Yasuda]

In microsoft’s implementation, we are using existing Authorization Server with a new Resource Server (Credential Issuer) - cannot define a new authorization endpoint and cannot modify existing AS metadata file. two metadata files is the only way forward for us, unless we copy all metadata of the existing AS into a new RS metadata file.

Could start by seeing how metadata of a second file will look like to see if we can prevent confusion you are worried about, Joseph (which is a fair point)? can try put some proposals…

[Thomas Bellebaum]

RS metadata file

Maybe this is an important detail.

In your implementation, the whole issuing service is just a resource server. Then it probably should not advertise any internals (like endpoint configuration) of a completely different (authorization) server. There are some AS deployments out there (including some of ours) which rely on being able to switch out endpoints and communicate this fact via their RFC 8414 metadata. They certainly do not want to notify every RS which might want to re-advertise this data.

I see two potential ways forward for microsoft and others:

1. Keep the document as an AS specific metadata document, advertising AS internals. This will either require modifying the AS or deploying a wrapper around the current metadata document (we have done this before in other scenarios). Note that if the issuer of AS and RS are the same, this will affect the same server regardless of whether or not the existing metadata file is used, so I would still argue in favor of using the existing endpoints for the reasons mentioned above.
2. Make the document RS specific. It should then not advertise any AS specific endpoints and capabilities at all, but instead reference the issuer identifier of the AS (Maybe even its metadata document so a client knows which one of oauth-authorization-server and openid-configuration to use).

‌

[David W Chadwick]

We also use two metadata files and the only property our RS metadata file contains about the AS service is the name of the AS service. All the remaining properties are RS specific, so there can be no confusion between RS and AS parameters. This is described in issue #1632

[David W Chadwick]

@Kristina We cannot completely define the contents of the RS-only metadata file until we resolve the PRs about the type and schema parameters. Once we have done this, we can produce a complete RS-only metadata file.

To my mind the slighly more complex task is defining a single metadata file for the combined RS/AS metadata, due to the potential confusion as to which service a particular parameter refers to e.g. the jwks_uri

[Joseph Heenan]

@Kristina to check if I understand you correctly, Microsoft is using / wants to use the same ‘iss’ value in both normal OIDC flows and credential issuance? and you need to use a different authorization_endpoint value for the 2 different cases?

Could start by seeing how metadata of a second file will look like to see if we can prevent confusion you are worried about, Joseph (which is a fair point)? can try put some proposals…

I think that’s a reasonable thing to do, yes.

I think an interesting question arises over registration_endpoint - if a client is using both OIDC and credential issuance, should it try and register twice, once to the endpoint in /.well-known/openid-configuration and again to the endpoint in .well-known/openid-credential-issuer? Or should it only do that if the dynamic registration endpoints in the two files are different?

[Daniel McGrogan]

+1 to the clarifying posts from Kristina & David. It seems the info emerging as folks try to implement the spec, is that the issuing endpoints need their own data descriptors. If it is done as part of a resolvable URL solution it seems reasonable that the Resource Domain Metadata should reference the Auth Domain Metadata vs wrapping or replacing it. I think Thomas’ point illustrates one key reason why the Resource Metadata should referencing & track the Auth/OP metadata. This should allow minimal impact (ideally no) impact on the existing OAuth metadata + enables a nice decoupling for implementers.

I would go so far as to say that ideally the OIDC4VCI should have no implementation impact on Auth servers and should be completely bounded to the client and resource domains, not saying that’s possible but it would be a good directional bias.

[Daniel McGrogan]

To Davids original question 

I would suggest that the metadata endpoint should be more generalised to encompass OAuth protected resources which may be a VC issuers.

`…/.well-known/vc-issuer-configuration` -> `…/.well-known/resource-configuration`

Having the resources defining the resource type information (in this case Verifiable Credentials) & trust relationships (pointing to the Auth/OP domain they trust) seems generally powerful.

It should be written in a way that it could be back fit to ‘standard’ OAuth protected resources. Having explicit Resource Metadata formalises the previously implicit metadata, which is hand rolled by developers working with the resource endpoints. 

Also the declaration of trust relationships allows for some interesting use cases e.g. a resource declares that it trusts multiple AS/OPs, thus allowing for dynamic federated Auth models.

                                                                             |- AS (oauth2.microsoft.com)
                                                                             |- IDP (identity.microsoft.com)
Resource (mycompany.com/resources/.well-known/resource-configuration) -trust>|- AS (authserv.workday.com)
                                                                             |- IDP (someidp.google.com)
                                                                             |- IDP (id.mycompany.com)

‌

[Torsten Lodderstedt]

I’m trying to wrap my head around this issue. What problems are we trying to solve?

What I read:

David: OIDC4VCI spec defines a new grant_types and additional metadata and a new endpoint

As already stated, the new grant type and additional metadata can be listed in the OAuth Server Metadata as well as the OpenID configuration.

The new credential issuance endpoint is a bit different as it is not related to OAuth but is one endpoint of the credential issuance API. So we could define a new metadata file for it.

Questions:

(1) Would that be covering the credential issuance API metadata only? or

(2) Would that cover issuance metadata and the respective OAuth configuration?

re (1) The way I read Daniel’s comments, he would lean towards (1) and let this file refer to the authorization server the respective API/RS relies on (1:1), potentially even to the authorization servers (1:n).

1:1: that could make the metadata lifecycle management a bit easier since different components have their distinct metadata. Not sure whether this justifies a new metadata file.
1:n: I would like to understand what the use case for such an architecture would be. I have built systems with a 1:n relationship between RS and AS and I know what complexity that causes (for example: using introspection in such a setup requires hybrid tokens in order to be able to determine the AS to send the introspection call to). So I’m pretty reluctant to go that way. I think the credential issuance endpoint is tied to one specific AS/OP in the same way a userinfo endpoint is tied to a certain AS - it’s just a different way to assert user claims.

(2) would basically be the approach taken by OpenID Connect where the additional metadata is added to a metadata file accessible under a different path. And in the deployments I’m aware of, if there is an /.well-known/oauth-authorization-server there is also a /.well-known/openid-configuration with exactly the same content. That’s possible since whatever new metadata we come up with, as long as we don’t override the definition of metadata in OAuth or OpenID space, we cannot violate the OAuth Server metadata or OpenID Discovery specs.

I raised the question: How would a credential client, e.g. a wallet, process the issuer URL of a credential issuer in order to access its metadata? We need to define the logic for it.

Georg: is in favour of the credential issuer having a different from the OpenID provider issuer value

I would say deployments can already use today different issuer values for OpenID Connect and Credential Issuance. But they don’t have to. I think we should allow this flexibility. To add some color: In our ecosystem I would strongly prefer to use the same issuer value for both functions. Why? Because I would like to allow RPs to decide whether they want to obtain user claims as ID Tokens, or Userinfo response, or Verifiable Credentials on top of the same infrastructure (IDP chooser, trust management, …) and even within the same transaction (issue a payment/OAuth, get some claims/OpenID, get a credential for offline use).

I think the questions Joseph raised regarding client ids falls into that realm as well. A client id is defined in the context of a certain issuer. So if the same issuer is used for OAuth, OpenID and Credential Issuance, a certain client id must also be valid for those three contexts. If there are different issuer values for OpenID and Credential issuance, a certain client id is defined in one of those contexts, the validity in the other is undefined.

My personal bottomline of the problems we want to solve is:

1. some of the new metadata feel like they don’t belong into a OAuth server metadata or OpenID configuration file.
2. pure credential issuance clients need to understand how to resolve the issuer metadata
3. it must be clear where what client id can be used.

I think we should define a new credential issuer metadata path, e.g. /.well-known/openid-credential-issuer. The file on that location must comply to the credential issuer metadata definition given in the VCI spec. That would solve 1 and 2. For (3), we could add some text explicitly stating that the issuer value determines whether a certain client id can be used across functions. My assumption is that a lot of deployments will add /.well-known/openid-credential-issuer as the third path for the same content.

[David W Chadwick]

There is one additional point that should be taken into account: the signing keys of the issuer and the AS (token endpoint). They will be different. If you have one combined account with just one jwks_uri that contains two public keys, then which is which? If you have two metadata files that each contain the metadata that is relevant to themselves (i.e. the RS and AS) then it is obvious which public key belongs to whom

[David W Chadwick]

Answers to Torsten’s questions

(1) If there is just one metadata file then it will cover both the AS and RS, if there are two metadata files each will cover their own metadata only.

(2) Again it depends upon whether you have one file or two. I would favor a 1:1 relationship of the two servers, (but then I am not an expert in OAuth2)

Note that this particular issue only concerns the new well known name for the RS metadata file. Whether there are 1 or 2 metadata files is the subject of a separate issue #1632

‌

[Kristina Yasuda]

@Joseph Heenan

@Kristina to check if I understand you correctly, Microsoft is using / wants to use the same ‘iss’ value in both normal OIDC flows and credential issuance? and you need to use a different authorization_endpoint value for the 2 different cases?

what is the iss in the credential issuance? DID signing an issued credential? iss value will definitely be different.

if a client is using both OIDC and credential issuance, should it try and register twice, once to the endpoint in /.well-known/openid-configuration and again to the endpoint in .well-known/openid-credential-issuer? Or should it only do that if the dynamic registration endpoints in the two files are different?

Interesting. my assumption has been that AS used for OIDC/OAuth will be re-used for Credential Issuer, so one registration at the AS will be sufficient. but if there are deployments where there is an additional AS specific to the credential issuance, registreting via the issuer might make more sense.

[Kristina Yasuda]

PR #372 merged