Authenticate using an OIDC Bridge Verifier

The OIDC Credential Verifier is designed for an OIDC Client application to request a DID, so that a wallet app can present its DID to the OIDC relying party.

Prerequisites

• Administrator access to an OIDC Client application. There is a list of OIDC Client apps, also known as ‘Relying Party’ libraries, on the OpenID website Certified OpenID Connect Implementations. Pick one which you feel comfortable with.

• The exact redirect_uri of your OIDC Client (localhost or hosted) and the path to the call back e.g. https://localhost:9090/callback.

Request

Make the following request to create an OIDC Credential Verifier:

1POST https://YOUR_TENANT_URL/ext/oidc/v1/verifiers

1{
2  "verifierDid": "did:key:z6MkrYVmyqSA93o4B1GwERM8kaQDMAUKAFV2TC3weQKeg9Gq",
3  "presentationTemplateId": "aee61692-3568-484a-8eda-e150c48ec9e6",
4  "claimMappings": []
5}

• verifierDid: Specifies the DID of the Verifiable Presentation recipient, so must be a valid DID on your tenant.

• presentationTemplateId: Use the unique identifier of the presentation request template created in the previous step. This is the template that will be used by this verifier.

Response

1{
2  "id": "41458e5a-9092-40b7-9a26-d4eb43c5792f",
3  "verifierDid": "did:key:z6MkrYVmyqSA93o4B1GwERM8kaQDMAUKAFV2TC3weQKeg9Gq",
4  "presentationTemplateId": "aee61692-3568-484a-8eda-e150c48ec9e6",
5  "claimMappings": []
6}

• id: Unique identifier of the created OIDC verifier. This identifier will be used later in this tutorial.

Once created, the verifier can be resolved publicly from your tenant by its verifierId.

1GET https://YOUR_TENANT_URL/ext/oidc/v1/verifiers/41458e5a-9092-40b7-9a26-d4eb43c5792f/.well-known/openid-configuration

The Authorization header is not required as it is intended for OIDC Client applications to resolve and therefore should be publicly available.

Create a client

Once you have your OIDC verifier, you need to create an OIDC Client on MATTR VII.

Request

Make the following request to create an OIDC client:

1POST https://YOUR_TENANT_URL/ext/oidc/v1/verifiers/41458e5a-9092-40b7-9a26-d4eb43c5792f/clients

1{
2    "name": "DID_Auth_Demo",
3    "redirectUris": [
4        "https://localhost:9090/callback"
5    ],
6    "responseTypes": [
7        "code"
8    ],
9    "grantTypes": [
10        "authorization_code"
11    ],
12    "tokenEndpointAuthMethod": "client_secret_post",
13    "idTokenSignedResponseAlg": "ES256",
14    "applicationType": "web"
15}

• name: Give your new client a meaningful name to recognise it by.

• redirectUris: This is the URL that the response will be sent to. It can accept a list of URLs, but at least one must match the callback to your OIDC Client that is made in the Authorisation Request, including https, fqdn and path.

  • Must be a valid URL.

  • Must use the HTTPS protocol.

  • Must not be an IP address.

  • Must not include query parameters.

  • For testing you can use a local host such as https://localhost:9090/callback.

• We’re sticking with the OIDC Authorisation Code flow, so we will keep the responseTypes, grantTypes, tokenEndpointAuthMethod and idTokenSignedResponseAlg all at their default values.

• There are other settings available for this endpoint like logoUri that can be used to enhance the UI. Refer to the API Reference for a detailed description.

Response

The above request will create a new client and provide a response similar to the following:

1{
2    "name": "DID_Auth_Demo",
3    "redirectUris": [
4        "https://localhost:9090/callback"
5    ],
6    "responseTypes": [
7        "code"
8    ],
9    "grantTypes": [
10        "authorization_code"
11    ],
12    "tokenEndpointAuthMethod": "client_secret_post",
13    "idTokenSignedResponseAlg": "ES256",
14    "applicationType": "web",
15    "id": "ukM3NWLFZJFSxh6DN2lg6",
16    "secret": "XDW7vuJ2Q6w9uPKUa8djN2Fz03YjKMIaGAQ6REeXhp2LgUfXTvNMgd7orvfrhwYQJAtMksypRVMvdy7MZUTAA",
17}

• Make note of the id and secret values, as you will need those later.

Your OIDC Bridge is now configured for DID Auth requests using an OpenID Connect Client application.

Sending the authentication request

Make the following request to initiate the Authorisation Code Flow by creating an authorisation request:

1https://YOUR_TENANT_URL/ext/oidc/v1/verifiers/41458e5a-9092-40b7-9a26-d4eb43c5792f/authorize
2?response_type=code
3&client_id=ukM3NWLFZJFSxh6DN2lg6
4&redirect_uri=https://localhost:9090/callback
5&scope=openid

All OIDC requests must contain scope value of openid as the first scope.

Copy the whole request with all the query parameters and paste it into your browser. If your client is configured correctly you should see a page showing a QR code.

By navigating to the Authorisation endpoint, you have initiated an OIDC Authorisation Code Flow. The OIDC Bridge extension has generated a QR code that includes a reference to a JWM message from your tenant, the payload of this message is a Presentation Request, using a DIDAuth query type, that can be interpreted by a Mobile Wallet.

By scanning the QR code (or following the deeplink) the MATTR Mobile Wallet App will create a DID for the connection and respond to the request with a proof of DID ownership.

Upon successful presentation, the browser will redirect to the redirect_uri provided in the authorisation request, with a code query parameter added.

Your OIDC client application will obtain the DID by requesting the token from the OpenID Provider.