Configure an authentication provider

An authentication or identity provider (IdP) is a platform that is typically used to store and manage user accounts on behalf of an organization or service provider. In this instance, we will use the authentication provider to authenticate end users before issuing them credentials.

Use the following steps to add an authentication provider. Once set up, MATTR VII will federate to your IdP to handle user authentication during a credential offer/issuance flow.  

 Prerequisites  

• Before continuing, you will need an IdP that exposes an OpenID Connect-based interface populated with users who can be subjects of issued credentials. See our tutorial on configuring an IdP.

Warning: It is NOT recommended to use the ID token as the primary source of claims as the claims retrieved from the authentication provider are stored by the platform to aid linking via interaction hooks.

Any PII that is contained in the ID Token, could be stored and as such may breach the terms of your agreement. Please contact us for further information.

Your identity provider should let you create a application clients for use with your provider. The credentials provided for the app will be used by MATTR VII to generate the authorization request.

To configure an authentication provider, make the following POST request. You can also look up the API reference for adding an authentication provider.

Request

1POST https://YOUR_TENANT_URL/v1/users/authenticationproviders

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  "claimsSource": "idToken",
10  "staticRequestParameters": {
11    "prompt": "login",
12    "maxAge": 10000
13  },
14  "forwardedRequestParameters": [
15    "login_hint"
16  ],
17  "claimsToSync": []
18}

Here's what each field of the request payload means: 

• url: The URL of the authentication provider.  

• scope: OpenID scopes to use during authentication to authorize access to a user's details. Each scope returns a set of user attributes, which are called claims. Be sure to test that right scopes are added to pass all the information you need.

• clientId: The client ID of the application created to be used with your identity provider.

• clientSecret: The client secret for the app used with your authentication provider.

• tokenEndpointAuthMethod: Authentication method for the authentication provider's token endpoint. Check the API reference for more supported values.

• claimsSource: The method of obtaining claims from the authentication provider. "idToken" retrieves data using the token endpoint whereas setting the value to "userInfo" gets attributes from the userinfo endpoint.

• staticRequestParameters (optional): Additional parameters that will be included in the request to the authentication provider. These parameters are the same for every request and have to be defined within the credential configuration. An example would be setting the "prompt" to be "login" letting the authorization provider know that 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 each.

• forwardedRequestParameters (optional): In contrast to static parameters above, you can provide dynamic params for each issuance flow 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. The forwarded parameter values are limited to under 1000 characters each.

• claimsToSync: List of claims to sync from the authentication provider to MATTR VII. If you have attributes from the ID token (like email, picture, etc) that you would like persisted on VII, add each claim to this array.

Note: Although your IdP can be used as a source of claims for issuing credentials, there is often a limit on the size of the ID token. This could limit the number of claims sourced from an IdP directly or cause the issuance flow to fail.

Response

When the authentication provider is configured successfully, a unique identifier (id) for the configured authentication provider is returned. This identifier can be used to obtain the configuration of the authentication provider later. 

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",
10  "tokenEndpointAuthMethod": "client_secret_post",
11  "claimsSource": "idToken",
12  "staticRequestParameters": {
13    "prompt": "login",
14    "maxAge": 10000
15  },
16  "forwardedRequestParameters": [
17    "login_hint"
18  ],
19  "claimsToSync": []
20}

Important: Don’t forget to add the callback URL to your authentication provider's allow list. This is returned as the redirectUrl in your API response.

For example:

1https://YOUR_TENANT_URL/core/v1/oauth/authentication/callback

This will ensure the redirection of end users from your authentication provider back to the wallet after successful authentication.

If you are using Auth0 as your identity provider, this guide should explain how to add callback URLs. For others, consult your provider for instructions on adding callback URLs.