OpenID for Verifiable Credential Issuance

[vanhoanHoang]

Hi everyone,

OpenID Verifiable Credential Issuance (OIDC4VC) has been discussed a lot in the Self-Soverin Identity (SSI) especially due to European Commission having released a Framework for eIDASv2. The later tends to chose OIDC4VC as a protocol to issue Verifiable Credential (VC) and to present Verifiable Presentation (VP).

For simplicity, VC is a token generally in JSON-LD format issued by OpenID Provider to the User whereas VP is a token presented by User to Relying Party for authentication and authorizations purposes. A VP can be the result of an aggregation of multiples VCs or simply a subset of attributes of a single VC. OIDC4VP and SIOPv2 have been introduced for the purposes of presenting Verifiable Presentation from USER to Relying Party.

In this context, multiple wroking groups have started discussions about a concrete implementation of these specifications. As the largest open source SSO software, will we start working on this ? @thomasdarimont

Cheers,
Hoan

[muhammad-asn]

Sorry for asking, Is it currently a proposal or idea for Keycloak to have native/built-in integration with SSI/DIDs? Or is there any other 3rd party for bridging the IAM (web2 based) to SSI/DIDs (web3 based).

[davux]

OpenID for Verifiable Credential Issuance (OID4VCI) relies on Rich Authorization Requests (RAR), which Keycloak supports. So I think in the particular case of OID4VCI, Keycloak can already be configured as the Authorization Server if you configure it properly. This is due to the fact that the AS in OID4VCI doesn't need to do anything related to DIDs. So maybe it's just a matter of someone documenting this particular use case.

Supporting OIDC4VP and SIOPv2 however is a different subject however, because it does require specific Self-Sovereign Identity logic. Let's open a separate discussion for those, to not mix things up.

[francis-pouatcha]

Proceeding toward the implementation of the GAIN POC, we will be moving on with following two scenarios, that require minimal modification on Keycloak (KC):

Scenario-1: Keycloak as Credential Issuer

This is a sample interaction in which KC functionality is extended with the the ability to produce VCs for all tokens produced by KC. Including the one produced through token exchange requests (as they present the first mean of selective disclosure so far).

sequenceDiagram
Actor User
participant Wallet
box Keycloak
participant CME as Credential Metadata<br/>Endpoint
participant AME as Authorization Matadata<br/>Endpoint
participant PARE as PAR<br/>Endpoint
participant AZE as Authorization<br/>Endpoint
participant TE as Token<br/>Endpoint
end
User ->> Wallet: Interact with user
%% Only new endpoint required
Wallet ->> CME: Metadata /.well-known/openid-credential-issuer
Note right of Wallet: Only new end point in this scenario
CME -->> Wallet : Credential issuer metadata
Wallet ->> AME: /.well-known/openid-configuration
AME -->> Wallet: Auth server metadata
Wallet ->> Wallet : Construct PAR (evtl. with RAR)
Note right of Wallet: [single|batch],credential=true, all VC|token info
Wallet ->> PARE: Post PAR
PARE-->>Wallet: request_uri
Wallet->>AZE: Authorization Request
AZE ->> AZE: Authorize User
Note right of AZE: evtl. with consent
AZE-->>Wallet: Authorization Response (code)
Wallet->>TE: Token Request (code)
TE-->>Wallet: Token Response (VCs)

In the first implementation, we could start with pre-authorized_grant_anonymous_access_supported=false in the credential metadata, so that we do not have to support pre-auth. As the process is not clear to me yet.

Scenario-2: Keycloak with External Credential Issuer

In this scenario, all what we need is a consumable RAR, that will allow KC to produce a corresponding access token. Access token will be converted into VC by credential issuer.

sequenceDiagram
Actor User
participant Wallet
box Credential Issuer
participant CME as Credential Metadata<br/>Endpoint
participant CE as Credential<br/>Endpoint
end
box Keycloak
participant AME as Authorization Matadata<br/>Endpoint
participant PARE as PAR<br/>Endpoint
participant AZE as Authorization<br/>Endpoint
participant TE as Token<br/>Endpoint
end
User ->> Wallet: Interact with user
%% Only new endpoint required
Wallet ->> CME: Metadata /.well-known/openid-credential-issuer
Note right of Wallet: Only new end point in this scenario
CME -->> Wallet : Credential issuer metadata
Wallet ->> AME: /.well-known/openid-configuration
AME -->> Wallet: Auth server metadata
Wallet ->> Wallet : Construct PAR (evtl. with RAR)
Note right of Wallet: [single|batch],credential=true, all VC|token info
Wallet ->> PARE: Post PAR
PARE-->>Wallet: request_uri
Wallet->>AZE: Authorization Request
AZE ->> AZE: Authorize User
Note right of AZE: evtl. with consent
AZE-->>Wallet: Authorization Response (code)
Wallet->>TE: Token Request (code)
TE-->>Wallet: Access Token, Refresh Token
Wallet->>CE: Credential Issuance Request
CE-->>Wallet: VCs

