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:
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
: 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 usesapi-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 themapFrom
method. In this example MATTR VII will query the claims source for a user with anemail
attribute that matches theclaims.email
value.userType
: Uses thedefaultValue
method. In this example MATTR VII will query the claims source for users that havestudent
as auserType
attribute.credentialProfile
: Uses themapFrom
method. In this example MATTR VII will only fetch data that is mapped to credentials that match thecredentialConfiguration.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 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:
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.comuserType
: studentcredentialProfile
: 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
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
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
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:
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
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
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.