Credential configuration claims
The MATTR VII 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:
1{
2 "authenticationProvider": {
3 "url": "https://account.example.com",
4 "subjectId": "145214ad-3635-4aff-b51d-61d69a3c8eee"
5 },
6 "claims": {
7 "given_name": "John",
8 "family_name": "Doe",
9 "email": "john.doe@example.com",
10 "address": {
11 "formatted": "123FooRd,BarWorld"
12 }
13 }
14}
authenticationProvider: References the Identity Provider (IdP) that was used to authenticate the user.claims: In this example we can see thatclaimshasgiven_namefamily_name,emailandaddressavailable 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
1{
2 "claimMappings": {
3 "dateOfBirth": {
4 "mapFrom": "claims.dateOfBirth",
5 "required": true
6 },
7 "email": {
8 "mapFrom": "claims.email",
9 "required": false
10 }
11 }
12}
Example user data
1{
2 "authenticationProvider": {
3 "url": "https://account.example.com",
4 "subjectId": "145214ad-3635-4aff-b51d-61d69a3c8eee"
5 },
6 "claims": {
7 "email": "john.doe@example.com"
8 }
9}
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
1{
2 "claimMappings": {
3 "dateOfBirth": {
4 "mapFrom": "claims.dateOfBirth",
5 "required": false
6 },
7 "email": {
8 "mapFrom": "claims.email",
9 "required": false
10 }
11 }
12}
Example user data
1{
2 "authenticationProvider": {
3 "url": "https://account.example.com",
4 "subjectId": "145214ad-3635-4aff-b51d-61d69a3c8eee"
5 },
6 "claims": {
7 "email": "john.doe@example.com"
8 }
9}
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.
1{
2 "credentialSubject": {
3 "email": "john.doe@example.com"
4 }
5}
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
1{
2 "claimMappings": {
3 "dateOfBirth": {
4 "mapFrom": "claims.dateOfBirth",
5 "defaultValue": "Not provided"
6 },
7 "email":{
8 "mapFrom": "claims.email",
9 "required": true
10 }
11 }
12}
Example user data
1{
2 "authenticationProvider": {},
3 "claims": {
4 "email": "john.doe@example.com"
5 }
6}
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 MATTR VII will use Not provided on the issued credential.
1{
2 "credentialSubject": {
3 "dateOfBirth": "Not provided",
4 "email": "john.doe@example.com"
5 }
6}
Static claims
Static values can be set by providing a defaultValue without mapFrom:
Example mapping
1{
2 "claimMappings": {
3 "email": {
4 "defaultValue": "noreply@example.com"
5 }
6 }
7}
Example user data
1{
2 "authenticationProvider": {},
3 "claims": {
4 "email": "john.doe@example.com"
5 }
6}
Issued credential
Although the user has an email claim, the issued credential will use the default value configured in the credential configuration:
1{
2 "credentialSubject": {
3 "email": "noreply@example.com"
4 }
5}
Other value data types
MATTR VII supports claims in various data types such as string, numeric, JSON and arrays, as shown in the following example mapping:
1{
2 "claimMappings": {
3 "staticStringValue": {
4 "defaultValue": "foo"
5 },
6 "staticNumericValue": {
7 "defaultValue": 12.34
8 },
9 "staticJsonValue": {
10 "defaultValue": {
11 "foo": "bar"
12 }
13 },
14 "staticArrayValue": {
15 "defaultValue": [
16 "foo",
17 "bar"
18 ]
19 }
20 }
21}