Learn

Claims source

The MATTR VII OpenID4VCI issuance workflow can issue verifiable credentials with claims fetched from an Identity Provider (IdP), interaction hook or any supported claims source.

In some cases, these claim sources are not integrated with the IdP and may have standalone databases that need to be interfaced with directly. To accommodate that, we have added support for retrieving data from a custom claims source via a single API call.

MATTR VII claims source integration allows configuring your tenant to fetch claims directly from a compatible claims source and use these claims when issuing verifiable credentials.

This workflow includes the following steps:

  1. You configure a new claims source. This configuration includes your authorisation credentials for that service, as well as request parameters that can be used to query it when fetching data.

  2. When issuing a new credential, MATTR VII will make either a GET or a POST request to the claims source using the configured request parameters and fetch available data .

  3. This fetched data can now be used when creating the verifiable credentials.

You can currently configure one claims source on your MATTR VII tenant.

You can also configure your claims source via our Self service portal.

Claims source requirements

MATTR VII requires that your claims source meet the following guidelines:

  • 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 claims 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).

Authorisation

We strongly recommend protecting your claims source to prevent unauthorised access.

MATTR VII currently supports two authentication methods:

  • api-key: The provided key is passed as a x-api-key header in all the requests made to the claims source. When using an API key as an authorisation method you must provide your API key for this claims source.

  • oauth-client-credentials: MATTR VII will first use your oauth client credentials to request an access token. Once the token is retrieved, it is used as an Authorization header prefixed by the token type. When using OAuth client credentials as an authorisation method you must provide the following information:

    • tokenEndpoint: URL for obtaining an access token for this claims source.

    • clientId: Your client identifier for this claims source.

    • clientSecret: Your client secret for this claims source.

    • audience: The claims source server.

    • tokenEndpointAuthMethod: Two authentication methods are available:

      • client_secret_basic: Credentials are passed as a base 64 encoded basic token.

      • client_secret_post: Credentials are passed as parameters within the request body.

MATTR VII only supports Bearer access tokens.

Request parameters

Most credentials would only require a subset of the data you have available on your claims source. To accomodate this and avoid retrieving unnecessary data, MATTR VII can pass request parameters that can be used for querying your database. These parameters can be based on any information gathered as part of the issuance journey. This includes both the Authentication provider and/or an Interaction hook component.

Request parameters can be either dynamic or static.

Dynamic request parameters

mapFrom

You can define a dynamic request parameter by using the mapFrom method, and define the path to map the parameter from. The exact path depends on your Authentication provider and Interaction hook configuration that are used to populate the claims object.

To support possible scenarios where mapping fails or evaluated to undefined (attribute doesn't exist) you can provide an optional defaultValue to use as a fallback parameter. This can be a string, an object or an array.

When only providing mapFrom, the request parameter will be mapped from the defined path. If mapping fails, no alternative value is used. When providing both mapFrom and defaultValue, MATTR VII will attempt to map the request parameter from the defined path. If mapping fails, the defaultValue is used instead.

credentialConfiguration

Another way of using dynamic request parameters is to use the credentialConfiguration object. If you construct your external database to support this, you could pass elements of the credentialConfiguration object as request parameters:

  • id: Unique configuration identifier.

  • type: Credential type (configuration type is defined as part of their setup process).

  • profile: Credential profile (configuration profile is defined as part of their setup process). The following options are available:

    • Web Credentials: web-semantic.

    • Compact Credentials: compact.

    • Compact Semantic Credentials: compact-semantic.

    • Mobile Credentials: mobile.

Using the credentialConfiguration object relies on structuring your database in a way that enables filtering queries based on the id, type and profile fields.

Static request parameters

When only providing defaultValue, this value is always used to populate the request parameter, regardless of any available claims values.

What's Next?

You can now proceed to configure a claims source.