How to configure and use a Claims source
As part of an OpenID4VCI issuance workflow, you can configure your tenant to fetch claims directly from a compatible Claims source and use these claims when issuing verifiable credentials.
You can also configure your Claims source via the MATTR Self Service Portal.
Prerequisites
- Database configured with an interface layer to support incoming requests:
- Must be accessible from the internet via HTTPS (e.g.
https://example.com
). - Must expose an endpoint supporting a HTTPS request using either GET or POST methods. This endpoint is what MATTR VII will call when querying the data source.
- Must conform to the following response criteria:
- Return a response within three seconds to avoid request timeout.
- Return a 2XX HTTP status code when the request was successful.
- Response body must be a valid JSON, denoted by the application/json MIME type.
- Each key in the JSON object must be a claim name and each value must be a claim value.
- If no claims are found, an empty object should be returned in the response body.
- Respond with error codes only when something exceptional happens. MATTR VII will log the error, but issuance will only fail when it does not meet an explicit credential configuration requirement (e.g., when no value for a required claim is available).
Overview
Configure and using a Claims source as part of an OID4VCI workflow comprises the following steps:
Configure a MATTR VII Claims source
The request structure would vary based on your preferred authorization method.
Request
Make a request of the following structure to configure a new claims source that is accessed using an API key:
POST /v1/claim-sources
Request body
{
"name": "My Claims source",
"url": "https://api.example.com/myclaims",
"authorization": {
"type": "api-key",
"value": "*************************0a995"
},
"requestMethod": "GET",
"requestParameters": {
"email": {
"mapFrom": "claims.email",
"defaultValue": "Unknown"
},
"userType": {
"defaultValue": "student"
},
"credentialProfile": {
"mapFrom": "credentialConfiguration.profile"
}
}
}
name
: Meaningful name for the configured Claims source.url
: Claims source URL (and any redirects it may include):- Must be a valid URL.
- Must use the HTTPS protocol.
- Must not be an IP address.
- Must not include query parameters.
authorization
: Details how to access the Claims source.type
: This example usesapi-key
to authenticate with this claim source.value
: API key value. MATTR VII does not validate this input and it is up to you to provide a 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 that can be used to query your database. This example uses the following parameters:email
: Uses themapFrom
method to pass theclaims.email
property as a request parameter. If noemail
exists for the user, theemail
request parameter will be passed asunknown
which is the defineddefaultValue
.userType
: Uses thedefaultValue
method to always passstudent
as theuserType
request parameter.credentialProfile
: Uses themapFrom
method to pass thecredentialConfiguration.profile
value as thecredentialProfile
request parameter.
Response
{
"id": "945214ad-3635-4aff-b51d-61d69a3c8eee",
"name": "YOUR_CLAIM_SOURCE_NAME",
"url": "https://api.example.com/myclaims",
"authorization": {
"type": "api-key",
"value": "*************************0a995"
},
"requestMethod": "GET",
"requestParameters": {
"email": {
"mapFrom": "claims.email"
},
"userType": {
"defaultValue": "student"
},
"credentialProfile": {
"mapFrom": "credentialConfiguration.profile"
}
}
}
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.
Query the Claims source
Once the Claims source is configured, MATTR VII will query it using the configured authentication method as part of the OID4VCI workflow.
This query is performed automatically by MATTR VII. It is only described here to provide clarity.
Request
MATTR VII will make one of the following requests to query the configured Claims source based on the
set requestMethod
:
GET https://api.example.com/myclaims?email=john@example.com&userType=student&credentialProfile=web-semantic
Headers:
x-api-key: *************************0a995 
x-request-id: 52tg0VFqRR6FjFsGB8CBhm
When the requestMethod is set to POST
, that same request would look as follows:
POST https://api.example.com/myclaims
Headers:
x-api-key: *************************0a995 
x-request-id: 52tg0VFqRR6FjFsGB8CBhm
content-type: application/json
Body:
{ "email": "john@example.com", "userType": "student", "credentialProfile": "web-semantic" }
Based on the configured request parameters, this query will fetch data for users that match the following criteria:
email
:john@example.com
(retrieved from theclaims.email
property).userType
: student (static request parameter).credentialProfile
: web-semantic (retrieved from thecredentialProfile.profile
property).
Response
Both requests should result in the same expected response:
{
"user": {
"firstName": "John",
"lastName": "Jones"
},
"account": {
"type": "admin",
"team": "managers"
}
}
These claims are then added to the claims object and can be mapped to credential claims when you create a credential configuration.