Credential configurations

Credential configurations are templates that are define rules and parameters that are used to issue a specific type of digital credential. They are referenced in Credential offers and define:

• What claims to include in the credential and where to map them from. Every claim that was retrieved as part of the issuance workflow can be used in the credential. This includes claims from the Authentication provider, Interaction hook and Claims source.
• The configured claims source to query during the issuance workflow.
• What branding is applied to the credential, including name and description strings, background colour, watermarks, logos and icons (Branding is only applicable to Web and Mobile Credentials).
• The credential expiry date, relative to the issuance timestamp.
• What credential management capabilities it enables. This currently includes revocation and data persistence.

Once you create a credential configuration, its details are available on your tenant's ./well-known/openid-credential-issuer endpoint (https://{your_tenant_url}/.well-known/openid-credential-issuer) so that credentials available from an issuer can be looked up by a wallet. If this endpoint is not resolvable, OID4VCI workflows would fail. This is especially important when configuring a Custom domain, which requires creating a redirect from your custom domain URL to your MATTR VII tenant URL where this resource is available.

Your tenant can include multiple Credential configurations to meet different use cases.

Claims mapping

Credential configurations define the mapping of claims from the internal user object into the issued credential. This is an example of what a user object looks like:

{
    "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 :
  • url : References the Authentication provider that is used to authenticate this user.
  • subjectId : Indicates the unique identifier of the user with this Authentication provider.
• claims : This object is used to hold claims fetched as part of the OID4VCI workflow. This can include claims from the configured Authentication provider, Interaction hook and Claims source. In this example we can see that the objects includes the given_name, family_name, email and address claims. These are therefore available for mapping into the issued credential.

Mapping is performed using the claimMapping object in the credential configuration. Each item in the object represents a credential claim and must include at least one of the following properties:

• mapFrom : Defines the path in the user's claims object to map the claim from.
• defaultValue : Defines the value that will be used to populate the claim if mapping fails or mapFrom is not included.

Here is an example of a claimMapping object:

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

This example maps the required dateOfBirth claim from claims.dateOfBirth and the optional email claim from claims.email. It also defines Not available as a default value for the email claim.

Claims types

The claimMappings object can include the following claim types:

• Required claims
• Optional claims
• Claims with default values
• Static claims

This section explains the usage of 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, issuance will fail.

Example claimMapping object

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

Example user object

{
    "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 be issued but will not contain the claim.

Example claimMapping object

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

Example user object

{
    "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 no 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 in the defaultValue property and the claim fails to map, the credential will be issued and the claim will be populated with the default value.

Example claimMapping object

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

Example user object

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

Issued credential

The user data has email in their claims object but it doesn't have a 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 as date of birth for the issued credential.

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

Static claims

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

Example claimMapping object

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

Example user object

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

Additional resources

Guides

API Reference

Sample Apps