Learn

Create an authentication provider configuration

Overview

An authentication or identity provider (IdP) is a platform that is typically used to store and manage user accounts on behalf of an organisation or a service provider. MATTR VII uses the authentication provider to authenticate end users before issuing them credentials.

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 our Self service portal.

Prerequisite

  • You will need an existing Identity Provider (IdP) that exposes an OpenID Connect-based interface populated with users who can issued verifiable credentials. See our tutorial if you need help in setting up your IdP.

  • Your IdP should let you create application clients, and these clients credentials will be used by MATTR VII to generate the authentication requests when issuing credentials.

Request

Make the following request to create an authentication provider configuration:

http
Copy to clipboard.
1POST https://YOUR_TENANT_URL/v1/users/authenticationproviders
json
Copy to clipboard.
1{
2    "url": "https://YOUR_AUTH_PROVIDER_URL",
3    "scope": [
4        "openid"
5    ],
6    "clientId": "YOUR_CLIENT_ID",
7    "clientSecret": "YOUR_CLIENT_SECRET",
8    "tokenEndpointAuthMethod": "client_secret_post",
9    "staticRequestParameters": {
10        "prompt": "login",
11        "maxAge": 10000
12    },
13    "forwardedRequestParameters": [
14        "login_hint"
15    ],
16    "claimsToPersist": []
17}

  • url: The URL of your IdP:

    • Must be a valid URL.

    • Must use the HTTPS protocol.

    • Must not be an IP address.

    • Must not include query parameters.

  • scope: 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 IdP.

  • clientSecret: The client secret of the application client created on your IdP.

  • tokenEndpointAuthMethod: Authentication method for your IdP 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 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 IdP 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 IdP 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. IdP 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
Copy to clipboard.
1{
2    "id": "983c0a86-204f-4431-9371-f5a22e506599",
3    "redirectUrl": "https://YOUR_TENANT_SUBDOMAIN/core/v1/oauth/authentication/callback",
4    "url": "https://YOUR_AUTH_PROVIDER_URL",
5    "scope": [
6        "openid"
7    ],
8    "clientId": "YOUR_CLIENT_ID",
9    "clientSecret": "YOUR_CLIENT_SECRET", //masked
10    "tokenEndpointAuthMethod": "client_secret_post",
11    "staticRequestParameters": {
12        "prompt": "login",
13        "maxAge": 10000
14    },
15    "forwardedRequestParameters": [
16        "login_hint"
17    ],
18    "claimsToPersist": []
19}

  • id: Unique identifier for the configured authentication provider. This identifier can be used to retrieve, update or remove the authentication provider configuration.

  • redirectUrl: You will need to add this URL to your IdP's allowlist/whitelist. This will enable it to redirect the user back to the wallet upon successful authentication with your IdP. If you are using Auth0 as your identity provider, this guide shows how to add callback URLs. For others, consult your provider for instructions on adding callback URLs.

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

What's next?

Now that you have your authentication provider configuration, you can configure an interaction hook and/or a claims source as part of your OpenId4VCI issuance workflow.

If your use case does not require an interaction hook or a claims source, you can proceed to create a credential configuration.