Skip to main content

Common OIDC to Credential Claim mappings

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.

"claimMappings": [
        {
            "oidcClaim": "given_name",
            "jsonLdTerm": "givenName"
        },
        {
            "oidcClaim": "family_name",
            "jsonLdTerm": "familyName"
        },
        {
            "oidcClaim": "name",
            "jsonLdTerm": "name"
        },
        {
            "oidcClaim": "nickname",
            "jsonLdTerm": "alternateName"
        },
        {
            "oidcClaim": "picture",
            "jsonLdTerm": "image"
        },
        {
            "oidcClaim": "profile",
            "jsonLdTerm": "mainEntityOfPage"
        },
        {
            "oidcClaim": "email",
            "jsonLdTerm": "email"
        },
        {
            "oidcClaim": "gender",
            "jsonLdTerm": "gender"
        },
        {
            "oidcClaim": "birthdate",
            "jsonLdTerm": "birthDate"
        },
        {
            "oidcClaim": "locale",
            "jsonLdTerm": "knowsLanguage"
        },
        {
            "oidcClaim": "phone_number",
            "jsonLdTerm": "telephone"
        }
    ]
tip

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. sovrin.one/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.

tip

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.

"claimMappings": [
        {
            "oidcClaim": "sovrin.one/alumni_of",
            "jsonLdTerm": "alumniOf"
        }
    ]
tip

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