Repository navigation
OpenID for Verifiable Credential Issuance #17616
Replies: 14 comments 38 replies
|
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). |
|
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. |
|
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 IssuerThis 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 Scenario-2: Keycloak with External Credential IssuerIn 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
|
|
I think authorized_gran 8000 t_anonymous_access_supported should be pre-authorized_grant_anonymous_access_supported |
|
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) |
|
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 S 8000 erver. 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 FlowsequenceDiagram
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 FlowsequenceDiagram
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)
|
Detailed Schema: Keycloak as a Verifiable Credential IssuerDealing 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
|
|
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 ( 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. |
|
As far as I know, keycloak has not yet support OAuth 2.0 Rich Authorization Requests (RAR). In the past, there was an activity for supporting RAR, but it stopped. Discussion: Epic Issue: To say more exactly, these discussion and issues were for realizing dynamic scope, which might lead to realizing RAR. |
|
@tnorimat Thanks for the feedback So, returning to VCI & Keycloak. What's the approach?
PS: Keep in mind that the two options, scope vs authorization details (RAR), are no longer equivalent, as of draft 13 of VCI. |
|
@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. |
|
@tnorimat Indeed supporting scopes is good starting point. Actually, KC can be used as it is to implement VCI with the following constraints:
To my understanding, the only thing missing is the ability to obtain |
|
Hello, We are now working on Support Authorization Code Flow for VC Issuance , We would like to break this issue into two sub-issues:
In the first PR, we would like to issue VC in pre-determined Credential Type, not considering a value of scope parameter. In the second PR, we plan to bind a scope value with
What do you think about these procedures for issuing a VC? I would be happy if you have comment on them. |
|
Dear @tnorimat For the 2nd process:
Overall the 2nd process perhaps could be generalized (as an implementation) as it is almost identical when using
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 |
|
@babisRoutis [1] Authz code 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 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. |
|
@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? |
|
@babisRoutis As for |
Dear @fabrii I am not a KC maintainer, so perhaps I am not the right person to provide you an answer. |
|
Hi @babisRoutis, thank you for your response. I am interested in the possibility of using the Authorization Code flow with Keycloak and an external issuer. At this time, we do not need the pre-authorized code grant. |
Perhaps you can take a look here. |
|
Thank you! I was looking for that kind of confirmation. |
I think the big picture is the following:
So, this 2nd OAUTH2 (or OIDC) server doesn't have to know anything about OpenId4VCI. From the perspective of the 2nd OAUTH2 server KC acts like a OAUTH2 client. As soon as KC receives an access_token/id_token issued by the 2nd server, it considers the user as authenticated and resumes the initial flow, to issue a code. Bottom line, I believe that the 2nd server doesn't have to "speak" OpenId4VCI PS: Of course there are some details that I skipped (how KC populates the user's model, but I think this is a well documented feature). |
|
First of all, thank you all contributors. 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, Am I right about that? |
|
Hi, |
|
Hi @wistefan , thank you for your answer. And your example helped me to understand a lot!! |
|
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 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. Maybe I better create new issue for this? |
|
Hi all, Now I am working on "scope" parameter support on OID4VCI, which originally came up for discussion in the thread like following:
At first, let me make something clear about use case of "scope" parameter.
Please let me know something missing here. |
|
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
In both cases the same |
|
There's something I'm not reading clearly, or maybe it is clear and I missed it. What functionality are we talking about in this discussion?
The OID4VCI specification separates the two components. I think Keycloak may be a good candidate for either, but the two functionalities should still be clearly decoupled. |
|
To my understanding, contributors focus on the 2nd case (KC acting both as an Auth. Server & Cred. Issuer). KC can be used as an AuthServer of an external VCI Issuer Service, yet with several restrictions. To my understanding:
|
|
Hi, I have checked the implementation so far and there is something that makes me wondering why? The current development state is using an OAuth2 Client configuration as base for a verifiable-credential representation ( Wouldn't it feel much more naturally to do this with the scope configuration system that keycloak does already have? I am pretty sure that the attributes from RAR requests can also be mapped onto this system Am I misunderstanding something? EDIT: |
|
@vanhoanHoang thanks for raising these questions. Here's my take on your points: Why OAuth2 Client Configuration?The current choice to leverage OAuth2 Client configuration for VCs in Keycloak is primarily based on: Existing Infrastructure: By using clients to handle VC configuration, we can reuse existing concepts like clients, scopes, and protocol mappers. This reduces development effort and leverages well known patterns. Authorization Code Flow Adaptation: The OID4VCI specification aligns closely with OAuth2's authorization code flow. By adapting this flow, we get a well-understood mechanism for authentication, authorization, and token exchange – all of them crucial for VC issuance. DID Association: Using an OAuth2 Client allows us to neatly associate a DID (Decentralized Identifier) with the client ID. This DID then becomes the issuer's identifier in the VC. Community Familiarity: The configuration workflow for OAuth2 clients and associated mappers is well-established and understood by the Keycloak community. This makes it easier for users to adopt and manage VCs. Why Not Custom Scopes and Mappers?While custom scopes and mappers seem intuitive, there are a few considerations: Dynamic Scopes Limitations: Keycloak's dynamic scopes feature, while promising, is still under development and may not be fully mature enough for complex VC use cases. Mapper Complexity: VC mappers would likely be more complex than standard attribute mappers, potentially involving cryptographic operations and specific data transformations. Specification Alignment: Sticking closer to the OID4VCI specification (which is based on OAuth2 concepts) helps ensure interoperability with other VC implementations. Addressing Your Concern on Admin UIYou're absolutely right that the lack of VC configuration in the Admin UI is a limitation. This is something the Keycloak team is likely to address in future releases. |
|
Sorry to raise so many questions but I would like to get onto the same page as you are and there are so many blurry things: OAuth2 Client ConfigurationExisting Infrastructure and Authorization Code Flow Adaptation: DID Association: Community Familiarity: Custom Scopes and MappersDynamic Scopes Limitations: Mapper Complexity: My approach would have been to use normal |
|
Hi, Existing Infrastructure and Authorization Code Flow Adaptation: DID Association: Community Familiarity: |
|
Hi With regards to DID of the issuer. In general it is expected that the wallet, as part of issuance process and after receiving a VC will somehow get the pub key of the issuer to verify the signature of the VC. Some examples:
In W3C VC DM In mso_mdc etc So in general, the way the issuer advertises its signing pub key depends on the format and even for a single format there could be several options, that affect also the issued credential. DID is merely such an option for SD-JWT-VC and W3C VC DM. |
|
First of all I want to mention that I understand that you have a huge lead on this topic and that I have probably still CredentialsEndpoint: A short "as is" descriptionThis is a short overview of how the CredentialsEndpoint is currently implemented: Authentication is done as normally with the AuthorizationCodeGrant and a normal Openid Connect (OAuth2) Client. A Verifiable Credential can be requested from the CredentialsEndpoint by referencing a VerifiableCredential like this: {
"format": "jwt_vc",
"credential_identifier": "MyVerifiableCredentialType"
}Now we iterate over all existing clients filtering those having the OpenId4VCI protocol-type and having the appropriate Afterward we are retrieving the credential. To do this we are extracting all OpenId4VCI clients from the database I have troubles understanding why the Use-case discussionNow let us discuss the use-cases that need to be handled on the CredentialsEndpoint Creating Verifiable CredentialsVerifiableCredentials are a JSON based data-structure that need to be created from a holders (users) data. We {
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "http://university.example/credentials/3732",
"type": ["VerifiableCredential", "ExampleDegreeCredential"],
"issuer": "https://university.example/issuers/14",
"validFrom": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "ExampleBachelorDegree",
"name": "Bachelor of Science and Arts"
}
}
}Such a credential is filled with static-data from the realms configuration and some configured A CredentialRequest for the above example might look like this: {
"format": "jwt_vc",
"credential_identifier": "ExampleDegreeCredential"
}TODOs when done with OAuth2 Client
TODOs when done with ClientScope
=> in both cases the
Signing a Verifiable CredentialThe signature is applied to the VerifiableCredential as you are already doing it. The format is used to get a Verifying a signatureThe signature holds a @babisRoutis I am not sure why the keycloak must support all of these cases. Isn't it enough to just tell that the Usage of DIDsA DID can be used in several places. It can reference natural or legal persons, objects, data-structures etc.
|
|
What is an endpoint address for checking the
Thanks |
Dear @sberyozkin I am afraid this is not so simple. There are specifications that define the well known locations and the expected contents of the response.
|
|
Thanks @babisRoutis, right, but it is a case of the identity provider being an instance of the credential issuer, and the Also, IMHO, conceptually, access to the I'm only trying to clarify why I thought it might work in principle, I realize it may not be supported. Thanks again |
|
According to OpenId4VCI in context are
The OIDC IdP metadata are not relevant. Also, keep in mind that according to OpenId4VCI Credential Issuer is conceptually a Protected Resource and not extension of an Authorization Server. The fact that it can be implemented by an Authorization Server (like in the Keycloak case) is a detail. On the other hand, the UserInfo is an endpoint part of OIDC (If I am not mistaken). In any case, Authorization Servers may extend their metadata, but this has a relative value because what is important is what the Clients are expecting to find within. |
That was exactly my point, it is a protected resource, exactly as a user info endpoint, in both cases, the info is relevant to a currently logged in user.
Well, exactly, if I start from the metadata of the authorization server, I'd like to see
Right, in this specific case it is not abstract specification situation but a concrete fact of Keycloak being an instance of Credential Issuer. But again, like I implied, I accept it may not be implemented, and do not intend to distract this group from the actual VC issuance work. Thanks |
|
@babisRoutis I'm sorry, I think you are right it is not worth going into mixing both types of metadata together, I'm good with the current approach, it can be reviewed anytime in the future should users show interest, thanks for your help 👍 |
|
Hello everyone, does Keycloak OpenID for VC support or plans to support an authorization code flow with Credential Offers as in the spec, or is it only a pre-authorized code at the moment ? |
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
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
All reactions