How to verify a JSON credential presentation using the OIDC Bridge

MATTR VII can use a presentation request flow to verify holder’s data. Holders can view these presentation requests in their digital wallets and choose to respond with a verifiable presentation, created from the JSON credentials they hold.

This guide will walk you through successfully orchestrating this workflow and obtaining the response using the OIDC Bridge.

Prerequisites

Administrator access to an OIDC Client application. You can find a list of compatible apps on the OpenID website.
The id of a Presentation request template available on your tenant. This can be any of the following:
DIDs:
- Verifier DID: This is a DID associated with the verifier. It must be available on your MATTR VII tenant and have a key type that can be used for messaging (e.g. a ed25519 key type). Refer to Create a did:key for more information.
- Subject DID: This is a did:key that identifies the intended holder of the credential. This DID is usually retrieved from the intended holder’s digital wallet.
  - Refer to Create a did:key if you need assistance in creating one for testing this feature.
  - In production environments you must have a secure way to obtain the holder’s digital wallet DID:
    - Use DID Auth for any new interactions.
    - Ask the user to share their wallet DID.
    - Request an existing credential as part of a verification workflow, and extract the DID from that interaction.
Download and setup the GO Hold example app.
A JSON credential issued to a digital wallet matching the following:
- The wallet DID matches the Subject DID.
- The credential matches the type defined in the presentation request template.

Overview

Verifying a JSON credential presentation using the OIDC Bridge comprises the following steps:

Configure an OIDC Verifier: This component kicks off the verification workflow.
Configure an OIDC Client: OIDC clients initiate the Authorization Code Flow with an OAuth2/OIDC Authorization Request, which prompts MATTR VII to create the presentation request.
Create a presentation request: Once an OIDC client is configured, you can create a presentation request and share it with the holder.
Receive a verifiable presentation: Upon holder’s consent, the digital wallet responds to the presentation request with a verifiable presentation. MATTR VII then performs the required validation to establish the integrity and authenticity of the data provided.

Configure an OIDC Verifier

Request

Make a request of the following structure to create an OIDC Credential Verifier:

HTTP

POST /ext/oidc/v1/verifiers

Request body

JSON

{
    "verifierDid": "did:web:example.com",
    "presentationTemplateId": "364b6a1b-3600-4927-a6ac-4d66aa6bbac3",
    "claimMappings": [
        {
            "jsonLdFqn": "http://schema.org/givenName",
            "oidcClaim": "given_name"
        },
        {
            "jsonLdFqn": "http://schema.org/familyName",
            "oidcClaim": "family_name"
        },
        {
            "jsonLdFqn": "http://schema.org/educationalCredentialAwarded",
            "oidcClaim": "https://tenant.vii.mattr.global/educationalCredentialAwarded"
        }
    ],
    "includePresentation": true
}

verifierDid : Use the Verifier DID.
presentationTemplateId : Use the id value of an existing presentation template that will be used by this Verifier to create presentation requests.
claimMappings : These mappings are required to map JSON-LD claims returned by the digital wallet to OIDC terms expected by the OIDC Verifier:
- jsonLdFqn : JSON-LD term. Use http:// and not https://. Otherwise you may not get the claims returned in your ID Token.
- oidcTerm : OIDC claim name. Standard OIDC claims are available on the Common Credential to OIDC Claim mappings page.
  Currently only schema.org data vocabularies are supported.
includePresentation (optional): When set to true, the generated id_token will include the original presentation from the wallet.

Response

JSON

{
    "id": "41458e5a-9092-40b7-9a26-d4eb43c5792f"
    //... rest of OIDC Verifier
}

id : Uniquely identifies this OIDC Verifier. You will need it to Configure an OIDC Client in the next step. You can also use it to retrieve, update or delete this OIDC Verifier.

Once created, this OIDC Verifier is publicly available on the tenant’s /.well-known/openid-configuration path, and can be resolved by making a request of the following structure:

HTTP

GET /ext/oidc/v1/verifiers/{id}/.well-known/openid-configuration

id : Replace with the unique OIDC Verifier id returned in the response above.

Configure an OIDC Client

The OIDC configured client will engage with your configured OIDC Verifier to initiate the verification workflow.

Request

Make a request of the following structure to configure an OIDC Client:

HTTP

POST /ext/oidc/v1/verifiers/{id}/clients

id : Replace with the unique OIDC Verifier id returned in the response above.

