How to implement OpenID for verifiable presentations

This is a mini guide how to implement draft 12 of the new OpenID for Verifiable Presentations 1.0 (OIDC4VP) in the authorisation code flow with the Connect2id server.

This means enabling the server to process OpenID authentication requests with a response_type=code vp_token where the VP token will be returned at the token endpoint. An implicit flow with response_type=vp_token is not currently supported.

1. Install the token response customiser plugin

  • Obtain the latest JAR of the token response customiser plugin.

  • Place the JAR inside the WEB-INF/lib directory of the Connect2id server c2id.war.

  • Deploy the c2id.war with the following Java system properties:

    op.token.response.customizer.enable=true
    op.token.response.customizer.includeAuthzDataParams=vp_token
    

    To verify that the Connect2id server successfully loaded the plugin and it's property configured grep the server logs for the TRC identifier:

    INFO MAIN [main] [TRC0000] Token response customizer enabled: true
    INFO MAIN [main] [TRC0001] Token response customizer: Included authorization data parameters: [vp_token]
    

2. Login page

Your Connect2id server login page must be updated to handle the response_type, presentation_definition, presentation_definition_uri and nonce request parameters in the context of the OIDC4VP spec. In addition, for a successful OIDC4VP request the login page must be capable of retrieving or minting the VP token so that it's made available to the Connect2id server for delivery to the RP at the token endpoint.

  • Prior to passing received OAuth 2.0 authorisation / OpenID authentication requests to the Connect2id server the login page must rewrite the query string so that a response_type=code vp_token is rewritten as response_type=code&vp_token=true. This is necessary because the Connect2id server currently cannot handle custom response_type values and if one, such as vp_token, is encountered, this will produce an invalid_request error. The vp_token=true parameter will appear as custom parameter signalling to the login page that a VP token is requested.

    Example rewrite using the standard OIDC4VP example:

    Received query string:

    response_type=code%20vp_token
    &client_id=https%3A%2F%2Fclient.example.org%2Fcb
    &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
    &presentation_definition=...
    &nonce=n-0S6_WzA2Mj HTTP/1.1
    

    Rewritten query string:

    response_type=code
    &vp_token=true
    &client_id=https%3A%2F%2Fclient.example.org%2Fcb
    &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
    &presentation_definition=...
    &nonce=n-0S6_WzA2Mj
    

    Note, RPs may pass the response_type as vp_token code which is equivalent to code vp_token!

  • Configure the Connect2id server to include the OIDC4VP specific parameters in the consent prompt so that the login page can access them in order to process an OIDC4VP request:

    op.authz.requestParamsInConsentPrompt=vp_token,presentation_definition,presentation_definition_uri,nonce
    
  • If the login page received a consent prompt with the request.vp_token parameter set this is a signal that the RP requested a response_type=code vp_token. The login page should then perform the necessary actions to process the VP token request, such as calling the wallet application of the end-user.

  • When the login page submits the consent object to the Connect2id server it will place the VP token in the data.vp_token parameter (so that it can be picked up the token response customiser plugin). In addition to that the login page should mark the consent as not long-lived (to prevent its persistence) and disable refresh token issue (not applicable here).

    Example minimal consent:

    {
      "scope" : [ "openid" ],
      "long_lived" : false,
      "refresh_token" : { "issue" : false },
      "data" : { "vp_token" : "$vp_token" }
    }
    

    With the VP token placed in this way the Connect2id server will then deliver it with the token response to the RP.