Claims source

Issuers databases are not always integrated with their Authentication providers and might require a separate integration into the issuance workflow. Claims sources allow configuring your tenant to use a compatible endpoint to fetch claims and use them in issued credentials.

Your Claims source configuration includes your authorization credentials for that service, as well as request parameters that can be used to query it when fetching data.

Once configured, MATTR VII will make an API request to the claims source using the configured request parameters and fetch available data as part of the issuance workflow. Any retrieved data from the claims source can be used in the issued credential.

Requirements

Any configured claims source must meet the following guidelines:

• Must be accessible from the internet via HTTPS (e.g. https://example.com).
• Must expose an endpoint supporting HTTPS request using either GET or POST. 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).

Authorization

MATTR VII supports two authorization methods to interact with your protected claim sources:

• api-key : The provided key is passed as a x-api-key header in all requests made to the 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 in all requests made to the claims source. MATTR VII only supports Bearer access tokens.

Request parameters

Credentials are likely to only require a subset of the data available on your claims source. To accommodate this, MATTR VII can pass request parameters that can be used to filter data queries. These parameters can be any claims retrieved from the Authentication provider and/or the Interaction hook component, and can be either dynamic or static.

Dynamic request parameters

You can map dynamic request parameters from two objects that are available in the OID4VCI workflow:

• claims : This object includes all the claims retrieved from the Authentication provider and/or the interaction hook.

• credentialConfiguration : You can use this object to pass elements of the credential configuration as request parameters:
  • id : Unique configuration identifier.
  • type : Credential type, globally unique per Credential configuration on your tenant (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:
    • JSON credentials: web-semantic.
    • CWT credentials: compact.
    • Semantic CWT credentials: compact-semantic.
    • mDocs: mobile.

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

Static request parameters

You can define a static request parameter by only providing a default value with no mapping path. Doing so means the default value is always passed as a request parameter, regardless of any claims available in a specific issuance workflow.

Additional resources

Guides

API Reference

Sample Apps