Overview

Our OpenID Credential Provisioning capability can create credentials with claims fetched from an Identity Provider (IdP), interaction hook or any external supported claims source.

In some cases, these claim sources are not integrated with the IdP and instead may have standalone databases that need to be interfaced with directly. To accommodate that, we have added support for retrieving data from a custom claim 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 those claims when issuing credentials.

This workflow includes the following steps:

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

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

3. This fetched user data can now be used to populate different elements within the issued credential.

Authorization

We strongly recommend protecting your claims source using authentication control to protect against unauthorised access.

MATTR VII currently supports two authentication methods:

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

• oauth-client-credentials: MATTR VII will first use your oauth client credentials to fetch an access token. Once the token is retrieved, it will be used as an Authorization header prefixed by its token type. When using OAuth client credentials as an authorization 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: This can be one of two options:

    • client_secret_basic: Your credentials will be passed as a base 64 encoded basic token.

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

MATTR VII only supports Bearer access tokens.

Request parameters

You can configure MATTR VII to query the claims source based on certain request parameters which would enable you to fetch specific data for specific users.

Querying for specific users

There are two methods you can use to query for specific users:

• mapFrom: This populates the query parameter with attributes from the claims object. Attributes in this object are mapped from your IdP token ID and depend on your configuration.

• defaultValue: This populates the query parameter with a static value of your choice.

Querying for specific data

When you setup a credential configuration, you define what values are mapped form the claims source when a credential is issued. Thus, when querying the claims source, you can limit the fetched data so that the claims source only returns data that is required to create the new credential.

This functionality is achieved using the credentialConfiguration object, which contains three elements that you can use to limit fetched data:

• id: This will only fetch data which is mapped to the configuration which matches this unique identifier.

• type: This will only fetch data which is mapped to configurations of this type (configuration type is defined as part of their setup process).

• profile: This will only fetch data which is mapped to configurations of this profile (configuration profile is defined as part of their setup process):

  • Web Credentials: web-semantic.

  • Compact Credentials: compact.

  • Compact Semantic Credentials: compact-semantic.

Claims source requirements

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

• The claims source must be accessible from the internet via HTTPS (e.g. https://example.com ).

• The claims source 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.  

• The claims source response must conform to the following rules :

  • Return a response within three seconds to avoid MATTR VII request timeout .

  • Return a 2XX HTTP status code when the request was successful. 

  • The response body must be a valid JSON, denoted by the application/json MIME type. 

  • In the JSON object, each key 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.

  • Only respond with error codes when something exceptional happens. MATTR VII will log the error, but issuance will only fail when it does not meet the requirements of the credential type being issued, e.g., if no value for a mandatory claim could be found. 

What's Next?

You can now proceed to configure a new claims source.