Credential Issuance

The Issuer2 service follows the same flow as the issuer service. You can follow the same guides to issue credentials as the issuer service. Any new features in the Issuer2 service are documented below.

• W3C VC: Issue W3C Credentials (JWT / SD-JWT) via OID4VC
• SD-JWT VC: Issue SD-JWT VC Credentials via OID4VC
• mDoc: Issue mDoc Credentials via ISO/IEC 18013-7

#Unsupported Features in the Issuer2 Service

Currently, the issuer2 does not support automatic credential status creation.

#New Features in the Issuer2 Service

The following features are only available to specific customers as they are in an early stage of development. Please contact us if you are an enterprise customer and are also interested in using them.

#Credential Offer by Value

It is now possible to configure whether to use credential offer by value or by reference. Note that the Walt.id stack will always use credential offer by reference (which is the default behavior).

If you need to fetch a credential offer by value, you can use the credentialOfferByValue parameter in the issue endpoint.

{
  "credentialOfferByValue": true
}

The credentialOfferByValue parameter is a boolean value. If it is set to true, the credential offer will be fetched by value. If it is set to false, the credential offer will be fetched by reference.

The default value is false.

#Issuer Defaults

When creating a new issuer service, you can now configure the default values for the issuer. These values will be used as a fallback for the credential issuance when no session exists. This happens in two scenarios:

1. Wallet initiated flows, where the wallet requests a credential issuance
2. Issuer initiated flows, where the issuer does not know which user will claim the credential

You configure the issuer defaults as part of the creation of the issuer2 service (which can be viewed and updated using the /v1/{target}/issuer-service-api2/configuration/view and /v1/{target}/issuer-service-api2/configuration/update endpoints respectively). You can define the issuanceConfigurationDefaults object as shown below.

Please find more information regarding the issuer configuration here.

{
  // Follow the same configuration as before...
  "traversable": true,
  "_id": "waltid.tenant.issuer22.config1",
  "supportedCredentialTypes": { ... },
  "tokenKeyId": "your-token-key-id",
  "kms": "waltid.tenant.kms",
  "baseUrl": "https://your-custom-domain.com",
  "authProviderConfiguration": { ... },

  // With these additional fields:
  "issuanceConfigurationDefaults": {
    "eu.europa.ec.eudi.pid.1": {
      "issuerKeyId": "your-issuer-key-id",
      "x5Chain": [
        "-----BEGIN CERTIFICATE-----
...intermediate cert...
-----END CERTIFICATE-----
"
      ],
      "idTokenClaimsToCredentialDataJsonPathMappingConfig": {
        "$.family_name": "$.['eu.europa.ec.eudi.pid.1'].family_name",
        "$.given_name": "$.['eu.europa.ec.eudi.pid.1'].given_name"
      },
      "mDocNameSpacesDataMappingConfig": {
        "eu.europa.ec.eudi.pid.1": {
          "entriesConfigMap": {
            "birth_date": {
              "type": "string",
              "conversionType": "stringToFullDate"
            },
            "issue_date": {
              "type": "string",
              "conversionType": "stringToFullDate"
            },
            "expiry_date": {
              "type": "string",
              "conversionType": "stringToFullDate"
            }
          }
        }
      },
      "staticCredentialData": {
        "eu.europa.ec.eudi.pid.1": {
          "family_name": "PLACEHOLDER",
          "given_name": "PLACEHOLDER",
          "nationality": "AT",
          "birth_date": "1986-03-22",
          "issue_date": "2024-01-01",
          "expiry_date": "2029-01-01"
        }
      },
      "authenticationMethod": "ID_TOKEN"
    }
  }
}

The issuanceConfigurationDefaults object is a JSON object that contains the default values for the issuer for each supported credential configuration id. The example above shows the configuration for the EUDI PID format where we pull first and last name from the ID token claims, and have static values for the other claims.

The issuanceConfigurationDefaults object contains the following fields:

• issuerKeyId: String - The key id of the issuer key to use for the credential issuance.
• x5Chain: Array - The X.509 certificate chain to use for the credential issuance.
• idTokenClaimsToCredentialDataJsonPathMappingConfig: Object - (Optional) The ID token claims to credential data JSON path mapping configuration to use for the credential issuance.
• mDocNameSpacesDataMappingConfig: Object - (Optional)The mDoc name spaces data mapping configuration to use for the credential issuance. Only required for mDoc credentials.
• staticCredentialData: Object - The static credential data to use for the credential issuance. Must contain the placeholder values for claims which will be replaced by the ID token claims.
• authenticationMethod: String - The authentication method to use for the credential issuance.

#Auth code flow

When initiating an auth code flow you have two options:

1. You already know the user you are going to issue the credential to. You can put their user ID from the configured IDP (which will be used in the sub claim of the ID Token) in the subjectId parameter in the issue endpoint.
2. You do not know the user you are going to issue the credential to. In this case, the values given in the /issue endpoint will be ignored, and the values in the issuanceConfigurationDefaults object is used instead when this user claims the credential.