Configure a claims source 

Our OpenID Credential Provisioning capability can utilise claims from an IdP, interaction hook or an external claims source.

In some cases, systems of record may not be integrated with an IdP and instead may have standalone databases that need to be interfaced with directly. 

MATTR VII claims source integration will allow users to configure their MATTR VII tenant to fetch claims directly from a compatible claims source and issue credentials with them.

This guide describes configuring a connection to an existing claims source.  

Adding a claims source 

The following is an example request to create a new claims source, which can be used to fetch claims for issuing credentials. The claim source in this example implements an API key authentication to access its resources and fetch claims for a specific user. MATTR VII will make a GET request to the API you provide with any requested parameters that are configured.

To retrieve data from your api, you need to add some data attributes about the user you want to get in the query. For this tutorial, the email of a user was added via the identity provider from the authentication step. We can use that email to query the data source. In this example, there are two parameters but you can forward any claims needed for your business logic from MATTR VII provided they have been synced from the IdP. These attributes are available via the claims object.

Request

1POST https://YOUR_TENANT_URL/v1/claimsources

1{
2  "name": "YOUR_CLAIM_SOURCE_NAME",
3  "url": "https://api.example.com/myclaims",
4  "authorization": {
5    "type": "api-key",
6    "value": "<string>"
7  },
8  "requestParameters": {
9    "email": {
10      "mapFrom": "claims.email"
11    },
12    "userType": {
13      "defaultValue": "student"
14    }
15  }
16}

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

• url: The URL of the claims source.  

• name: Name for the claims source.  

• authorization: Authorisation details for the claims source. In this example, the authorisation type is api-key. We recommend protecting your claims source using authentication control to protect against unauthorised access. MATTR VII currently supports authentication based on api-key for claim sources. The api key will be passed as x-api-key in the request headers. MATTR VII will not validate your inputs for the value field, which means it's entirely up to you to provide the correct authorisation details for your claim sources.

• requestParameters: This is where you map claims to query parameters.

1. email: Setting email as one of the requestParameters will create the following GET request https://api.example.com/myclaims?email=demo@joe.doe where demo@joe.doe is mapped from claims.email. The email comes from the IdP, and the claim source also has email as a data attribute.

2. userType: Setting userType.defaultValue to student without setting userType.mapFrom will query your claim source with a static attribute userType=student .

During an issuance flow, MATTR VII will make an API call to GET https://api.example.com/myclaims?email=demo@joe.doe&userType=student using x-api-key in the request headers.

Response

In response, a unique identifier for the configured claims source is returned. This can be used to interact (view, edit or delete) with the configured claims source later.

1{
2   "id":"945214ad-3635-4aff-b51d-61d69a3c8eee",
3   "name":"YOUR_CLAIM_SOURCE_NAME",
4   "url":"https://api.example.com/myclaims",
5   "authorization":{
6      "type":"api-key",
7      "value":"ANY_VALUE"
8   },
9   "requestParameters":{
10      "email":{
11         "mapFrom":"claims.email"
12      },
13      "userType":{
14         "defaultValue":"student"
15      }
16   }
17}

Claim source responses

Your claim source is required to respond to a valid GET request with a JSON object containing any claims you wish to pass to VII. The root of the JSON object should contain a key-value pair with all the data and the response HTTP status should be 200 OK.

Note: Your claim source needs to respond to the GET request within 3 seconds to avoid a timeout

Request

1GET https://example.com/myclaims?userId=1001  
2  Headers:
3    x-api-key: 2e972131302b4ba28d978c901390a995  
4    x-request-id: 114e7db8-0ca2-4396-b966-70124f4eeefa  

The x-api-key header is used as an authentication mechanism to ensure that only authorised clients can access this endpoint. When MATTR VII makes a request to the claims source it will include the configured API key in the request header x-api-key. 

This is format of what the claims server should return:

1{  
2  "firstName": "John",  
3  "lastName": "Jones"  
4}  

If your data has nested values, here's how you could configure claimMappings:

Example response from your claim server:

1{
2  "user": {
3    "firstName": "John",
4    "lastName": "Jones"  
5  },
6  "account": {
7    "type": "admin",
8    "team": "managers"
9  }
10}

Your mapping:

1{
2  "requestParameters": {
3    "firstName": {
4      "mapFrom": "claims.user.firstName"
5    },
6    "lastName": {
7      "mapFrom": "claims.user.lastName"
8    },
9    "accountType": {
10      "mapFrom": "claims.account.type"
11    },
12    "team": {
13      "mapFrom": "claims.account.team"
14    }
15  }
16}

If there are no claims to return for a user, your server should return an empty json object with a 200 OK status.