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 thegiven_name
,family_name
,email
andaddress
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'sclaims
object to map the claim from.defaultValue
: Defines the value that will be used to populate the claim if mapping fails ormapFrom
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:
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"
}
}