[coxchrisw]

I think authorized_grant_anonymous_access_supported should be pre-authorized_grant_anonymous_access_supported

[francis-pouatcha]

From the GAIN POC Meeting: In a scenario where authorization server and credential issuer are colocated, the credential-issuer-metadata could also transport auth-server-metadata (.well-known/oauth-authorization-server)

[francis-pouatcha]

As an enrichment of diagrams in here, below are two more diagrams from @coxchrisw with both auth code flow and pre-auth code flow. In these cases all current Keycloak endpoints are inside the participant Authorization Server.

It is also essential to witness the role of an attestation endpoint. This is the component responsible for producing/certifying credentials (attestation tokens) used by Wallets (as OIDC Client) and by Verifiers (if necessary in their role as RP) to access the authorization server.

Scenario-A: Authorisation Code Flow

sequenceDiagram
Actor User
participant Wallet
participant CI as Credential<br/>Issuer
participant ATE as Attestation<br/>Endpoint
participant AS as Authorisation<br/>Server
User->>Wallet: Interact with wallet
Wallet->>CI: Obtain Credential Issuer metadata
CI-->>Wallet: Credential Issuer metadata
Wallet->>ATE: Create Client Attestation
ATE-->>Wallet: Client Attestation
Wallet->>AS: Construct PAR Request
note right of AS: use client attestation<br/>in par request<br/>contains VC to grant
AS -->> Wallet: PAR Response
Wallet ->> AS: Authorisation Request
note right of AS: use PAR response<br/>in Auth request
AS ->> AS: Authenticate User
AS -->> Wallet: Authorisation Response
Wallet ->> AS: Token Request (code)
note right of AS: use client attestation<br>in token request
AS -->> Wallet: Token Response (access_token)
Wallet->> CI:  Credential Request (access_token, proof(s))
CI -->> Wallet: Credential Response (credential(s) OR acceptance_token)

Scenario-B: Pre-Authorisation Code Flow

sequenceDiagram
Actor User
participant Wallet
participant CI as Credential<br/>Issuer
participant ATE as Attestation<br/>Endpoint
participant AS as Authorisation<br/>Server

User->>CI: User provides  information required for the issuance of a certain Credential
CI-->>Wallet: Credential Offer (Pre-Authorized Code)
note left of CI: could be QR or<br/>Deep Link
Wallet->>CI: Obtain Credential Issuer metadata
CI-->>Wallet: Credential Issuer metadata
Wallet->>ATE: Create Client Attestation
ATE-->>Wallet: Client Attestation
Wallet ->> AS: Token Request (code)
note right of AS: use client attestation<br>in token request
AS -->> Wallet: Token Response (access_token)
Wallet->> CI:  Credential Request (access_token, proof(s))
CI -->> Wallet: Credential Response (credential(s) OR acceptance_token)

[francis-pouatcha]

Detailed Schema: Keycloak as a Verifiable Credential Issuer

Dealing with client attestation in this schema. In the GAIN POC, Stage-1 does not required trusting the wallet attestation. Touching affected Keycloak components.

