Learn

Authentication Provider

Configure an Authentication Provider

Configures an Authentication Provider on the tenant.

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.

Only one authentication provider can be configured on a tenant.

The /.well-known/openid-configuration endpoint of the Authentication Provider must contain values for the authorization_endpoint, token_endpoint and scopes_supported.

Analytic events

  • USER_AUTHENTICATION_PROVIDER_CREATE_START
  • USER_AUTHENTICATION_PROVIDER_CREATE_SUCCESS
  • USER_AUTHENTICATION_PROVIDER_CREATE_FAIL
SecuritybearerAuth
Request
Request Body schema: application/json
required

The Authentication Provider payload

url
required
string <uri>

Base url for your Authentication Provider well-known endpoint:

  • Must be a valid URL.
  • Must use the HTTPS protocol.
  • Must not be an IP address.
  • Must not contain query parameters. Port and fragment parameters will be dropped.
  • URL must use https and have a valid public TLD.
  • Unicode will be converted to ASCII.
scope
Array of strings
Default: ["openid","profile","email"]

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
required
string

The client ID of the application client created on your IdP.

clientSecret
required
string

The client secret of the application client created on your IdP.

tokenEndpointAuthMethod
string
Default: "client_secret_basic"

Authentication method for your IdP token endpoint:

  • client_secret_post: Your credentials are passed as parameters in the request body.
  • client_secret_basic (default): Your credentials are passed as a base 64 encoded token.
Enum: "client_secret_basic" "client_secret_post"
object <= 1000 properties

Additional parameters (maximum 1000 entries allowed) that will be included in the request to your IdP. These parameters are 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
Array of strings
Default: []

In contrast to staticRequestParameters, you can provide dynamic parameters that are fetched uniquely for each request to make the user journey more seamless. You can forward params to your IdP like login_hint which will pass the email of the user starting the flow. Values are limited to 1000 characters each, and cannot override any core Authorize Parameters.

claimsToPersist
Array of strings
Default: []

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.

Responses
201

Authentication Provider configured

400

Bad Request

post/core/v1/users/authentication-providers
Request samples
application/json
{
  • "url": "https://example-university.au.auth0.com",
  • "scope": [
    ],
  • "clientId": "vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN",
  • "clientSecret": "QNwfa4Yi4Im9zy1u_15n7SzWKt-9G5cdH0r1bONRpUPfN-UIRaaXv_90z8V6-OjH",
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "staticRequestParameters": {
    },
  • "forwardedRequestParameters": [
    ],
  • "claimsToPersist": [
    ]
}
Response samples
application/json
{
  • "id": "983c0a86-204f-4431-9371-f5a22e506599",
  • "redirectUrl": "https://tenant.vii.mattr.global/core/v1/oauth/authentication/callback",
  • "url": "http://example.com",
  • "scope": [
    ],
  • "clientId": "vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN",
  • "clientSecret": "***********************************************************6-OjH",
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "staticRequestParameters": {
    },
  • "forwardedRequestParameters": [
    ],
  • "claimsToPersist": [
    ]
}

Retrieve all Authentication Providers

Returns a list of all Authentication Providers on your tenant.

Analytic events

  • USER_AUTHENTICATION_PROVIDER_RETRIEVE_LIST_START
  • USER_AUTHENTICATION_PROVIDER_RETRIEVE_LIST_SUCCESS
  • USER_AUTHENTICATION_PROVIDER_RETRIEVE_LIST_FAIL
SecuritybearerAuth
Request
query Parameters
limit
number [ 1 .. 1000 ]

Range size of returned entries, default 100

Example: limit=2
cursor
string

Starting point for the range of entries

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h
Responses
200

Authentication Providers retrieved

400

Bad Request

get/core/v1/users/authentication-providers
Request samples 
Response samples 
application/json
{
  • "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM",
  • "data": [
    ]
}
Retrieve an Authentication Provider
Retrieve an existing Authentication Provider by providing its ID.


Analytic events


    

  • USER_AUTHENTICATION_PROVIDER_RETRIEVE_START
    • 

  • USER_AUTHENTICATION_PROVIDER_RETRIEVE_SUCCESS
    • 

  • USER_AUTHENTICATION_PROVIDER_RETRIEVE_FAIL
    • 



SecuritybearerAuth 
Request 
path Parameters
id
required
string <uuid> 
Authentication Provider ID


 
 Example:  41458e5a-9092-40b7-9a26-d4eb43c5792f
