Authentication provider

Overview

An authentication or identity provider (IdP) is a platform used to store and manage user accounts. MATTR VII uses auth providers to authenticate users before issuing them credentials as part of the OID4VCI Authorization Code flow.

To configure a MATTR VII Authentication provider you will need an existing provider that exposes an OpenID Connect-based interface, populated with users who can be issued verifiable credentials. Your provider should allow creating application clients, which will be used by MATTR VII to generate the authentication requests when issuing credentials.

Alongside authentication, you can configure MATTR VII to query your provider for different scopes of claims that can be retrieved and used as part of the OID4VCI Authorization Code flow. Available scopes depend on your provider and its configuration. See Auth0 supported scopes as an example.

Requirements

You can use any OpenID provider if it supports the following capabilities specified by OpenID Connect Core and OpenID Connect Discovery:

• Must publish its OpenID Provider configuration at /.well-known/openid-configuration
• Must support Authorization Code flow
• Must support the state parameter

These requirements allow the OID4VCI Authorization Code flow to engage with your Authentication provider and accept an ID Token containing the user claims.

Ensuring claim availability

When using the Authorization Code flow, the claims available for inclusion in the issued credential are determined by data returned by your Authentication provider and (if configured) your Interaction hook and/or Claims source.

A common cause of issuance failures is a mismatch between the claims expected by your Credential configuration and the claims your Authentication provider actually supplies.

To avoid this, it is important to understand the relationship between scopes and claims, and to verify that your provider can return the claims your credential configuration requires.

Scopes and claims

In OpenID Connect, claims are the individual pieces of information about a user (e.g. given_name, email, birthdate). Scopes are high-level permissions that a client requests to gain access to categories of claims. The standard claim name in OIDC discovery for date of birth is birthdate (no underscore); you can later map this provider claim into a different credential claim name (for example, mapping OIDC birthdate to a credential claim birth_date) using claim mappings in your credential configuration.

The OIDC specification defines recommended mappings between scopes and claims. For example:

However, these mappings are not guaranteed. Your Authentication provider ultimately decides which claims are returned based on:

• The scopes requested by the client.
• The provider's own configuration and custom mappings.
• Whether the user's profile actually contains values for those claims.

For example, requesting the profile scope does not guarantee that given_name will be returned. The user's profile must have a value for that field, and the provider must be configured to include it in the response.

Checking your provider's supported claims

Every OIDC-compliant provider publishes a discovery document at /.well-known/openid-configuration. This document includes two key fields for understanding claim availability:

• claims_supported: Typically lists the specific claims the provider can return. This list may not be exhaustive, and additional claims may still be returned depending on your provider's configuration and custom mappings.
• scopes_supported: Typically lists the scopes the provider accepts. Scopes that are not listed here may be ignored or rejected, but behaviour can vary across providers, so you should validate supported scopes by testing your integration (for example, by inspecting issued tokens and UserInfo responses).

For example, a provider's discovery document might list:

{
  "claims_supported": [
    "sub", "name", "given_name", "family_name",
    "email", "email_verified", "picture"
  ],
  "scopes_supported": [
    "openid", "profile", "email", "address"
  ]
}

In this case, standard identity claims like given_name and email are supported. However, the standard OIDC claim birthdate is not listed in claims_supported, so the provider will not return it unless it is explicitly configured as a supported claim. Custom claim names (for example, employee_id) are provider-specific and will not appear in claims_supported unless your provider is configured to expose them.

Verifying claims for your credential configuration

Before creating a credential configuration that relies on claims from your Authentication provider, follow these steps:

1. Review your provider's discovery document: Fetch the /.well-known/openid-configuration endpoint and check claims_supported against the claims your credential configuration requires.
2. Confirm scope configuration: Ensure the MATTR VII Authentication provider configuration requests the scopes needed to access those claims (e.g. profile for given_name, email for email).
3. Check user profile data: Verify that the user accounts in your provider have values populated for the required claims. Even supported claims will not be returned if the user's profile is missing that data.
4. Handle unsupported provider claims and credential-only fields: For claims that are not listed in claims_supported but you still want as OIDC claims (e.g. the standard birthdate claim), or for credential-specific fields that are not expected to come from your Authentication provider (e.g. an expiry_date field on the credential), consider the following options:
   • For provider claims, add them to your provider as custom claims using provider-specific features (e.g. Auth0 Actions or Rules) so they can appear in ID tokens or the UserInfo response.
   • For credential-only fields, use a Claims source or an Interaction hook to supply additional attributes from your own data, rather than expecting them from the Authentication provider.
   • Set a defaultValue in the credential configuration so issuance can succeed even when the claim is not provided by the provider or any other source.

Request parameters

You can configure MATTR VII to include request parameters when the holder is redirected to the Authentication provider:

• Static request parameters are included in the request to your IdP, and will be identical for every request as defined in your configuration. An example would be setting the prompt to be login to let your Authentication provider know it should show the login page every time.
  • Keys must be strings.
  • Values of top-level object keys must stringify to less than 1000 characters.
• Dynamic request parameters are fetched uniquely for each request to make the user journey more seamless. Here, you can forward params to your Authentication provider like login_hint which will pass the email of the user starting the flow.
  • Dynamic parameters values are limited to 1000 characters each.

Persisting claims

Upon successful authentication the provider responds with an ID token. You can configure MATTR VII to persist selected claims on your tenant.