Configure a claims source 

This tutorial will explain how to configure a new claims source, and what kind of requests will be made to that claims source when new credentials are issued.

This process will be slightly different depending on your chosen authorization method (API Key or OAuth client credentials), so we will show both options.

API Key

Request

Make the following request to create a new claim source that is accessed using an API key:

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": "2e972131302b4ba28d978c901390a995"
7    },
8    "requestMethod": "GET",
9    "requestParameters": {
10        "email": {
11            "mapFrom": "claims.email"
12        },
13        "userType": {
14            "defaultValue": "student"
15        },
16        "credentialProfile": {
17            "mapFrom": "credentialConfiguration.profile"
18        }
19    }
20}

• name: Name for the claims source.  

• url: URL of the claims source.  

• authorization: API Key to access the claims source. Note that MATTR VII does not validate your input for the value field, which means it's entirely up to you to provide the correct authorisation details for your claim sources.

  • type: This example uses api-key as the customer will use an API key to authorize with this claim source.

  • value: API key value.

• requestMethod: Indicates the request method MATTR VII will make when fetching data from this claims source. Both the GET and POST method are supported. If nothing is provided, it defaults to GET.

• requestParameters: These parameters are used to query your claims source for a specific user:

• email: Uses the mapFrom method. In this example MATTR VII will query the claims source for a user with an email attribute that matches the claims.email value.

• userType: Uses the defaultValue method. In this example MATTR VII will query the claims source for users that have student as a userType attribute.

• credentialProfile: Uses the mapFrom method. In this example MATTR VII will only fetch data that is mapped to credentials that match the credentialConfiguration.profile value.

Response

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": "***************************0a995"
8    },
9    "requestMethod": "GET",
10    "requestParameters": {
11        "email": {
12            "mapFrom": "claims.email"
13        },
14        "userType": {
15            "defaultValue": "student"
16        },
17        "credentialProfile": {
18            "mapFrom": "credentialConfiguration.profile"
19        }
20    }
21}

• id: Unique identifier for the configured claims source. This identifier can be used later to manage (view, edit, delete) this claims source.

• authorization.value: The response will mask your API Key. It will be completely masked if it is less than 20 characters, and only expose the last 5 characters if it is 20 characters or longer.

Querying the Claims Source

Request

The created claims source configuration should result in MATTR VII making the following call during an issuance flow:

1GET https://example.com/myclaims?email=john@example.com&userType=student&credentialProfile=web-semantic 
2  Headers:
3    x-api-key: 2e972131302b4ba28d978c901390a995  
4    x-request-id: 52tg0VFqRR6FjFsGB8CBhm

This query will fetch data for the user that matches the following parameters:

• email: john@example.com

• userType: student

• credentialProfile: web-semantic

When the requestMethod is set to POST, that same request would look as follows:

1POST https://example.com/myclaims
2  Headers:
3    x-api-key: 2e972131302b4ba28d978c901390a995 
4    x-request-id: 52tg0VFqRR6FjFsGB8CBhm
5    content-type: application/json
6  Body:
7    { "email": "john@example.com", "userType": "student", "credentialProfile": "web-semantic" }

Response

This is what the response might look like:

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

These claims can now be mapped to the issued credential when you setup a credential configuration.

OAuth client credentials

When using OAuth client credentials to authenticate with your claims source, the request to configure a new claims source would be similar to the one described above.

The only difference is that the authorization object should include different elements which are required for OAuth authorisation. Refer to the Overview page for more information.

Obtaining an Access Token

When querying the claims source using OAuth credentials, MATTR VII will first make a request to obtain an access token, depending on your chosen authentication method (refer to the Overview page for more information):

client_secret_basic

1POST https://example.com/oauth/token
2  Headers:
3    x-request-id: 52tg0VFqRR6FjFsGB8CBhm
4    authorization: Basic base64(clientId:clientSecret)
5    content-type: application/x-www-form-urlencoded
6  Body:
7    grant_type=client_credentials&audience=example.com

client_secret_post

1POST https://example.com/oauth/token
2  Headers:
3    x-request-id: 52tg0VFqRR6FjFsGB8CBhm
4    content-type: application/x-www-form-urlencoded
5  Body:
6    client_id=clientId&client_secret=clientSecret&grant_type=client_credentials&audience=example.com

Both requests should result in the same expected response:

1{
2  "access_token": "<string>",
3  "token_type": "Bearer",
4  "expires_in": 900 // integer in seconds, recommended but not mandatory
5}

Querying the Database

Once an access token is obtained, MATTR VII will make one of the following call to query your claims source, based on your requestMethod:

GET

1GET https://example.com/myclaims?email=john@example.com&userType=student&credentialProfile=web-semantic 
2  Headers:
3    authorization: Bearer access_token
4    x-request-id: 52tg0VFqRR6FjFsGB8CBhm

POST

1POST https://example.com/myclaims
2  Headers:
3    authorization: Bearer access_token
4    x-request-id: 52tg0VFqRR6FjFsGB8CBhm
5    content-type: application/json
6  Body:
7    { "email": "john@example.com", "userType": "student", "credentialProfile": "web-semantic" }

The response would be similar to the one described above.

What's Next?

You can now proceed to setup a credential configuration.