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 isapi-key
. We recommend protecting your claims source using authentication control to protect against unauthorised access. MATTR VII currently supports authentication based onapi-key
for claim sources. The api key will be passed asx-api-key
in the request headers. MATTR VII will not validate your inputs for thevalue
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.
email
: Settingemail
as one of therequestParameters
will create the followingGET
requesthttps://api.example.com/myclaims?email=demo@joe.doe
wheredemo@joe.doe
is mapped fromclaims.email
. Theemail
comes from the IdP, and the claim source also hasemail
as a data attribute.userType
: SettinguserType.defaultValue
tostudent
without settinguserType.mapFrom
will query your claim source with a static attributeuserType=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.