Request body

JSON

{
    "name": "Verify_Credential_Demo",
    "redirectUris": ["https://example.com/callback"],
    "responseTypes": ["code"],
    "grantTypes": ["authorization_code"],
    "tokenEndpointAuthMethod": "client_secret_post",
    "idTokenSignedResponseAlg": "ES256",
    "applicationType": "web",
    "logoUri": "https://example.com/logo.png"
}

name : Insert a meaningful name for your OIDC Client.
redirectUris : This array can include a list of URLs, one of which must match the callback URI configured on your OIDC Client for the Authorization Request:
- Must be a valid URL.
- Must use the HTTPS protocol.
- Must not be an IP address.
- Must not include query parameters.
- localhost is not supported as a valid redirect URI. For local development, consider using a proxy service such as ngrok or Cloudflare.
responseTypes : Indicates the expected response type. Use code.
grantTypes : Indicates the type of the response. Use authorization_code.
tokenEndpointAuthMethod : Indicates the authentication method. Use client_secret_post.
idTokenSignedResponseAlg : Indicates the token encryption algorithm. Use ES256.
logoUri : Insert a publicly available and valid URI to an image that will be displayed above the QR code during verification workflows.

Response

JSON

{
    "name": "Verify_Credential_Demo",
    "redirectUris": ["https://example.com/callback"],
    "responseTypes": ["code"],
    "grantTypes": ["authorization_code"],
    "tokenEndpointAuthMethod": "client_secret_post",
    "idTokenSignedResponseAlg": "ES256",
    "applicationType": "web",
    "id": "ukM3NWLFZJFSxh6DN2lg6",
    "secret": "XDW7vuJ2Q6w9uPKUa8djN2Fz03YjKMIaGAQ6REeXhp2LgUfXTvNMgd7orvfrhwYQJAtMksypRVMvdy7MZUTAA"
}

id : Make note of your client id this OIDC Client.
secret : Make note of your client secret with this OIDC Client.

Create a presentation request

Once you have set up an OIDC Client, you can create a presentation request to obtain and verify holder’s data.

Construct a request of the following structure:

HTTP

GET /ext/oidc/v1/verifiers/{id}/authorize
?response_type=code
&client_id=ukM3NWLFZJFSxh6DN2lg6
&redirect_uri=https://example.com/callback
&scope=openid openid_credential_presentation

id : Replace with your OIDC Verifier unique id obtained when you configured the OIDC Verifier.
client_id : Replace with the client id obtained in the response when you configured the OIDC Client.
redirect_uri : Replace with the encoded URL that will obtain the Credential claims from the token.

Receive a verifiable presentation

Paste the presentation request in your preferred web browser. This will initiate an OIDC Authorization Code Flow and generate a QR code that can be used to point a device at your tenant and initiate a verification workflow.

On mobile devices the QR code is collapsed by default and a deep link is shown instead.

Once you scan the QR code/select the deep link, the wallet will request consent to respond with a verifiable presentation which includes credentials that match the presentation request template.
Upon consent, the browser will redirect to the redirect_uri provided in the authorisation request with a code query parameter. For example: https://example.com/callback/?code=oGRCuRMt44-ty8cw.
Make a request of the following structure to obtain a token from the configured OIDC Verifier:

Request

POST /ext/oidc/v1/verifiers/{id}/token

id : Replace with the unique id of your configured OIDC Verifier.

Request body

{
    "client_id": "BumzBH9-EGGJfZHwkg7mq",
    "client_secret": "njsF2********************************************************",
    "grant_type": "authorization_code",
    "redirect_uri": "https://example.com/callback",
    "code": "oGRCuRMt44-ty8cw"
}

client_id : Replace with the client id obtained in the response when you configured the OIDC Client.
client_secret : Replace with the client secret obtained in the response when you configured the OIDC Client.
grant_type : Use authorization_code.
redirect_uri : Use the same URI as the presentation request above.
code : Use the code query parameter from the redirect in step 3 above.

Response

{
    "access_token": "KrrFP8GUeddJJtj7EF-4ugdvCl-dDdWwOqvAbvYsmfy",
    "expires_in": 3600,
    "id_token": "{your_id_token}",
    "scope": "openid",
    "token_type": "Bearer"
}

id_token : The claims are included in this JWT token. You can obtain them by using a tool similar to https://jwt.io/.

Callback Basic QuerybyExample