Learn

Set up an OIDC Credential Issuer

The OIDC Bridge issuer is currently marked as 'Retired' as per our Service Level Agreement. It is no longer actively enhanced or supported and will be removed from the MATTR VII platform on August 19th, 2024. It is highly recommended to use the improved OpenID4VCI protocol when issuing credentials.

Introduction

To use the OIDC Bridge as an OpenID Connect Credential Provider, you need to add an OIDC Credential Issuer so that a digital wallet can discover the OIDC Bridge details.

This guide will step through how that can be achieved by setting up the OIDC Credential Issuer.

Prerequisites

You need the following in order to proceed with this tutorial:

  • Access to the MATTR VII APIs. If you’re experiencing difficulty, contact us.

  • The DID (Decentralized Identifier) to use for issuing credentials, both basic and ZKP-enabled credentials can be issued depending on the keyType of the DID used.

  • A correctly-configured OpenID Provider (OP). Have the client_id and client_secret close at hand.

  • Understand the payload of the ID token issued by your OP so you can map claims.

  • Download the MATTR Mobile Wallet App and have it set up with a PIN.

If you’re experiencing any difficulties please contact us.

The OIDC Credential Issuer

The OIDC Credential Issuer publishes its OpenID Provider metadata at its /.well-known/openid-configuration endpoint. It is designed to expose enough information for a client (in this case the Mobile Wallet App) to ingest and present a screen to the user to establish consent before kicking off an OpenID Connect-based credential issuance flow via an authorization request.

The OIDC Credential Issuer will then federate out authorization to the configured federatedProvider (the OP you have previously configured) and ingest the ID Token.

Using mappings configured in the OIDC Credential Issuer, the Extension will invoke the credential creation operation on your tenant and package the response into credential object on the token endpoint.

Create an OIDC Credential Issuer

Create an OIDC Credential Issuer by invoking the API as follows:

Request

http
Copy to clipboard.
1POST https://YOUR_TENANT_URL/ext/oidc/v1/issuers
json
Copy to clipboard.
1{
2    "credential": {
3        "issuerDid": "did:web:organization.com",
4        "issuerName": "Example University",
5        "name": "My Custom Credential",
6        "context": [
7            "https://schema.org"
8        ],
9        "type": [
10            "CourseCredential"
11        ]
12    },
13    "federatedProvider": {
14        "url": "https://your-auth0-tenant.au.auth0.com",
15        "clientId": "auth0_client_id",
16        "clientSecret": "auth0_client_secret",
17        "claimsSource": "idToken",
18        "tokenEndpointAuthMethod": "client_secret_post"/"client_secret_basic"，
19        "scope": [
20            "openid",
21            "profile",
22            "email"
23        ]
24    },
25    "staticRequestParameters": {
26        "prompt": "login",
27        "max_age": 10000
28    },
29    "forwardedRequestParameters": [
30        "login_hint"
31    ],
32    "claimMappings": [
33        {
34            "oidcClaim": "name",
35            "jsonLdTerm": "name"
36        },
37        {
38            "oidcClaim": "https://YOUR_TENANT_URL/educationalCredentialAwarded",
39            "jsonLdTerm": "educationalCredentialAwarded"
40        }
41    ]
42}

The request consists of 5 sections:

1. Credential

The credential object defines:

  • which issuerDid to use.

  • the meaningful name of the credential that will appear in the digital wallet.

  • the JSON-LD context and credential type.

  • issuerName field is optional and can be used to define the name of the issuer. If provided, the value will be used when displaying the issued credentials in the wallet. If not provided, the wallet will show the tenant domain on the issued credentials.

  • type defines the type of the Web Credential. This is a unique identifier that the system uses to differentiate between different types of Web Credentials. There MUST be a value of type other than VerifiableCredential in the configuration payload.