Responses 
200
Authentication Provider retrieved


400
Bad Request


404
Authentication Provider not found


get/core/v1/users/authentication-providers/{id}
Request samples 
Response samples 
application/json
{
  • "id": "983c0a86-204f-4431-9371-f5a22e506599",
  • "redirectUrl": "https://tenant.vii.mattr.global/core/v1/oauth/authentication/callback",
  • "url": "http://example.com",
  • "scope": [
    ],
  • "clientId": "vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN",
  • "clientSecret": "***********************************************************6-OjH",
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "staticRequestParameters": {
    },
  • "forwardedRequestParameters": [
    ],
  • "claimsToPersist": [
    ]
}
Update an Authentication Provider
Updates an existing Authentication Provider by providing its ID.


Analytic events


    

  • USER_AUTHENTICATION_PROVIDER_UPDATE_START
    • 

  • USER_AUTHENTICATION_PROVIDER_UPDATE_SUCCESS
    • 

  • USER_AUTHENTICATION_PROVIDER_UPDATE_FAIL
    • 



SecuritybearerAuth 
Request 
path Parameters
id
required
string <uuid> 
Authentication Provider ID


 
 Example:  41458e5a-9092-40b7-9a26-d4eb43c5792f
Request Body schema: application/json
required
Update an Authentication Provider


scope
Array of strings
 Default:  ["openid","profile","email"]
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
required
string
The client ID of the application client created on your IdP.


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


 
tokenEndpointAuthMethod
string
 Default:  "client_secret_basic"
Authentication method for your IdP token endpoint:


    

  • client_secret_post: Your credentials are passed as parameters in the request body.
    • 

  • client_secret_basic (default): Your credentials are passed as a base 64 encoded token.
    • 



 Enum: "client_secret_basic" "client_secret_post"  
object  <= 1000 properties 
Additional parameters (maximum 1000 entries allowed) that will be included in the request to your IdP. These parameters are 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
Array of strings
 Default:  []
In contrast to staticRequestParameters, you can provide dynamic parameters that are fetched uniquely for each request to make the user journey more seamless. You can forward params to your IdP like login_hint which will pass the email of the user starting the flow. Values are limited to 1000 characters each, and cannot override any core Authorize Parameters.


 
claimsToPersist
Array of strings
 Default:  []
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.


 
Responses 
200
Authentication Provider updated


400
Bad Request


404
Authentication Provider not found


put/core/v1/users/authentication-providers/{id}
Request samples 
application/json
{
  • "scope": [
    ],
  • "clientId": "vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN",
  • "clientSecret": "QNwfa4Yi4Im9zy1u_15n7SzWKt-9G5cdH0r1bONRpUPfN-UIRaaXv_90z8V6-OjH",
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "staticRequestParameters": {
    },
  • "forwardedRequestParameters": [
    ],
  • "claimsToPersist": [
    ]
}
Response samples 
application/json
{
  • "id": "983c0a86-204f-4431-9371-f5a22e506599",
  • "redirectUrl": "https://tenant.vii.mattr.global/core/v1/oauth/authentication/callback",
  • "url": "http://example.com",
  • "scope": [
    ],
  • "clientId": "vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN",
  • "clientSecret": "***********************************************************6-OjH",
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "staticRequestParameters": {
    },
  • "forwardedRequestParameters": [
    ],
  • "claimsToPersist": [
    ]
}
Delete an Authentication Provider
Deletes an existing Authentication Provider by providing its ID.


Analytic events


    

  • USER_AUTHENTICATION_PROVIDER_DELETE_START
    • 

  • USER_AUTHENTICATION_PROVIDER_DELETE_SUCCESS
    • 

  • USER_AUTHENTICATION_PROVIDER_DELETE_FAIL
    • 



SecuritybearerAuth 
Request 
path Parameters
id
required
string <uuid> 
Authentication Provider ID


 
 Example:  41458e5a-9092-40b7-9a26-d4eb43c5792f
Responses 
204
Authentication Provider deleted


400
Bad Request


404
Authentication Provider not found


delete/core/v1/users/authentication-providers/{id}
Request samples 
Response samples 
application/json
{
  • "code": "BadRequest",
  • "message": "Validation Error",
  • "details": [
    ]
}
➔ Next to Interaction Hook