Configure a claims source 

This tutorial explains how to configure a claims source on your MATTR VII tenant, and what kind of requests will be made to that claims source when new credentials are issued.

This process is slightly different depending on your configured authorisation method, so the following options are described:

You can also configure your claims source via our Self service portal.

API Key

Request

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

http
Copy to clipboard.
1POST https://YOUR_TENANT_URL/v1/claimsources
json
Copy to clipboard.
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: Claims source name.

  • url: Claims source URL:

    • Must be a valid URL.

    • Must use the HTTPS protocol.

    • Must not be an IP address.

    • Must not include query parameters.

  • authorization: API Key to access the claims source.

    • type: This example uses api-key to authenticate with this claim source.

    • value: API key value. Note that MATTR VII does not validate your input, which means it's up to you to provide the correct API key for your claim sources.

  • requestMethod: Indicates the request method MATTR VII will use when retrieving data from this claims source. Both the GET and POST method are supported. If no value is provided, GET is used by default.

  • requestParameters: Insert request parameters to be used to query your claims source for specific data. This example uses the following parameters:

    • 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

json
Copy to clipboard.
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 is used when you create a credential configuration that uses this claims source, or to retrieve, update and/or remove 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 request during an issuance flow:

http
Copy to clipboard.
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:

http
Copy to clipboard.
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

json
Copy to clipboard.
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 as configured 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, with two notable differences:

  • The authorization object should include different elements which are required for OAuth authentication. Refer to the Overview page for more information.

  • MATTR VII will validate the data provided in the authorization object by fetching an access token and verifying it follows the OAuth 2 standard. This means that you must always provide valid authentication credentials in this object, even for prototyping/testing etc.

Requesting an Access Token

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

Request using

http
Copy to clipboard.
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

Request using

http
Copy to clipboard.
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

Request

Both requests should result in the same expected response:

json
Copy to clipboard.
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:

Request using

http
Copy to clipboard.
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

Request using

http
Copy to clipboard.
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" }

For both methods the response would be similar to the one described above.

What's Next?

Now that you have your claims source configured, you can configure an interaction hook as part of your OpenId4VCI issuance workflow.

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