How to create an Authentication provider configuration

An authentication provider (sometimes referred to as an Identity Provider, or IdP) is a platform typically used to store and manage user accounts on behalf of an organisation or a service provider. MATTR VII uses the configured authentication provider to authenticate end users before issuing them credentials via the OID4VCI workflow.

As part of configuring your OpenID4VCI issuance workflow, you will need to create an authentication provider configuration on your MATTR VII tenant.

You can also configure your Authentication provider via the MATTR Self Service Portal.

Prerequisites

An existing Authentication provider that:
- Exposes an OpenID Connect-based interface.
- Is populated with users who can be issued verifiable credentials.
- Is configured with application clients for which you hold the login credentials.

Overview

Creating an Authentication provider configuration comprises the following steps:

Create a MATTR VII Authentication provider configuration.
Update your Authentication provider callback URL.

Create a MATTR VII Authentication provider configuration

Request

Make a request of the following structure to create an Authentication provider configuration:

HTTP

POST /v1/users/authentication-providers

Request body

JSON

{
    "url": "https://example.us.auth0.com/",
    "scope": ["openid"],
    "clientId": "zH1IGGkRo6q0ofwiNJnlY0bg9fchw3s0",
    "clientSecret": "***********************************************************LFRrZ",
    "tokenEndpointAuthMethod": "client_secret_post",
    "staticRequestParameters": {
        "prompt": "login",
        "maxAge": 10000
    },
    "forwardedRequestParameters": ["login_hint"],
    "claimsToPersist": []
}

url : The URL of your Authentication provider:
- Must be a valid URL.
- Must use the HTTPS protocol.
- Must not be an IP address.
- Must not include query parameters.
scope (optional): OpenID scopes to use during authentication. Each scope returns a set of user attributes which are called claims. Be sure to test that right scopes are added to get all the information you need.
clientId : The client ID of the application client created on your Authentication provider.
clientSecret : The client secret of the application client created on your Authentication provider.
tokenEndpointAuthMethod : Authentication method for your Authentication provider token endpoint. The following methods are supported:
client_secret_post : Your credentials are passed as parameters in the request body.
client_secret_basic : Your credentials are passed as a base 64 encoded token.
staticRequestParameters (optional): Additional parameters that will be included in the request to your Authentication provider, 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.
forwardedRequestParameters (optional): In contrast to staticRequestParameters, you can provide dynamic parameters that 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. Forwarded parameters values are limited to 1000 characters each.
claimsToPersist (optional): List of claims to persist from your Authentication provider to MATTR VII. If you have attributes from the ID token (e.g. email, picture, etc.) that you would like persisted on MATTR VII, add them to this array. By default this array is empty, meaning no claims are persisted on MATTR VII.

Response

JSON

{
    "id": "983c0a86-204f-4431-9371-f5a22e506599",
    "redirectUrl": "https://learn.vii.au01.mattr.global/core/v1/oauth/authentication/callback",
    "url": "https://example.us.auth0.com/",
    "scope": ["openid"],
    "clientId": "zH1IGGkRo6q0ofwiNJnlY0bg9fchw3s0",
    "clientSecret": "***********************************************************LFRrZ", //masked
    "tokenEndpointAuthMethod": "client_secret_post",
    "staticRequestParameters": {
        "prompt": "login",
        "maxAge": 10000
    },
    "forwardedRequestParameters": ["login_hint"],
    "claimsToPersist": []
}

id : Unique identifier for the configured Authentication provider. This identifier can be used to retrieve, update or remove the Authentication provider configuration.
redirectUrl : This is the URL the user should be redirected to upon successful authentication to continue the OID4VCI workflow. You will add it to to your Authentication provider’s allowlist/whitelist in the next step.
clientSecret : Your authentication provider client secret will be masked in the response without revealing the actual secret. If the secret is less than 20 characters it will be completely masked, and if it is over 20 only the last 5 characters are revealed.

Update your Authentication provider callback URL

Add the redirectUrl from the response above to your Authentication provider’s allowlist/whitelist of callback URLs:

If you are using Auth0 as your Authentication provider, this guide shows how to add callback URLs.
If you are using a different authentication provider, consult their documentation for instructions on adding callback URLs.

Tutorial 🎓Interaction hook