Package org.keycloak.protocol.oid4vc.issuance

Class OID4VCIssuerEndpoint

java.lang.Object

org.keycloak.protocol.oid4vc.issuance.OID4VCIssuerEndpoint

public class OID4VCIssuerEndpoint
extends Object

Provides the (REST-)endpoints required for the OID4VCI protocol.

Author:

Stefan Wiedemann

Field Summary

Fields

Modifier and Type	Field	Description
static final String	AUTHORIZATION_DETAILS_CLAIMS_PREFIX	Prefix for session note keys that store authorization details claims.
static final String	CREDENTIAL_CONFIGURATION_IDS_NOTE	Session note key for storing credential configuration IDs from credential offer.
static final String	CREDENTIAL_OFFER_PATH
static final String	CREDENTIAL_OFFER_URI_CODE_SCOPE
static final String	CREDENTIAL_PATH
static final String	DEFLATE_COMPRESSION
static final String	NONCE_PATH
static final String	OID4VCI_ENABLED_ATTRIBUTE_KEY
static final String	RESPONSE_TYPE_IMG_PNG

Constructor Summary

Constructors

Constructor	Description
OID4VCIssuerEndpoint(KeycloakSession keycloakSession)
OID4VCIssuerEndpoint(KeycloakSession session, Map<String,CredentialBuilder> credentialBuilders, AppAuthManager.BearerTokenAuthenticator authenticator, TimeProvider timeProvider, int preAuthorizedCodeLifeSpan)

Method Summary

Modifier and Type	Method	Description
jakarta.ws.rs.core.Response	getCNonce()	the OpenId4VCI nonce-endpoint
jakarta.ws.rs.core.Response	getCredentialOffer(String nonce)	Provides an OID4VCI compliant credential offer
jakarta.ws.rs.core.Response	getCredentialOfferPreflight(String nonce)	Handles CORS preflight requests for credential offer endpoint
jakarta.ws.rs.core.Response	getCredentialOfferURI(String credConfigId)	Creates a Credential Offer Uri that is bound to the calling user.
jakarta.ws.rs.core.Response	getCredentialOfferURI(String credConfigId, boolean preAuthorized, String targetUser)	Creates a Credential Offer Uri that is bound to a specific user.
jakarta.ws.rs.core.Response	getCredentialOfferURI(String credConfigId, boolean preAuthorized, String appClientId, String appUsername, OfferUriType type, int width, int height)	Creates a Credential Offer Uri that can be pre-authorized and hence bound to a specific client/user id.
jakarta.ws.rs.core.Response	getCredentialOfferURIPreflight()	Handles CORS preflight requests for credential offer URI endpoint.
jakarta.ws.rs.core.Response	requestCredential(String requestPayload)	Returns a verifiable credential

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

CREDENTIAL_CONFIGURATION_IDS_NOTE

public static final String CREDENTIAL_CONFIGURATION_IDS_NOTE

Session note key for storing credential configuration IDs from credential offer. This allows the authorization details processor to easily retrieve the configuration IDs without having to search through all session notes or parse the full credential offer.

See Also:

• Constant Field Values

AUTHORIZATION_DETAILS_CLAIMS_PREFIX

public static final String AUTHORIZATION_DETAILS_CLAIMS_PREFIX

Prefix for session note keys that store authorization details claims. This is used to store claims from authorization details for later use during credential issuance.

See Also:

• Constant Field Values

DEFLATE_COMPRESSION

public static final String DEFLATE_COMPRESSION

See Also:

• Constant Field Values

NONCE_PATH

public static final String NONCE_PATH

See Also:

• Constant Field Values

CREDENTIAL_PATH

public static final String CREDENTIAL_PATH

See Also:

• Constant Field Values

CREDENTIAL_OFFER_PATH

public static final String CREDENTIAL_OFFER_PATH

See Also:

• Constant Field Values

RESPONSE_TYPE_IMG_PNG

public static final String RESPONSE_TYPE_IMG_PNG

See Also:

• Constant Field Values

CREDENTIAL_OFFER_URI_CODE_SCOPE

public static final String CREDENTIAL_OFFER_URI_CODE_SCOPE

See Also:

• Constant Field Values

OID4VCI_ENABLED_ATTRIBUTE_KEY

public static final String OID4VCI_ENABLED_ATTRIBUTE_KEY

