-
Notifications
You must be signed in to change notification settings - Fork 144
Blog post on the support of OpenID4VCI #682
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
613b89a to
b9d7bc8
Compare
Closes keycloak#666 Signed-off-by: Ingrid Kamga <[email protected]>
Signed-off-by: Awambeng Rodrick <[email protected]> Signed-off-by: Ingrid Kamga <[email protected]>
b9d7bc8 to
fc93520
Compare
ahus1
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thank you for the blog post. See below for some comments.
At the end (or the beginning), do you want to have a call-to-action how people should provide feedback? Do you want to add a GitHub discussion, or the slack channel of the working group?
Signed-off-by: Awambeng Rodrick <[email protected]>
|
Hi @ahus1, I’ve addressed the comments you left. Could you please take a look when you get a chance? |
Signed-off-by: Alexander Schwartz <[email protected]>
|
@Awambeng - thank you for the changes. This now looks good. Some minor added links here - please merge that PR into your PR, and then it should be good from a technical writer's point of view. Please have someone from the working group review the content. Thanks! |
|
@ahus1 Thank you very much for the review and improvements. We haven’t received any feedback from the SIG members yet. @tnorimat @VinodAnandan @mposolda @thomasdarimont Could you please help review this PR when you have a moment? |
thomasdarimont
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
|
@thomasdarimont @VinodAnandan Thank you for your reviews. Unfortunately, I can’t re-request your reviews, but feel free to take a look as all your comments and suggestions have been addressed. |
|
@IngridPuppet @Awambeng @thomasdarimont Should we consider including the following in the Concrete Use-Cases section? I believe it highlights one of the strongest privacy and security advantages of digital credentials. Selective disclosure for low-trust scenarios - For example, a user can present only the minimum necessary information (such as a photo and confirmation that they are above a certain age) to a bouncer or security guard, without revealing their full identity or personal details. |
@VinodAnandan I might be wrong, but I see this example as more tied to SD-JWT VCs. Instead, I updated the first example in the list to highlight the security aspect you mentioned. Hope that works! @IngridPuppet @thomasdarimont WDYT? |
Yes, definitely. It is well-known that the general public is often reluctant to the feature until selective disclosure is mentioned. |
mposolda
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks @Awambeng and @IngridPuppet for the nice blog and for applying most of my suggestions I've sent earlier by the email.
Added 2 additional comments inline. Could you please double-check?
|
|
||
| - Attribute `vc.format` defines the format of the credential whereas `vc.verifiable_credential_type` specifies the `vct` property's value. | ||
| - All `vc.display` entries are intended to be used by a wallet to display intelligible descriptions. | ||
| - Known bugs mandate configuring the credential signing algorithm via `vc.proof_signing_alg_values_supported`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What exactly are these "Known bugs" ? Are these Keycloak bugs? If yes, then it might be good to rather fix it on Keycloak side or at least create the GH issue on Keycloak side and refer it from here with the link? Last week, I've created keycloak/keycloak#44699 , which is slightly related, but probably different than the issue you have in mind?
Or is it bug in the OID4VCI specification itself or some other party? In that case, it can be maybe good to describe the limitation in the specification somehow as part of this point.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hi Marek. It's not an issue with the OID4VCI specification. We created issue keycloak/keycloak#44621 to address it. A PR is in queue.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@IngridPuppet Thanks for the clarification! So if I understand correctly, that PR keycloak/keycloak#44621 needs to be merged first before this blog is published and then this blog-post can be updated to align with it (including renaming the option and slightly rewriting this sentence to avoid using "Known bugs mandate ..." formulation :-)
Is it correct?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, we are on par. The whole bullet mentioning "Known bugs..." is meant to be removed after ticket keycloak/keycloak#44621 is completed. We hope such updates on the blog post could be done with iterative PRs prior to considering publishing it.
tnorimat
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@IngridPuppet Hello, I added some review comments. Could you check them?
|
@VinodAnandan @mposolda I’ve closed the other PR, and all the changes are now consolidated here as suggested. |
|
@IngridPuppet @Awambeng @VinodAnandan @tnorimat It seems to me that main question is whether we "base" this blog-post based on Keycloak 26.5.0 release or based on the last "nightly" build? So far, it seems to me that it can be better if we "base" this blog-post based on the last Keycloak 26.5.0 release. I see the main disadvantage of the nightly release is, that OID4VCI is still under development. Hence this blog-post will probably quickly become outdated. For example when we publish this blog-post today, but someone will try instructions from this blog-post in 3 weeks from now (with the nightly build from February 1 for example), he will see different behaviour than described in this blog-post and maybe instructions will not work for him at all. So my vote is to make this based on the Keycloak 26.5.0 release, but add paragraph at the bottom of the blog-post, that OID4VCI is still under development and instructions and configuration options from the blog-post may change in the future Keycloak versions. WDYT? If we go this path, I guess some small updates would be needed in the blog-post (AFAIK for example option "Credential Signing Algorithm" mentioned in the blog-post is not yet available in Keycloak 26.5.0 admin console. However it may not be needed to create client-scope with this option configured AFAIK as long as the created ES256 is set as realm active key). WDYT? |
Thanks @mposolda, I agree. Basing the blog post on Keycloak 26.5.0 is safer and avoids issues with fast-changing nightly behavior. Adding a short disclaimer about OID4VCI still being under development makes sense. One concern I have is that for Keycloak 26.5.0 to be fully functional, an additional configuration is required (the Credential Signing Algorithm), and optionally the changes from this PR: keycloak/keycloak#44874. Without this, some fields are currently saved as empty strings, which leads to runtime issues. It would also be good to address this issue: keycloak/keycloak#44699, as currently it requires explicitly setting the Credential Signing Key ID during client scope creation. Do we have an idea when the next patch release is planned, and whether it would be possible to include these changes? That would help ensure we have a stable version to base the blog post on. |
I am not sure about backporting those to patch release as those are related to experimental feature... If saving client scopes from admin console still has limitations in Keycloak 26.5.0, is it perhaps possible to fallback to admin REST API directly in this blog-post as it was before? |
@mposolda I've updated the blog post as suggested. Could you please take a look? |
mposolda
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@Awambeng Nice, Thanks!
I've added some last minor comments regarding the "Publishing date" and feedback, but I hope we can merge this very soon. Leaving for tomorrow to eventually provide some last reviews (if someone still has some review points). Otherwise hope to merge on Friday.
| @@ -0,0 +1,379 @@ | |||
| :title: Setting Up Keycloak as a Credential Issuer with OpenID4VCI | |||
| :date: 2025-12-02 | |||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is it possible to update this date for example to 2026-01-16 ? This means Friday this week. I hope we can merge this PR on Friday and hence the date would be accurate (this mechanism of date hardcoded in the PR file itself is not so ideal, but that is how it works in current Keycloak blog posts...).
|
|
||
| == Important Note on OpenID4VCI Development Status | ||
|
|
||
| OpenID4VCI support in Keycloak is still under active development. The instructions and configuration options described in this blog post are based on *Keycloak 26.5.0* and may change in future Keycloak versions as the feature evolves. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| OpenID4VCI support in Keycloak is still under active development. The instructions and configuration options described in this blog post are based on *Keycloak 26.5.0* and may change in future Keycloak versions as the feature evolves. | |
| OpenID4VCI support in Keycloak is still under active development. The instructions and configuration options described in this blog post are based on *Keycloak 26.5.0* and may change in future Keycloak versions as the feature evolves. If you want to look at latest updates in the OID4VCI feature, then you can use latest https://www.keycloak.org/nightly/[Keycloak nightly release], however be aware that instructions in this blog may not work with that version. |
Is it possible to add some small sentence about "nightly" build as we briefly discussed on today's meeting? For example something like I've suggested?
| We’d love to hear your thoughts on this guide! You can provide feedback or ask questions through: | ||
|
|
||
| * Slack: Join the https://slack.cncf.io/[Cloud Native Computing Foundation (CNCF) Slack] and discuss with us in the channel https://cloud-native.slack.com/channels/keycloak-oauth-sig[#keycloak-oauth-sig]. | ||
|
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| * Github: Inspect and join recent https://github.com/keycloak/keycloak/discussions?discussions_q=is%3Aopen+oid4vci[OpenID4VCI related Github discussions]. Inspect https://github.com/keycloak/keycloak/issues?q=is%3Aissue%20state%3Aopen%20label%3Aarea%2Foid4vc[existing OpenID4VCI related Github issues] and feel free to comment/upvote some of them or create new issue if you have idea for the enhancement or if you found a bug. |
Is it possible to add a note about feedback on Github? For example something like I've added above? WDYT?
|
@Awambeng Could you please also rebase this PR on top of latest Keycloak-web main? |
Signed-off-by: Awambeng Rodrick <[email protected]>
Signed-off-by: Awambeng Rodrick <[email protected]>
Signed-off-by: Awambeng Rodrick <[email protected]>
Signed-off-by: Awambeng Rodrick <[email protected]>
Signed-off-by: Awambeng Rodrick <[email protected]>
…in REST API with UI-based instructions Signed-off-by: Awambeng Rodrick <[email protected]>
… for enabling Verifiable Credentials Signed-off-by: Awambeng Rodrick <[email protected]>
…and removing signing key ID Signed-off-by: Awambeng Rodrick <[email protected]>
…ayground OID4VCI demo and improving phrasing Signed-off-by: Awambeng Rodrick <[email protected]>
Signed-off-by: Awambeng Rodrick <[email protected]>
Signed-off-by: Awambeng Rodrick <[email protected]>
Signed-off-by: Awambeng Rodrick <[email protected]>
… to use Admin REST API, and clarify OpenID4VCI development status Signed-off-by: Awambeng Rodrick <[email protected]>
Signed-off-by: Awambeng Rodrick <[email protected]>
|
@mposolda I’ve rebased on the latest |
mposolda
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@Awambeng Thanks! Hope to merge tomorrow (if there is no one else wanting to review/comment).
|
I read throught he blogpost again! Looks very good now :) Maybe a followup blogpost cloud also show how the generated SD-JWT VC credential looks like. |
| 7. The **Wallet** requests the **Verifiable Credential** from the **Issuer Credential Endpoint** using the Access Token. | ||
| 8. The **Issuer** returns the **VC** to the Wallet. | ||
|
|
||
| .Credential issuance via Authorization Code Flow |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We can use a Mermaid sequence diagram instead of an image. it will be easier to maintain.
Here is the code for authorization-code-flow.png.
sequenceDiagram
autonumber
participant Wallet
participant User
participant Issuer as Issuer <br/><Keycloak>
Wallet->>Issuer: Authorization Request (request credentials)
Issuer->>User: Authenticate user and request consent
User->>Issuer: Provide credentials and grant consent
Issuer-->>Wallet: Return Authorization Code
Wallet->>Issuer: Exchange Authorization Code for Access Token (Token Endpoint)
Issuer-->>Wallet: Return Access Token
Wallet->>Issuer: Request Verifiable Credential (VC Endpoint) using Access Token
Issuer-->>Wallet: Return Verifiable Credential (VC)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks @embesozzi, that makes sense. Using a Mermaid sequence diagram would definitely be easier to maintain.
The only concern is that our current setup does not seem to support Mermaid, so it would not render properly in the blog post.
@mposolda, what do you think? Should we look into adding Mermaid support, or keep the image for now?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Mermaid is great, but if it is not properly rendered on the web-page and on the blog, then it is not so good option IMO.
Also regarding blog-post, I do not think that we care about maintenance as when blog-post is published, it is usually not later updated. So image is fine for this blog-post IMO.
However we care about maintenance for the Keycloak documentation. For that one, we use https://draw.io for the diagrams. This is not so nice and easy like mermaid, but it works well in Keycloak documentation. See for example token exchange diagram or some other diagrams in the HA guide https://www.keycloak.org/guides#high-availability ).
It seems next step might be to add those nice pictures to the Keycloak documentation and hence possibly rewrite them to use draw.io ? However that is a follow-up not directly related to this blog-post though, but rather to Keycloak documentation...
| 4. The **Wallet** requests the **Verifiable Credential** from the **Issuer Credential Endpoint** using the Access Token. | ||
| 5. The **Issuer** returns the **VC** to the Wallet. | ||
|
|
||
| .Credential issuance via Pre-Authorized Code Flow |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Same here. Below is the code for pre-authorization-code-flow.png.
sequenceDiagram
autonumber
participant Wallet
participant Issuer as Issuer <br><Keycloak>
Issuer-->>Wallet: Send Pre-Authorized Code (QR code or link)
Wallet->>Issuer: Exchange Pre-Authorized Code for Access Token (Token Endpoint)
Issuer-->>Wallet: Return Access Token
Wallet->>Issuer: Request Verifiable Credential (Credential Endpoint) using Access Token
Issuer-->>Wallet: Return Verifiable Credential (VC)
+1 . This can be also nice to better document in the Keycloak documentation. I am not sure how far to go as we probably do not want to duplicate whole sd-jwt format details in the Keycloak docs, but maybe something readable (with nice pictures and easy examples to follow) like for example in the curity docs might be great |
|
Just a minor observation: it would be good to show all URLs in the code examples and images over |
An initial version, so as to collect further early feedback.
Partially addresses #666 and #668 (They are duplicate)
Closes #666 (Let this initial draft close one)
Regarding the video, we're waiting for blocking UI PRs to merged first.