Skip to main content

Credential configuration claims

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

This is an example of what a user object looks like for each of your users:


{
    "authenticationProvider": {
        "url": "https://account.example.com",
        "subjectId": "145214ad-3635-4aff-b51d-61d69a3c8eee"
    },
    "claims": {
        "given_name": "John",
        "family_name": "Doe",
        "email": "john.doe@example.com",
        "address": {
            "formatted": "123FooRd,BarWorld"
        }
    }
}

  • authenticationProvider: References the Identity Provider (IdP) that was used to authenticate the user.

  • claims: In this example we can see that claims has given_name family_name, email and address available for claim mapping.

Claim types​

These are the types of claims you can include in the credential configuration claimMappings object:

  • Required claims

  • Optional claims

  • Claims with default values

  • Static claims

This section introduces using each type by providing an example claim mapping, the theoretical user object that exists on VII and what the issued credential would look like.

Required claims​

If required is set to true, and the claim fails to map, the credential cannot be issued.

Example mapping​


{
    "claimMappings": {
        "dateOfBirth": {
            "mapFrom": "claims.dateOfBirth",
            "required": true
        },
        "email": {
            "mapFrom": "claims.email",
            "required": false
        }
    }
}

Example user data​


{
    "authenticationProvider": {
        "url": "https://account.example.com",
        "subjectId": "145214ad-3635-4aff-b51d-61d69a3c8eee"
    },
    "claims": {
        "email": "john.doe@example.com"
    }
}

Issued credential​

The issuance will result in an error and the credential will not be issued as dateOfBirth is a required claim that does not exist in the user data.

Optional claims​

If required is not present in claimMappings or if it is set to false and the claim fails to map, the credential will still be issued but will not contain the claim.

Example mapping​


{
    "claimMappings": {
        "dateOfBirth": {
            "mapFrom": "claims.dateOfBirth",
            "required": false
        },
        "email": {
            "mapFrom": "claims.email",
            "required": false
        }
    }
}

Example user data​


{
    "authenticationProvider": {
        "url": "https://account.example.com",
        "subjectId": "145214ad-3635-4aff-b51d-61d69a3c8eee"
    },
    "claims": {
        "email": "john.doe@example.com"
    }
}

Issued credential​

The user data only has email in claims, but not dateOfBirth. Since dateOfBirth is an optional field for this configuration, the issued credential will contain email mapped from user data, but will not contain dateOfBirth as a claim.


{
    "credentialSubject": {
        "email": "john.doe@example.com"
    }
}

Claims with default values​

If a default value is provided and the claim fails to map, the credential will be issued with the claim using the default value.

Example mapping​


{
   "claimMappings": {
      "dateOfBirth": {
         "mapFrom": "claims.dateOfBirth",
         "defaultValue": "Not provided"
      },
      "email":{
         "mapFrom": "claims.email",
         "required": true
      }
   }
}

Example user data​


{
    "authenticationProvider": {},
    "claims": {
        "email": "john.doe@example.com"
    }
}

Issued credential​

The user data has email in claims but it doesn't have the dateOfBirth, which means we won't be able to map values for dateOfBirth into the credential. However, we have setup the defaultValue for date of birth as Not provided, which means Sovrin will use Not provided on the issued credential.


{
    "credentialSubject": {
        "dateOfBirth": "Not provided",
        "email": "john.doe@example.com"
    }
}

Static claims​

Static values can be set by providing a defaultValue without mapFrom:

Example mapping​


{
    "claimMappings": {
        "email": {
            "defaultValue": "noreply@example.com"
        }
    }
}

Example user data​


{
    "authenticationProvider": {},
    "claims": {
        "email": "john.doe@example.com"
    }
}

Issued credential​

Although the user has an email claim, the issued credential will use the default value configured in the credential configuration:


{
    "credentialSubject": {
        "email": "noreply@example.com"
    }
}

Other value data types​

Sovrin supports claims in various data types such as string, numeric, JSON and arrays, as shown in the following example mapping:


{
    "claimMappings": {
        "staticStringValue": {
            "defaultValue": "foo"
        },
        "staticNumericValue": {
            "defaultValue": 12.34
        },
        "staticJsonValue": {
            "defaultValue": {
                "foo": "bar"
            }
        },
        "staticArrayValue": {
            "defaultValue": [
                "foo",
                "bar"
            ]
        }
    }
}