Skip to main content

Configure a claims source

This tutorial explains how to configure a claims source on your Sovrin tenant, and what kind of requests will be made to that claims source when new credentials are issued.

This process is slightly different depending on your configured authorisation method, so the following options are described:

tip

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

API Key​

Request​

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


POST https://api.sovrin.one/v1/claimsources


{
    "name": "YOUR_CLAIM_SOURCE_NAME",
    "url": "https://api.example.com/myclaims",
    "authorization": {
        "type": "api-key",
        "value": "2e972131302b4ba28d978c901390a995"
    },
    "requestMethod": "GET",
    "requestParameters": {
        "email": {
            "mapFrom": "claims.email"
        },
        "userType": {
            "defaultValue": "student"
        },
        "credentialProfile": {
            "mapFrom": "credentialConfiguration.profile"
        }
    }
}

  • name: Claims source name.

  • url: Claims source URL:

    • Must be a valid URL.

    • Must use the HTTPS protocol.

    • Must not be an IP address.

    • Must not include query parameters.

  • authorization: API Key to access the claims source.

    • type: This example uses api-key to authenticate with this claim source.

    • value: API key value. Note that Sovrin does not validate your input, which means it's up to you to provide the correct API key for your claim sources.

  • requestMethod: Indicates the request method Sovrin 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 to be used to query your claims source for specific data. This example uses the following parameters:

    • email: Uses the mapFrom method. In this example Sovrin will query the claims source for a user with an email attribute that matches the claims.email value.

    • userType: Uses the defaultValue method. In this example Sovrin will query the claims source for users that have student as a userType attribute.

  • credentialProfile: Uses the mapFrom method. In this example Sovrin will only fetch data that is mapped to credentials that match the credentialConfiguration.profile value.

Response​


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

Querying the Claims Source​

Request​

The created claims source configuration should result in Sovrin making the following request during an issuance flow:


GET https://example.com/myclaims?email=john@example.com&userType=student&credentialProfile=web-semantic 
  Headers:
    x-api-key: 2e972131302b4ba28d978c901390a995  
    x-request-id: 52tg0VFqRR6FjFsGB8CBhm

This query will fetch data for the user that matches the following parameters:

When the requestMethod is set to POST, that same request would look as follows:


POST https://example.com/myclaims
  Headers:
    x-api-key: 2e972131302b4ba28d978c901390a995 
    x-request-id: 52tg0VFqRR6FjFsGB8CBhm
    content-type: application/json
  Body:
    { "email": "john@example.com", "userType": "student", "credentialProfile": "web-semantic" }

Response​


{
    "user": {
        "firstName": "John",
        "lastName": "Jones"  
    },
    "account": {
        "type": "admin",
        "team": "managers"
    }
}

These claims can now be mapped to the issued credential as configured when you setup a credential configuration.

OAuth client credentials​

When using OAuth client credentials to authenticate with your claims source, the request to configure a new claims source would be similar to the one described above, with two notable differences:

  • The authorization object should include different elements which are required for OAuth authentication. Refer to the Overview page for more information.

  • Sovrin will validate the data provided in the authorization object by fetching an access token and verifying it follows the OAuth 2 standard. This means that you must always provide valid authentication credentials in this object, even for prototyping/testing etc.

Requesting an Access Token​

When querying the claims source using OAuth credentials, Sovrin will first request an access token, depending on your chosen authentication method (refer to the Overview page for more information):

Request using​


POST https://example.com/oauth/token
  Headers:
    x-request-id: 52tg0VFqRR6FjFsGB8CBhm
    authorization: Basic base64(clientId:clientSecret)
    content-type: application/x-www-form-urlencoded
  Body:
    grant_type=client_credentials&audience=example.com

Request using​


POST https://example.com/oauth/token
  Headers:
    x-request-id: 52tg0VFqRR6FjFsGB8CBhm
    content-type: application/x-www-form-urlencoded
  Body:
    client_id=clientId&client_secret=clientSecret&grant_type=client_credentials&audience=example.com

Request​

Both requests should result in the same expected response:


{
  "access_token": "<string>",
  "token_type": "Bearer",
  "expires_in": 900 // integer in seconds, recommended but not mandatory
}

Querying the Database​

Once an access token is obtained, Sovrin will make one of the following call to query your claims source, based on your requestMethod:

Request using​


POST https://example.com/myclaims
Headers:
  authorization: Bearer access_token
  x-request-id: 52tg0VFqRR6FjFsGB8CBhm
  content-type: application/json
Body:
  { "email": "john@example.com", "userType": "student", "credentialProfile": "web-semantic" }

For both methods the response would be similar to the one described above.

What's Next?​

Now that you have your claims source configured, you can configure an interaction hook as part of your OpenId4VCI issuance workflow.

If your use case does not require an interaction hook, you can proceed to create a credential configuration.