sequenceDiagram
Actor User
participant Wallet
box Keycloak
participant CME as Credential Metadata<br/>Endpoint
participant AME as Authorization Matadata<br/>Endpoint
participant PARE as PAR<br/>Endpoint
participant DCR as DCR<br/>Endpoint
participant AZE as Authorization<br/>Endpoint
participant TE as Token<br/>Endpoint
end
User ->> Wallet: interacts
Wallet ->> CME: (1) Obtains Credential Issuer metadata <br>/.well-known/openid-credential-issuer
Note right of Wallet: 10.2 New endpoint<br/>do we need /issuer? see 10.2.1
CME -->> Wallet : Credential issuer metadata
Note right of Wallet: <br/>credential_issuer:<br/>authorization_server:<br/>credential_endpoint:<br/>batch_credential_endpoint:<br/>
Wallet ->> AME: (1) Obtains Authorization Server metadata <br>/.well-known/openid-configuration
AME -->> Wallet: Auth server metadata
Wallet ->> Wallet: create wallet attestation
Note right of Wallet: Self signed attestation<br/>GAIN PoC stage 1
Wallet ->> DCR: Register Wallet(Wallet Attestation)<br/>Endpoint: auth_server_metadata:registration_endpoint<br/>GAIN: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-attestation-based-client-auth-00
Note left of DCR: Configured KC to<br/>consume self signed<br/>attestations
DCR -->> Wallet: Wallet Client Credentials
Wallet ->> Wallet : Construct RAR
Note over Wallet : RAR type openid_credential<br/>[single|batch]<br/>credential=true<br/>all VC|token info
Wallet ->> PARE: Post PAR<br/>attestation-based-client-auth
Note left of PARE: Configured KC to<br/>consume self signed<br/>attestations
PARE-->>Wallet: request_uri
Wallet->>AZE: Authorization Request
AZE ->> AZE: Authorize User
Note right of AZE: evtl. with consent
AZE-->>Wallet: Authorization Response (code)
Wallet->>TE: Token Request (code)
Note left of TE: Configured KC to<br/>consume self signed<br/>attestations
TE-->>Wallet: Token Response (VCs)
Note right of Wallet: Token might be a<br/>verifiable credential

[babisRoutis]

It is not clear to me, whether Keycloak currently supports RAR.

In the latest editor's draft(draft 13) of the OpenID4VCI, authors made significant changes with regards to the use of RAR in order to address a known shortcoming of the protocol.

In particular, when an authorization request contains one or more authorization details (RAR), then the token endpoint must return in a successful response the authorization details that were placed to authorization request and in addition there could be (inside the authorization details) additional attributes (credential_identifiers).

The later was added by the authors in order to allow a wallet to place an issuance request not only using a credential type (for instance mso_mdoc mDL) but also specifying an additional identifier. That way, a wallet can request for instance the birth certificate of X person as opposed to requested just for a birth certificate.

Returning to Keycloak, it should be able to receive with the authorization request, authorization details, ask the user to authorize the request and somehow inform the token endpoint that there could be zero or more credential identifiers (depending on the nature of the credential issued and the issuance business logic).

This is an essential addition to VCI, that probably will be included to the Implementer's draft, and I think it would be important to track Keycloak's support to RAR.
a) RAR support in authorization endpoint (and PAR endpoint)
b) RAR support including the additional credential_identifiers in the Token endpoint

[tnorimat]

As far as I know, keycloak has not yet support OAuth 2.0 Rich Authorization Requests (RAR).
https://datatracker.ietf.org/doc/html/rfc9396

In the past, there was an activity for supporting RAR, but it stopped.

Discussion:
#8532

Epic Issue:
#9225

To say more exactly, these discussion and issues were for realizing dynamic scope, which might lead to realizing RAR.

[babisRoutis]

@tnorimat Thanks for the feedback

So, returning to VCI & Keycloak. What's the approach?

• Is keycloak going to focus on scopes (at least initially)? or
• RAR is considered a prerequisite for VCI?

PS: Keep in mind that the two options, scope vs authorization details (RAR), are no longer equivalent, as of draft 13 of VCI.

[tnorimat]

@babisRoutis Hello, IMO, it might be better to use scope parameter. RAR is useful for other use-cases, however it might take a lot of time to support it. To support OID4VCI swiftly, using scope parameter might be a good first step.

[babisRoutis]

@tnorimat Indeed supporting scopes is good starting point.

Actually, KC can be used as it is to implement VCI with the following constraints:

• external credential issuer service
• authorize code grant
• scope instead of RAR
• no need for token endpoint to return c_nonce & c_nonce_expires_in. VCI does mention that token endpoint may return those values, but this is merely an optimization because the Credential issuer must return them in any case. Thus token endpoint can be left as is for authorization code grant.

To my understanding, the only thing missing is the ability to obtain issuer_state in authorization & PAR endpoints and perhaps attestation-based client authentication.

[tnorimat]

Hello,

We are now working on Support Authorization Code Flow for VC Issuance ,

We would like to break this issue into two sub-issues:

1. VC issuance in Authz Code flow without considering “scope” parameter
2. VC issuance in Authz Code flow with considering “scope” parameter

In the first PR, we would like to issue VC in pre-determined Credential Type, not considering a value of scope parameter.
We need to consider mapping a value of a scope parameter to a Credential Type, which is not defined by the specification of OID4VCI. In the second PR, we would like to consider it.

In the second PR, we plan to bind a scope value with credential_configuration_id, and issue a VC as follows:

