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 authorisation method.

Request

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

HTTP

POST /v1/claim-sources

Request body

JSON

{
    "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 uses api-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 the mapFrom method to pass the claims.email property as a request parameter. If no email exists for the user, the email request parameter will be passed as unknown which is the defined defaultValue.
- userType : Uses the defaultValue method to always pass student as the userType request parameter.
- credentialProfile : Uses the mapFrom method to pass the credentialConfiguration.profile value as the credentialProfile request parameter.

Response

JSON

{
    "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 :

HTTP Request (GET)

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:

HTTP Request (POST)

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 the claims.email property).
userType : student (static request parameter).
credentialProfile : web-semantic (retrieved from the credentialProfile.profile property).

Response

Both requests should result in the same expected response:

JSON

{
    "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.

Interaction hook Credential configuration