Set up an OIDC Credential Issuer

Introduction

To use the OIDC Bridge Extension 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:

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

POST
https://tenant.platform.mattr.global/oidc/v1/issuers
{
"credential": {
"issuerDid": "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5",
"name": "My Custom Credential",
"context": [
"https://schema.org"
],
"type": [
"Course"
]
},
"federatedProvider": {
"url": "https://your-auth0-tenant.au.auth0.com",
"clientId": "auth0_client_id",
"clientSecret": "auth0_client_secret",
"scope": [
"openid",
"profile",
"email"
],
},
"claimMappings": [
{
"jsonLdTerm": "givenName",
"oidcClaim": "given_name"
},
{
"jsonLdTerm": "familyName",
"oidcClaim": "family_name"
},
{
"jsonLdTerm": "educationalCredentialAwarded",
"oidcClaim": "https://tenant.platform.mattr.global/educationalCredentialAwarded"
}
]
}

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.

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

Currently the platform only 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 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.

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

Response

{
"id": "983c0a86-204f-4431-9371-f5a22e506599",
"credential": {
"issuerDid": "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5",
"name": "My Custom Credential",
"context": [
"https://schema.org"
],
"type": [
"Course"
]
},
"federatedProvider": {
"url": "https://your-auth0-tenant.au.auth0.com",
"clientId": "auth0_client_id",
"clientSecret": "auth0_client_secret",
"callbackUrl": "https://tenant.platform.mattr.global/oidc/v1/issuers/983c0a86-204f-4431-9371-f5a22e506599/federated/callback"
},
"claimMappings": [
{
"jsonLdTerm": "givenName",
"oidcClaim": "given_name"
},
{
"jsonLdTerm": "familyName",
"oidcClaim": "family_name"
},
{
"jsonLdTerm": "educationalCredentialAwarded",
"oidcClaim": "https://tenant.platform.mattr.global/educationalCredentialAwarded"
}
]
}

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 Issuer can be resolved publicly from your tenant using the issuerId:

GET https://tenant.platform.mattr.global/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.