1. A holder requests an issuer (Keycloak) for its credential issuer metadata.
2. This credential issuer metadata includes credential_configurations_supported parameter, which includes credential_configuration_id(s).
3. The holder pick up one of value of credential_configuration_id(s), and put it onto a scope parameter of an authorization request.
4. On receiving the authorization request, the issuer (Keycloak) prepare a verifiable credentials in a format and type which a value of scope parameter (namely, credential_configuration_id indicates).

What do you think about these procedures for issuing a VC? I would be happy if you have comment on them.

[babisRoutis]

Dear @tnorimat

For the 2nd process:

• There should be a precondition that a specific credential_configuration_id defines a scope. In general, this is optional.
• Step 1: This is the wallet initiated issuance, in which wallet knows (out-band) the issuer. This step could be more generic, since there is also the case that wallet/holder has been offered one or more credentials (via a credential offer that uses authorization code)
• Step 2: Personally, I agree. Mind though that authors of VCI think that there is also the case that an issuer doesn't advertise all credential_configuration_id(s), for whatever reason. For context you may look here
• Step 4: I miss the part where holder visits token endpoint. This is important depending whether you are thinking to update the token endpoint response to include c_nonce & c_nonce_expires_in. According to VCI this can be omitted and let the credential endpoint to return those values.

Overall the 2nd process perhaps could be generalized (as an implementation) as it is almost identical when using authorization_details (RAR), instead of scope. For instance a more generic flow could be

1. Wallet has been received either a credential offer or can prepare a credential offer knowing out-band the issuer. The offer may contain one or more credential_configuration_id
2. Wallet verifies the credential offer against issuer advertised metadata.
3. For each offered credential_configuration_id there should be either a scope or (in the absence of a scope) a relevant authorization_details. At the end of this, we should have a list of scopes and/or a list of authorization_details
4. An authorization request is being placed using the scopes & authorization_details from previous step
5. When code is being returned to holder, it visits token endpoint. In case of authorization_details there should be a way to support credential_identifiers (not credential_configuration_id). That's a common business use case which currently can be implemented only using RAR. (please see here)
6. Holder places the relevant issuer requests.

Even if keycloak doesn't provide immediate support to RAR (haven't followed this one), the above flow still holds since it only requires to make scope required for a all credential_configuration_id(s)

[tnorimat]

@babisRoutis
Thank you for your comments.

[1] Authz code flow
The Issuer-initiated flow / The Wallet-initiated flow

At first, I would like to only consider the Issuer-initiated flow. In the future, I would like to consider the Wallet-initiated flow.

[2] credential_configuration_id(s) in a credential issuer metadata
disclosed / not disclosed

At first, I would like to assume that all credential_configuration_id(s) be disclosed in a credential issuer metadata. In the future, I would like to consider which credential_configuration_id(s) are disclosed or not.

[3] c_nonce & c_nonce_expires_in in a response from Token Endpoint

At first, I would like to not support them because these are optional parameter. In the future, I would like to consider these parameters.

[4] RAR

AFAIK, I am not sure whether and when RAR is supported. Therefore, I would like to consider only scope parameter. If RAR is supported in the future, I would like to consider authorization_details parameter.

IMO, It might be good that the complete feature of VC issurance be realized step by step.

If we tried to implement the complete feature of VC issurance to one PR, it would take a lot of time, and its code volume woulb be huge, which makes the review of the PR quite difficult.

Instead of that, I would like to implement mandator features of VC issurance to one PR. After that, I would like to implement optional features one by one.

By doing so, it is expected that the code volume of each PR might be small, which makes the review of the PR relatively easy.

[babisRoutis]

@tnorimat Indeed, this is a sound approach. All assumptions are reasonable.

Will you consider supporting in the above scenario issuer_state at PAR and/or Authorization endpoint?

Also, can this be used with an external credential issuer that is protected by KC?

[tnorimat]

@babisRoutis As for issuer_state, it might be considered when we would consider supporting Crediential Offer in Authz Code Flow.
As for an external credential issuer, I do not consider it yet.

[babisRoutis]

@tnorimat Thank your for your reply.

A final question.

You mentioned earlier that you aim initially to support issuer initiated flow. With authz code flow I would add, given that we can have issuer initiated flows also using pre-authorized code flow.

My question is the following:
In an issuer initiated flow (no matter the grant type) issuer has to either draw a QR code (cross-device) or form a deep link (same device), in order to communicate the credential offer (by value or by reference) to the wallet.

How you intend to implement this ? Which UI will be responsible for this?

[babisRoutis]

I am asking the above question because I think that an Issuer should expose an endpoint - not described in VCI - that would allow another application to request the creation of a credential offer.

