Common OIDC to Credential Claim mappings

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

As described in the guide to Set up an OIDC Credential Issuer, claims from the ID Token need to be mapped to JSON-LD terms used by the OIDC Credential Issuer when creating the credential.

Common terms

Below is a list of the standard OIDC claims and their JSON-LD equivalent terms from https://schema.org.

These mappings can be pasted into the payload when setting up an OIDC Credential Issuer. Ensure that https://schema.org is used as the context.

json
Copy to clipboard.
1"claimMappings": [
2        {
3            "oidcClaim": "given_name",
4            "jsonLdTerm": "givenName"
5        },
6        {
7            "oidcClaim": "family_name",
8            "jsonLdTerm": "familyName"
9        },
10        {
11            "oidcClaim": "name",
12            "jsonLdTerm": "name"
13        },
14        {
15            "oidcClaim": "nickname",
16            "jsonLdTerm": "alternateName"
17        },
18        {
19            "oidcClaim": "picture",
20            "jsonLdTerm": "image"
21        },
22        {
23            "oidcClaim": "profile",
24            "jsonLdTerm": "mainEntityOfPage"
25        },
26        {
27            "oidcClaim": "email",
28            "jsonLdTerm": "email"
29        },
30        {
31            "oidcClaim": "gender",
32            "jsonLdTerm": "gender"
33        },
34        {
35            "oidcClaim": "birthdate",
36            "jsonLdTerm": "birthDate"
37        },
38        {
39            "oidcClaim": "locale",
40            "jsonLdTerm": "knowsLanguage"
41        },
42        {
43            "oidcClaim": "phone_number",
44            "jsonLdTerm": "telephone"
45        }
46    ]

Note: The default OIDC Address claim uses a JSON object. The OIDC Bridge can only accept single-string mappings at this time, if you want to use an address claim then look to implement it as a custom claim. e.g. mattr.global/address

Custom claims

Any other claim in the ID Token can be mapped as long as there is an applicable term available in the context schema.

Currently we only support schema.org as a data vocabulary, please contact us if you wish to explore other options.

The OpenID Connect recommendation is to name-space custom claims so as to avoid any collision with standard claims, current or future.

The oidcClaim value must be an exact match for the claim name in the ID Token, otherwise it will be ignored during credential issuance.

json
Copy to clipboard.
1"claimMappings": [
2        {
3            "oidcClaim": "mattr.global/alumni_of",
4            "jsonLdTerm": "alumniOf"
5        }
6    ]

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