Motivation

With recent developments, Keycloak can serve as an OID4VCI issuer, issuing a verifiable credential for parties to validate the identity of a user. Enabling users to log in to Keycloak by presenting that same credential is a valid use case, and one that is gaining traction.

The SD-JWT format for verifiable credentials is certainly one of the most supported currently. In our use case at adorsys, we specifically want to exchange an SD-JWT identity credential for an access token, so as to maintain legacy systems operable. By this, we mean Keycloak is not intended to implement the OID4VP peer protocol to OID4VCI for verifying presentations, which, given its complexity, would have probably justified the addition of some dependencies. Instead, Keycloak is intended to verify SD-JWT presentations, i.e., with the presence of a Key Binding JWT (KB-JWT), and eventually return an access token.

For reference, these issues enabled Keycloak to run this SD-JWT verification:

• Implement advanced verification of SD-JWT in Keycloak #30907
• Keycloak native verification of an SD-JWT based vp_token #29859

Proposal

Our proposal is to delegate OID4VP interaction with a user wallet to an external client, which in turn, runs this SD-JWT against access token exchange with Keycloak. Though OAuth 2.0 for First-Party Applications (FiPA) is primarily thought for providing native login experience, we believe it remains sufficiently agnostic of the authentication means to enable its API-only conceptual foundation to be leveraged for this SD-JWT authentication. The FiPA flow is particularly helpful in preventing replayed presentations.

SD-JWT authentication may be achieved by implementing an SD-JWT authenticator for FiPA for these reasons:

• Confidential clients can seamlessly and reliably authenticate as first-party apps.
• The Error Response at the Authorization Challenge Endpoint is thought to communicate metadata for accompanying authentication flows. Here, we define such metadata to include information to use for producing a valid SD-JWT presentation, including a nonce (for replay protection), a credential type, some expected fields, and other presentation requirements.

Here is a comprehensive sequential diagram of the scenario:

%%{init: {'sequence': {'actorMargin': 150}}}%%
sequenceDiagram
    participant C as FiPA Client
    participant K as Keycloak

    C->>K: Authorization Challenge Request
    Note over C,K: {client_id, client_secret, auth_flow: "sdjwt-flow"}
    K-->>C: Authorization Error Response
    Note over C,K: 400: {auth_session, auth_metadata: {vct, nonce, aud, required_claims}}

    C->>K: Authorization Challenge Request
    Note over C,K: {client_id, client_secret, auth_flow: "sdjwt-flow", auth_session, sdjwt_token}
    K-->>C: Authorization Code Response
    Note over C,K: 200: {authorization_code}

    C->>K: Access Token Request
    Note over C,K: {client_id, client_secret, auth_flow: "sdjwt-flow", auth_session, sdjwt_token}
    K-->>C: Access Token Response
    Note over C,K: 200: {access_token}

Comments:

• The first call to the authorization challenge endpoint is expected to fail and return the metadata required for the user to prepare a valid SD-JWT presentation.
• With authentication metadata, the authenticating party can prepare a valid non-replayable SD-JWT presentation and exchange it for an authorization code.
• Finally, the authorization code is exchanged for an access token.

We could implement a functional PoC on this logic and are particularly seeking input from the community with the expectation to amend and contribute our code to Keycloak, enabling user authentication by presentation of an SD-JWT identity credential.

Useful links

• Main discussion on FiPA: Support for native login experiences with OAuth 2.0 First-Party Applications #25014
• Related discussion but more general: Keycloak exchange of a verifiable presentation against an access token #29857