How to verify a Web Credential presentation using the OIDC Bridge

Configure an OIDC Verifier

Request

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

POST /ext/oidc/v1/verifiers

Request body

{
    "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

{
    "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:

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:

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

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

Request body

{
    "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 (opens in a new tab) or Cloudflare (opens in a new tab).
• 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

{
    "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:

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

1. 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.

2. 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.

3. 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.

4. 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/ (opens in a new tab).