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 Details

  • Constructor Details

  • 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.
      See Also:

    • createCredentialOfferPreflight

      @OPTIONS @Path("create-credential-offer") public jakarta.ws.rs.core.Response createCredentialOfferPreflight()
      Handles CORS preflight requests for the /create-credential-offer endpoint. Preflight requests return CORS headers for all origins (standard CORS behavior). The actual request will validate origins against client configuration.

    • createCredentialOffer

      public jakarta.ws.rs.core.Response createCredentialOffer(String credConfigId)
      Creates a Pre-Authorized offer that is bound to the calling user.

    • createCredentialOffer

      public jakarta.ws.rs.core.Response createCredentialOffer(String credConfigId, boolean preAuthorized, String targetUser)
      Creates a Credential Offer that is bound to a specific user.

    • createCredentialOffer

      @GET @Produces({"application/json","image/png"}) @Path("create-credential-offer") public jakarta.ws.rs.core.Response createCredentialOffer(@QueryParam("credential_configuration_id") String credConfigId, @QueryParam("pre_authorized") @DefaultValue("true") Boolean preAuthorized, @QueryParam("tx_code") @DefaultValue("false") Boolean withTxCode, @QueryParam("target_user") String targetUser, @QueryParam("expire") Integer expireAt, @QueryParam("type") @DefaultValue("uri") OfferResponseType responseType, @QueryParam("width") @DefaultValue("200") int width, @QueryParam("height") @DefaultValue("200") int height)
      Creates a Credential Offer that can be pre-authorized and/or bound to a specific target user.

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

      +----------+----------+---------+--------------------------------------------+ | Pre-Auth | Username | Valid | Notes | +----------+----------+---------+--------------------------------------------+ | no | no | yes | Anonymous offer; works for any login user. | | no | yes | yes | Offer restricted to a specific user. | +----------+----------+---------+--------------------------------------------+ | yes | no | yes | Self issued pre-auth offer. | | yes | yes | yes | Offer restricted to a specific user. | +----------+----------+---------+--------------------------------------------+

      Pre-Authorized Offer
      • A pre-authorized offer is authorized for the clientId from the current login session
      • If targetUser is null or empty, it defaults to the user from the current login session
      • If targetUser is equal to the current login, the generated offer is "self issued"
      • To create an offer for another user, the issuing user must hold the credential_offer_create role
      • A pre-authorized offer can optionally have an associated tx_code
      • An offer can optionally have a predefined expiry date
      Non Pre-Authorized Offer
      • If targetUser is null or empty, the generated offer is "anonymous"
      • If targetUser is equal to the current login, the offer is "self issued"
      • If targetUser is none of the above, the offer is "targeted"
      • For a targeted offer, the issuing user must hold the credential_offer_create role
      • An offer can optionally have a predefined expiry date
      The responseType supports "Same Device" and "Cross Device" use cases.

      +---------+------------------+-------------------------------------------+ | Type | Mime-Type | Notes | +---------+------------------+-------------------------------------------+ | uri | application/json | JSON document that contains the offer uri | | uri+qr | application/json | Same as 'uri' plus url encoded qr-code | | qr | image/png | Credential offer encoded as qr-code image | +---------+------------------+---------+---------------------------------+

      This endpoint creates an internal credential offer state, which can then be accessed via a uniquely generated credential offer uri. It is the responsibility of the caller to communicate the credential offer to the target user in a secure manner.

      If the response contains a generated tx_code, which protects a pre-auth offer with a second layer of security, this tx_code must be sent over an alternative communication channel (i.e. not together with the offer itself)
      Parameters:
      credConfigId - A valid credential configuration id
      preAuthorized - A flag whether the offer should be pre-authorized
      targetUser - The username that the offer is authorized for
      withTxCode - A flag whether a tx_code should be generated for a pre-auth offer
      expireAt - The date/time when the offer expires (in Unix timestamp seconds)
      responseType - The response type, which can be 'uri', 'qr' or 'uri+qr'
      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