Skip to main content

Claims source

The Sovrin 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 claim source via a single API call.

Sovrin 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 will be used to query it when fetching data.

  2. When issuing a new credential, Sovrin 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 Sovrin tenant.

tip

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

Claims source requirements​

Sovrin 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 Sovrin 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. Sovrin will log the error, but issuance will only fail when it does not meet an explicit credential configuration requirement. (e.g., if no value for a required claim could is available).

Authorisation​

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

Sovrin 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: Sovrin 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.

    tip

    Sovrin only supports Bearer access tokens.

    Request parameters​

Some use cases might only require a subset of the data you have available on your claims source. To accomodate that and avoid retrieving unnecessary data, you can configure Sovrin with request parameters to only query for specific data and 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 create 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 retrieved 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 retrieved data:

  • id: Only query for data mapped to a configuration matching this unique identifier.

  • type: Only query for data mapped to configurations of this type (configuration type is defined as part of their [setup process(./configuration-overview)]).

  • profile: Only query for data mapped to configurations of this 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.

What's Next?​

You can now proceed to configure a claims source.