To issue a ZKP-enabled credential use an issuerDid with the keyType of Bls12381G2, this will result in a BBS+ signature credential stored in the mobile wallet. View the Verify a ZKP Enabled Credential tutorial on how to verify selectively-disclosed information.

2. Federated provider

The federatedProvider object defines the attributes of your OpenID Provider configuration including:

  • URL

  • Client ID

  • Client Secret

  • Scopes required to invoke claims with your information systems

If no scope is provided, the default value openid profile email will be used.

  • Claim Source is either idToken by default or userInfo

  • tokenEndpointAuthMethod is either client_secret_post by default if not provided, or client_secret_basic

3. Claim mappings

The claimMappings collection defines the subject claims for the credential by mapping OpenID Connect claims from the ID token to JSON-LD terms that will be used when creating the Verifiable Credential along with the context provided in the credential object as the data vocabulary.

By default the platform supports schema.org as a data vocabulary, please contact us if you wish to explore other options.

  • oidcTerm is the OIDC claim name

  • jsonLdTerm is the JSON-LD term name

Use the payload of your ID token (e.g. view it in jwt.io) to obtain the exact field name used and map the required fields to a valid JSON-LD term from schema.org.

The common OIDC claims are already mapped for you on here, so you can copy and paste these into your claimMappings collection if you wish.

Only claims you explicitly map to JSON-LD terms will appear in the issued credential; all other claims in the ID token will be disregarded. Likewise, additional mappings in your Issuer will be ignored at Credential issuance if the claims do not exist in the ID token (although they will appear in the Offer screen in the mobile app).

The entire Schema.org list of JSON-LD terms can be accessed directly and used to look-up terms. Use the rdfs:label value.

4. staticRequestParameters

Parameters that should be included in the request to the IDP. Keys must be strings. Values of top level object keys must stringify to less than 1000 characters each.

5. forwardedRequestParameters

Parameters that can be provided by the client to be forwarded to the IDP. The forwarded parameter values are limited to under 1000 characters when stringified.

Response

json
Copy to clipboard.
1{
2    "id": "983c0a86-204f-4431-9371-f5a22e506599",
3    "credential": {
4        "issuerDid": "did:web:organization.com",
5        "name": "My Custom Credential",
6        "context": [
7            "https://schema.org"
8        ],
9        "type": [
10            "CourseCredential"
11        ]
12    },
13    "federatedProvider": {
14        "url": "https://your-auth0-tenant.au.auth0.com",
15        "clientId": "auth0_client_id",
16        "clientSecret": "*******************",
17        "claimsSource": "idToken",
18        "tokenEndpointAuthMethod": "client_secret_post"/"client_secret_basic"，
19        "scope": [
20            "openid",
21            "profile",
22            "email"
23        ]
24    },
25    "staticRequestParameters": {
26        "prompt": "login"，
27        "maxAge": 10000
28    },
29    "forwardedRequestParameters": [
30        "login_hint"
31    ],
32    "claimMappings": [
33        {
34            "oidcClaim": "name",
35            "jsonLdTerm": "name"
36        },
37        {
38            "oidcClaim": "https://YOUR_TENANT_URL/educationalCredentialAwarded",
39            "jsonLdTerm": "educationalCredentialAwarded"
40        }
41    ]
42}

The full callbackUrl is included in the response. This will likely be required to be configured within your OpenID Provider as an ‘allowed callback’.

The response will mask federatedProvider.clientSecret. It will be completely masked if it is less than 20 characters, and only expose the last 5 characters if it is 20 characters or longer.

The newly-created Issuer can be resolved publicly using the id value in the above response:

http
Copy to clipboard.
1GET https://YOUR_TENANT_URL/ext/oidc/v1/issuers/983c0a86-204f-4431-9371-f5a22e506599/.well-known/openid-configuration

The Authorization header is not required as it is intended for a digital wallet client to resolve.

You now have an OIDC Credential Issuer configured for Verifiable Credential issuance. Continue to the next step to complete configuration of your OP and to issue a credential.