This other application could be the one the user visits to begin the issuer-initiated process (I will use the term Issuer UI)

In your initial scenario (authz code flow, no issuer_state) a credential offer is static information. Thus, Issuer UI can draw a credential offer (qr, deep link or redirect) as long as it is aware of available credential_configuration_id(s).

In the general case though, a credential offer is not static.

• in authz code flow may use the issuer_state &
• in pre-authorized flow there is the pre-authorized code.

[tnorimat]

Sorry, I made a mistake. First, I try to suport the Wallet-initiated flow, not the Issuer-initiated flow.

[babisRoutis]

Sorry, I made a mistake. First, I try to suport the Wallet-initiated flow, not the Issuer-initiated flow.

Ok that's clear @tnorimat

From wallet's perspective there is no real difference between a wallet-initiated or handling a credential offer that uses authorization code flow.
I do understand that for KC, wallet-initiated means that there is no need to create or present credential offers, at least for now.

By the way, I am not a big fan of using wallet/issuer-initiated terms 😄

Reason being that wallet-initiated corresponds to authz code flow with no issuer_state. On the other hand, issuer-initiated can be implemented with either authz code or pre-authorized code flow. It seems to me that many tend to forget the former option and think that issuer-initiated implies pre-authorized code.

[bucchi]

First of all, thank you all contributors.
I am a big fan of Keycloak community.
And I really appreciate what you guys have done for OID4VCs support.

There are a couple of things I want to make sure about the implementation.

Here is the first one:

From code merged with PR #27931,
I guess that (in Keycloak Issuer server) client instance is designed to be created for each wallet instances.
(This means unique client id is issued to each end users or each smart devices.)

Am I right about that?
Or is it for each wallet suppliers or wallet applications?

[wistefan]

Hi,
the client id is not intended for the wallets. Its rather intended to be used for the "audience" of the credential, similar as its used by OIDC. E.g. if you want to create an Credential to be used for accessing did:web:my-target.com, you can create a client with that ID and manage the roles to be assigned for users.
Best,
Stefan

[bucchi]

Hi @wistefan ,

thank you for your answer.

And your example helped me to understand a lot!!

[bucchi]

Hi,

Let me make sure one more thing about the implementation of the relation between VC and mapper.

Especially about how to figure out which mapper should be executed for a requested VC
when multiple VCs are configured for one client as attributes and also a group of mappers are configured as protocol mappers of the client.

On the implementation for now, it looks you can not control mappers executed depend on a requested VC.

For each mapper you can set Supported Credential Types.
But this type might not be used properly.

Maybe I better create new issue for this?

[bucchi]

Hi all,

Now I am working on "scope" parameter support on OID4VCI, which originally came up for discussion in the thread like following:

We would like to break this issue into two sub-issues:

VC issuance in Authz Code flow without considering “scope” parameter
VC issuance in Authz Code flow with considering “scope” parameter

At first, let me make something clear about use case of "scope" parameter.

1. It is for the wallet which support only authorization code flow and which does not support authorization_details.

2. It can be used to request a certain credential.

   In this case, you can identify one credential from requested scope value with Issuer metadata.

      <sample issuer metadata(Credential_configutation_supported)>
                             - credential : AAA
                                   scope : <AAA>
                                   format : jwt_vc_json
 
                            - credential : BBB
                                  scope : BBB
                                  format : jwt_vc_json
 
                            - credential : CCC
                                  scope : <CCC>
                                  fromat : ldp_vc           

3. It also can be used to request a set of credentials with single scope.

   In this case, you can get some credentials from one scope value with Issuer metadata
   => From my understanding, it may be for Batch Credential Endpoint since Credential Endpoint can not send back multiple credentials with one response.

      <sample issuer metadata(Credential_configutation_supported)>
                             - credential : AAA
                                   scope : <AAA>
                                   format : jwt_vc_json
 
                            - credential : BBB
                                  scope : BBB
                                  format : jwt_vc_json
 
                            - credential : CCC
                                  scope : <AAA>
                                  fromat : ldp_vc           

Please let me know something missing here.
Any comments or ideas are welcome.

[babisRoutis]

Hi @bucchi

Maybe it could be just me, yet it is not clear what exactly are you asking 😄

Anyhow, for the 3d case where a scope corresponds to more than one credentials (or more precisely ,to multiple credential_configuration_id(s)), it is in the wallet discretion to

• either call multiple times the credential endpoint or, alternatively, to
• place a single call to the batch endpoint (provided that issuer supports this optional endpoint).

In both cases the same access_token can be used.