See Also:

• Constant Field Values

Constructor Details

OID4VCIssuerEndpoint

public OID4VCIssuerEndpoint(KeycloakSession session,
 Map<String,CredentialBuilder> credentialBuilders,
 AppAuthManager.BearerTokenAuthenticator authenticator,
 TimeProvider timeProvider,
 int preAuthorizedCodeLifeSpan)

OID4VCIssuerEndpoint

public OID4VCIssuerEndpoint(KeycloakSession keycloakSession)

Method Details

getCNonce

@POST
@Produces("application/json")
@Path("nonce")
public jakarta.ws.rs.core.Response getCNonce()

the OpenId4VCI nonce-endpoint

Returns:

a short-lived c_nonce value that must be presented in key-bound proofs at the credential endpoint.

getCredentialOfferURIPreflight

@OPTIONS
@Path("credential-offer-uri")
public jakarta.ws.rs.core.Response getCredentialOfferURIPreflight()

Handles CORS preflight requests for credential offer URI endpoint. Preflight requests return CORS headers for all origins (standard CORS behavior). The actual request will validate origins against client configuration.

getCredentialOfferURI

public jakarta.ws.rs.core.Response getCredentialOfferURI(String credConfigId)

Creates a Credential Offer Uri that is bound to the calling user.

getCredentialOfferURI

public jakarta.ws.rs.core.Response getCredentialOfferURI(String credConfigId,
 boolean preAuthorized,
 String targetUser)

Creates a Credential Offer Uri that is bound to a specific user.

getCredentialOfferURI

@GET
@Produces({"application/json","image/png"})
@Path("credential-offer-uri")
public jakarta.ws.rs.core.Response getCredentialOfferURI(@QueryParam("credential_configuration_id")
 String credConfigId,
 @QueryParam("pre_authorized") @DefaultValue("true")
 boolean preAuthorized,
 @QueryParam("client_id")
 String appClientId,
 @QueryParam("username")
 String appUsername,
 @QueryParam("type") @DefaultValue("uri")
 OfferUriType type,
 @QueryParam("width") @DefaultValue("200")
 int width,
 @QueryParam("height") @DefaultValue("200")
 int height)

Creates a Credential Offer Uri that can be pre-authorized and hence bound to a specific client/user id.

Credential Offer Validity Matrix for the supported request parameters "pre_authorized", "client_id", "username" combinations.

+----------+-----------+---------+---------+-----------------------------------------------------+ | pre-auth | clientId | username | Valid | Notes | +----------+-----------+---------+---------+-----------------------------------------------------+ | no | no | no | yes | Generic offer; any logged-in user may redeem. | | no | no | yes | yes | Offer restricted to a specific user. | | no | yes | no | yes | Bound to client; user determined at login. | | no | yes | yes | yes | Bound to both client and user. | +----------+-----------+---------+---------+-----------------------------------------------------+ | yes | no | no | no | Pre-auth requires a user subject; missing username. | | yes | yes | no | no | Same as above; username required. | | yes | no | yes | yes | Pre-auth for a specific user; client unconstrained. | | yes | yes | yes | yes | Fully constrained: user + client. | +----------+-----------+---------+---------+-----------------------------------------------------+

Parameters:

credConfigId - A valid credential configuration id

preAuthorized - A flag whether the offer should be pre-authorized (requires targetUser)

appClientId - The client id that the offer is authorized for

appUsername - The username that the offer is authorized for

type - The response type, which can be 'uri' or 'qr-code'

width - The width of the QR code image

height - The height of the QR code image

getCredentialOfferPreflight

@OPTIONS
@Path("credential-offer/{nonce}")
public jakarta.ws.rs.core.Response getCredentialOfferPreflight(@PathParam("nonce")
 String nonce)

Handles CORS preflight requests for credential offer endpoint

getCredentialOffer

@GET
@Produces("application/json")
@Path("credential-offer/{nonce}")
public jakarta.ws.rs.core.Response getCredentialOffer(@PathParam("nonce")
 String nonce)

Provides an OID4VCI compliant credential offer

requestCredential

@POST
@Consumes({"application/json","application/jwt"})
@Produces({"application/json","application/jwt"})
@Path("credential")
public jakarta.ws.rs.core.Response requestCredential(String requestPayload)

Returns a verifiable credential