Repository navigation
[OID4VCI] Clarification of issuance use-cases #45626
Replies: 6 comments 15 replies
|
About "CredentialOffer comes from DataHolder" ... The image suggests that there is an entity external to Keycloak that somehow fabricates a credential offer json document. The issuer would not know anything about such an offer (i.e. it has no offer state). If this document is meant to transport some credential metadata to the wallet, which then allows the wallet to get a verifiable credential (by scope or credential_configuration_id) it would perhaps be better to name it as such (i.e. not credential offer) to avoid confusion with an actual credential offer, which is always created by the Issuer. Alternatively, if it is indeed meant to be a credential offer as outlined by the spec, that external entity would want to make a call to Keycloak to the credential offer created on its behalf. The first arrow would go the other way, from the University Portal to the Issuer. The credential offer then existed in Keycloak and could be shown, transported, and acted upon. 8000 Also worth noting, that the issuer would likely want to have a chance to apply credential offer policies, which might deny credential offer creation for one reason or another. |
|
I was wondering about the same when looking at this picture :-) It seems to me that the credential-offer from the "CredentialOffer comes from DataHolder" flow is |
|
Exactly. @mposolda explained it correctly. The Credential Offer created here by the University simply informs the wallet that it can obtain a credential using the Authorization Code Flow at a specific Authorization Server. This Credential Offer must not be created by Keycloak. |
|
@Captain-P-Goldfish Thanks for the extensive list of use-cases! I have more things, but wanted to check about the "Security considerations" in the flow "User initiates Issuance from Keycloak Portal" .
If I understand correctly, this is about the fact, that some credential types can be initiated by user himself (user self-issuance flows) without a need for the administrator to create credential-offer for the user. However for some others, it is strictly required that administrator creates credential offer for the user. Is it correct? Considering this, it seems to me there is some inconsistency in current Keycloak as:
I wonder if we need some configuration option on OID4VCI client scope like WDYT? |
|
We are making progress. This is the issue that captures changes/fixes to credential offer creation. @Captain-P-Goldfish shall we continue our talks specifically on this topic? It seem important, I'd like to get it right with respect to ...
... and yes, of course it needs to support the use cases you already have. |
@Captain-P-Goldfish I see it the same. Current REST API can be improved. IMO ideas to improve mentioned in #45005 (and presented by @tdiesler on last SIG meeting) are all good and also if we can make sure that QR-code (deep link) is not directly visible to admin (Added some idea here in 2.b for REST API endpoint). However still some limitations of REST approach are there... I hope to prototype "actions" based approach and share with you guys soon... At the same time, if there is really hard requirement that "Data holder" (or "Issuer portal" application) must be able to display QR-code with the pre-authorization-code on it's page (rather than being displayed on Keycloak UI), then REST API might be also still needed though... As "actions" based approach is not going to support this. |
FYI. Created #45777 |
Seeing forward to it |
I think it is not necessary for the time being. I may still be wrong, but I am confident that this will become clearer once everything has been defined in more detail. |
Is that so? I thought the /credential-offer-uri is the only place where |
|
Oh dear, I just found this ... Credential offers created on demand as part of authorization code flow. What is the rational behind that? |
|
@tdiesler I suppose Adorsys team would know the answer as they implemented it :-) However at the same time: The "credential offer" created here is in fact just an internal credential-offer saved inside Keycloak storage. I suppose the reason is that OID4VCI credentialRequest currently always require internal credential-offer to exists in the IMO the flow without "real" credential-offer makes sense. If I understand correctly, this is for example the case with the @Captain-P-Goldfish example above for the flow "User initiates Issuance directly from Wallet" or for the use-case H.4 from the specs . At the same time, I can see that for some verifiable-credential types it should not be permitted that user himself initiates the flow without any pre-created credential-offer created for him by administrator. |
|
That the CredentialRequest always requires an internal CredentialOfferState would likely be wrong. AFAIK, it should be ok to request a credential based on scope or credential_configuration_id alone. The CredentialOfferState represents the credential offer as made by the Issuer. An external actor can ask the Issuer to create a credential offer if it has the privileges to do so, but it is never a side effect of some other flow. I guess it boils down to the question "Can I trigger credential offer creation for myself without having special privileges?". Before we introduced the the credential offer matrix it was actually the only way to create an offer (i.e. the Issuer could not create an offer for somebody else). As it is now (I believe), the /credential-offer-uri endpoints requires a target user for pre-auth offers even if that target user is the (authorized) user that calls the endpoint. That condition could possibly be relaxed like this ...
I can't say, I fully understand the use case. Why would a wallet need an offer when it knows the Issuer (and its metadata) already and can hence request any credential based on that metadata. I can understand that in a cross-device flow the wallet wants to have a QR code that encodes details on how to fetch a given credential. In case of an anonymous non-pre-authorized credential offer, the wallet could get that QR code from the /credential-offer-uri endpoint at any time. No CredentialOfferState would need to be persisted because it does not contain information beyond what is already in the Issuer's metadata/configuration. Persistent CredentialOfferState is needed for ...
Bottom line ... the /credential-offer-uri endpoint could generate a QR for anonymous non-pre-authorized credential offers at anytime for anyone (without storing CredentialOfferState) |
|
@Captain-P-Goldfish Few more comments to your use-cases:
|
Yes, my list of use cases is incomplete. However, I think we can derive the missing cases quite easily from the ones mentioned above: the main difference is that an administrator initiates the process by providing the Credential Offer to the user (for example, via email). In those administrator-driven scenarios, I believe the Credential Offer should use the Authorization Code Flow rather than the Pre-Authorized Code Flow. The Authorization Code Flow is significantly more secure, because the user must authenticate and explicitly approve the issuance. This also reduces the risk that a credential could be imported into a different wallet without the user’s knowledge or consent.
You are correct. The Credential Offer from the Data Holder is only meant to tell the wallet that it should start an Authorization Code Flow with the given Authorization Server (Credential Issuer) in order to obtain the referenced credential.
Exactly.
Yes, we already have one use case as a test-scenario running that follows a similar pattern using a proprietary protocol between two instances. In this setup, the Data Holder pushes data to a custom endpoint, and a special authenticator creates a transient user instance when the user is delegated using a short-lived identifier during the redirect. |
|
and thanks for the thorough review! |
I see it similarly. Although I can imagine that administrator can create credential-offer also for the pre-authorization code flow, although that credential-offer (qr-code / deep link) would be displayed to the user on the KC page after it is confirmed that user authenticated to KC. User can then scan qr-code to his wallet, which would do pre-authorization code flow. That is pretty much what I am trying with the "Actions" approach. |
By fabricating a credential offer (instead of obtaining it from the Issuer), the Data Holder bypasses credential offer policies that the Issuer may have put in place in order to restrict what is getting offered (i.e. credential_identifier), who the offer is valid for (i.e. allowed target users), when it will expire and perhaps other details that the credential offer state holds. Is there really a benefit of not asking the Issuer? Something must create that pseudo offer and possibly generate the QR code for it, why not make a simple http call to have Keycloak do the same? In the latter case, we could then reason about a "credential offer" and would not need to distinguish between externally fabricated ones and those generated by Keycloak. |
|
I see the "fabricating credential offer" just as an implementation detail that internal Java "Credential offer" object is created to be able to later use it from However IMO when clientScope has option **Allow user self-issued credential ** switched to "off", then it should not be possible to "fabricate" this internal credential-offer during |
|
Here is another issuance use-case to consider similar to the above but with another layer added. My perspective is a large scale government deployment (not EU). I am posting in this thread based on the discussion title. I apologize in advance if this should be considered a new discussion topic and will update as appropriate. Layers and definitions as follows:
Observation: The digital credential vendors and open source developers are building AS functionality into their technical stack with all the security risks that entails. Traditional IAM vendors were building credential issuance into their stacks (MS, OKTA etc..) but appear to have backed away from that to focus on verification which is a much larger opportunity - small number of issuers of foundational credentials, large number of verifiers. There is an opportunity here. Reasons for doing this This configuration allows for more flexibility and customization in large scale deployments (i.e. government) with a clear separation of responsibilities.
Testing to Date I have built a pre-authorized code flow proof of concept demo that uses an external issuance service. Here are some findings:
What is required for this use case
|
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
In this discussion, I want to focus on real-world scenarios that we are likely to face in the future when working with Keycloak and wallets.
To that end, I have defined a set of use cases (certainly not an exhaustive list) and introduced an additional role in
the OID4VCI protocol that is not explicitly defined in the current specification.
this discussion is related to some technical discussions I had with @tdiesler.
I would kindly like to invite the following developers for review if you are interested:
@mposolda @IngridPuppet @Awambeng @thomasdarimont @francis-pouatcha @forkimenjeckayang
Summary: Separation of Credential Issuer and DataHolder
OID4VCI defines a protocol-level model in which the Credential Issuer is implicitly
assumed to be both:
As a result, OID4VCI does not distinguish between protocol responsibilities and
business data ownership.
Our Use Case and Extension
In our use case, these responsibilities are intentionally separated:
Credential Issuer (OID4VCI role)
A technical component (e.g. Keycloak) that:
DataHolder (out-of-spec role)
A business authority (e.g. a university) that:
Note
Please note that DataHolder may not be the correct term here, as there are use cases in which the data is not held by the DataHolder but by Keycloak.
The first four examples below illustrate this issue, as the credential data is stored at the Credential Issuer (Keycloak) rather than at the DataHolder.
The DataHolder is not an OID4VCI concept; it is introduced deliberately to model
real-world delegated issuance scenarios.
Definition of User Interaction
The following concept defines user interaction as any explicit user action that
actively triggers or advances the issuance workflow, such as scanning a QR code,
clicking a deep link, entering a
tx_codeetc.DataHolder initiated Flows
CredentialOffer comes from DataHolder
DataHolder initiates AuthorizationRequest
User Self-Issuance Flows
User initiates Issuance from Keycloak Portal
User initiates Issuance directly from Wallet
Data is retrieved from external provider
Data is retrieved from external Identity Provider
Data is pushed by DataHolder
This use case should be probably setup with a custom-extension instead of being supported natively by Keycloak.
But the diagram shows that we need mechanisms that allow us to add short-living user instances. This can probably be done with appropriate additional endpoints and
AuthenticationExecutionsUsing Pushed Authorization Request for receiving Credential Data?
this use case is just an idea that we could use to get the CredentialData with a PushedAuthorizationRequest of the DataHolder
All reactions