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 thevalue
field, which means it's entirely up to you to provide the correct authorisation details for your claim sources.type
: This example usesapi-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 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 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.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
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.