APEREO CASDocumentation

Enterprise Authentication for All Earthlings and Beyond

Identity, Single Sign-On and Access Management
View on GitHub

Verifiable Credentials - OpenID Connect Authentication

OpenID Connect Authentication can be used in conjunction with Verifiable Credentials to provide a secure and decentralized way of verifying user identities. Verifiable Credentials are digital credentials that can be issued by trusted authorities and can be presented by users to prove their identity or attributes.

In this role, CAS acts as an OpenID Credential Issuer and extends its existing OpenID Connect capabilities with support for credential issuance, credential metadata publication, proof validation, nonce generation, and wallet-facing issuance flows.

The following capabilities are in place:

  • Issuer metadata is published via the .well-known/openid-credential-issuer endpoint.
  • CAS may issue credentials formats such as SD-JWT VC (selective disclosure), etc.
  • Dedicated endpoints for credential issuance and nonce generation are available.
  • Credential offers may be produced and shared with wallets.
  • Pre-authorized code flows may be used to obtain issuance-scoped access tokens.
  • Access tokens issued for verifiable credential flows may carry authorization context for one or more credential configurations.
  • Proofs may be validated to ensure possession of holder key material and to prevent replay.

Supported formats are:

  • dc+sd-jwt
  • jwt_vc_json
  • jwt_vc_json-ld

Overview

Support is enabled by including the following module in the overlay:

Show in CAS Initializr Generate CAS Server WAR Overlay 


1
2
3
4
5



<dependency>
    <groupId>org.apereo.cas</groupId>
    <artifactId>cas-server-support-oidc-vc</artifactId>
    <version>${cas.version}</version>
</dependency>





1



implementation "org.apereo.cas:cas-server-support-oidc-vc:${project.'cas.version'}"





1
2
3
4
5
6
7
8
9



dependencyManagement {
    imports {
        mavenBom "org.apereo.cas:cas-server-support-bom:${project.'cas.version'}"
    }
}

dependencies {
    implementation "org.apereo.cas:cas-server-support-oidc-vc"
}





1
2
3
4
5
6
7
8
9
10



dependencies {
    /*
        The following platform references are included automatically and are listed for reference only.

        implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")
        implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
        
    */
    implementation "org.apereo.cas:cas-server-support-oidc-vc"
}

The following settings and properties are available from the CAS configuration catalog:

cas.authn.oidc.vc.issuer.batch-sizeMaximum number of credential requests accepted in a single batch.
10

Maximum number of credential requests accepted in a single batch.

Type
Integer
Default
10
Defined by
OidcVerifiableCredentialsIssuerProperties
cas.authn.oidc.vc.issuer.credential-configurations.[key].claims.[key].disclosableA claim that is candidate for Selective Disclosure.
true

A claim that is candidate for Selective Disclosure. It is packaged inside the credential in a way that allows the Holder to selectively share it—or completely hide it—when presenting the credential to a Verifier (Relying Party).

Type
boolean
Default
true
Defined by
OidcVerifiableCredentialClaimProperties
cas.authn.oidc.vc.issuer.credential-configurations.[key].claims.[key].displayControl display settings for this claim.
no default

Control display settings for this claim.

Type
List<OidcVerifiableCredentialClaimProperties.CredentialClaimDisplay>
Default
none
Defined by
OidcVerifiableCredentialClaimProperties
cas.authn.oidc.vc.issuer.credential-configurations.[key].claims.[key].display[0].localeLocale that controls this configuration's display.
en-US

Locale that controls this configuration's display.

Type
String
Default
en-US
Defined by
CredentialClaimDisplay
cas.authn.oidc.vc.issuer.credential-configurations.[key].claims.[key].display[0].nameDisplay name for this configuration.
no default

Display name for this configuration.

Type
String
Default
none
Defined by
CredentialClaimDisplay
cas.authn.oidc.vc.issuer.credential-configurations.[key].claims.[key].mandatoryWhether this claim is mandatory.
no default

Whether this claim is mandatory. A claim (attribute) that must be present in the Verifiable Credential when it is issued. The Issuer requires this data to make the credential valid.

Type
boolean
Default
none
Defined by
OidcVerifiableCredentialClaimProperties
cas.authn.oidc.vc.issuer.credential-configurations.[key].credential-signing-alg-values-supportedLists the signing algorithms supported by the issuer when producing the credential for this configuration.
ES256,RS256

Lists the signing algorithms supported by the issuer when producing the credential for this configuration. These algorithm identifiers are typically JOSE signature algorithms such as ES256 or RS256, and are advertised in issuer metadata so wallets know what credential signature formats are supported.

Type
List<String>
Default
ES256,RS256
Defined by
OidcVerifiableCredentialConfigurationProperties
cas.authn.oidc.vc.issuer.credential-configurations.[key].credential-validityLength of time for which a credential issued by this configuration remains valid.
P30D
Duration

Length of time for which a credential issued by this configuration remains valid. The value controls the exp claim of the issued credential, and the validUntil property for credential formats that carry one. Wallets store credentials long after issuance, so this must outlive the issuance exchange itself.

Type
String
Default
P30D
Defined by
OidcVerifiableCredentialConfigurationProperties
cas.authn.oidc.vc.issuer.credential-configurations.[key].cryptographic-binding-methods-supportedLists the supported cryptographic binding methods for this credential.
jwk

Lists the supported cryptographic binding methods for this credential. These values indicate how the issued credential may be bound to key material controlled by the wallet or holder. A common value is jwk, which indicates binding via a JSON Web Key.

Type
List<String>
Default
jwk
Defined by
OidcVerifiableCredentialConfigurationProperties
cas.authn.oidc.vc.issuer.credential-configurations.[key].deferred-issuanceWhether credentials of this configuration are issued in a deferred manner.
no default

Whether credentials of this configuration are issued in a deferred manner. A credential request is then answered with a transaction_id, and the wallet collects the credentials from the deferred credential endpoint once the transaction has been approved through the oidcVcDeferred actuator endpoint. The ticket registry keeps the transactions; a registry that cannot keep them, such as the stateless ticket registry, issues the credentials immediately.

Type
boolean
Default
none
Defined by
OidcVerifiableCredentialConfigurationProperties
cas.authn.oidc.vc.issuer.credential-configurations.[key].displayControl display settings of this credential configuration used in metadata generation.
org.apereo.cas.configuration.model.support.oidc.OidcVerifiableCredentialConfigurationProperties$CredentialConfigurationDisplay@3605c4d3

Control display settings of this credential configuration used in metadata generation.

Type
List<OidcVerifiableCredentialConfigurationProperties.CredentialConfigurationDisplay>
Default
org.apereo.cas.configuration.model.support.oidc.OidcVerifiableCredentialConfigurationProperties$CredentialConfigurationDisplay@3605c4d3
Defined by
OidcVerifiableCredentialConfigurationProperties
cas.authn.oidc.vc.issuer.credential-configurations.[key].display[0].background-colorBackground color for this configuration.
no default

Background color for this configuration.

Type
String
Default
none
Defined by
CredentialConfigurationDisplay
cas.authn.oidc.vc.issuer.credential-configurations.[key].display[0].descriptionDescription for this configuration.
My verifiable credential that belongs to my organization

Description for this configuration.

Type
String
Default
My verifiable credential that belongs to my organization
Defined by
CredentialConfigurationDisplay
cas.authn.oidc.vc.issuer.credential-configurations.[key].display[0].localeLocale that controls this configuration's display.
en-US

Locale that controls this configuration's display.

Type
String
Default
en-US
Defined by
CredentialConfigurationDisplay
cas.authn.oidc.vc.issuer.credential-configurations.[key].display[0].logoLogo url.
https://apereo.github.io/cas/images/cas_logo.png

Logo url.

Type
String
Default
https://apereo.github.io/cas/images/cas_logo.png
Defined by
CredentialConfigurationDisplay
cas.authn.oidc.vc.issuer.credential-configurations.[key].display[0].nameDisplay name for this configuration.
My Verifiable Credential

Display name for this configuration.

Type
String
Default
My Verifiable Credential
Defined by
CredentialConfigurationDisplay
cas.authn.oidc.vc.issuer.credential-configurations.[key].display[0].text-colorText color for this configuration.
no default

Text color for this configuration.

Type
String
Default
none
Defined by
CredentialConfigurationDisplay
cas.authn.oidc.vc.issuer.credential-configurations.[key].formatDefines the credential format issued for this configuration.
OidcVerifiableCredentialConfigurationProperties.CredentialConfigurationFormats.DC_SD_JWT(dc+sd-jwt)
Defines the credential format issued for this configuration. Typical values depend on the verifiable credential profile supported by the issuer, such as JWT-based or SD-JWT-based credentials. This value is published in issuer metadata and is used by wallets to determine how the credential request and response should be processed. Available values are as follows:
  • DC_SD_JWT: A Data Integrity Claims (DC) credential encoded as an SD-JWT, supporting selective disclosure of claims while preserving cryptographic integrity.
  • JWT_VC_JSON: It is a JSON-based string that represents the credential as a base64url-encoded JWT.
  • JWT_VC_JSON_LD: This format includes a @context URLs that maps data properties to universal schemas. Every field has a strict, globally defined semantic meaning.
Type
OidcVerifiableCredentialConfigurationProperties.CredentialConfigurationFormats
Default
OidcVerifiableCredentialConfigurationProperties.CredentialConfigurationFormats.DC_SD_JWT(dc+sd-jwt)
Defined by
OidcVerifiableCredentialConfigurationProperties
cas.authn.oidc.vc.issuer.credential-configurations.[key].key-attestations.key-storageAttack potential resistance levels of the key storage this credential configuration accepts, such as iso_18045_high or iso_18045_moderate .
no default

Attack potential resistance levels of the key storage this credential configuration accepts, such as iso_18045_high or iso_18045_moderate. When set, a key attestation must name at least one of them in its key_storage claim.

Type
List<String>
Default
none
Defined by
OidcVerifiableCredentialKeyAttestationRequirementProperties
cas.authn.oidc.vc.issuer.credential-configurations.[key].key-attestations.requiredWhether every proof for this credential configuration must come with a key attestation, either in the key_attestation header of a jwt proof or as an attestation proof.
no default

Whether every proof for this credential configuration must come with a key attestation, either in the key_attestation header of a jwt proof or as an attestation proof.

Type
boolean
Default
none
Defined by
OidcVerifiableCredentialKeyAttestationRequirementProperties
cas.authn.oidc.vc.issuer.credential-configurations.[key].key-attestations.user-authenticationAttack potential resistance levels of user authentication this credential configuration accepts, such as iso_18045_high .
no default

Attack potential resistance levels of user authentication this credential configuration accepts, such as iso_18045_high. When set, a key attestation must name at least one of them in its user_authentication claim.

Type
List<String>
Default
none
Defined by
OidcVerifiableCredentialKeyAttestationRequirementProperties
cas.authn.oidc.vc.issuer.credential-configurations.[key].proof-signing-alg-values-supportedLists the signing algorithms supported for proof validation when the wallet submits proof material as part of a credential request.
ES256,RS256

Lists the signing algorithms supported for proof validation when the wallet submits proof material as part of a credential request. These values represent the algorithms CAS accepts when verifying proof-of-possession tokens or JWT-based proofs presented by the holder.

Type
List<String>
Default
ES256,RS256
Defined by
OidcVerifiableCredentialConfigurationProperties
cas.authn.oidc.vc.issuer.credential-configurations.[key].scopeOAuth scope associated with this credential configuration.
no default

OAuth scope associated with this credential configuration. This scope may be used during authorization and token issuance to indicate that the client or wallet is requesting permission to obtain this specific type of verifiable credential.

Type
String
Default
none
Defined by
OidcVerifiableCredentialConfigurationProperties
cas.authn.oidc.vc.issuer.deferred-issuance.intervalHow long a wallet should wait before asking for the credentials of a deferred transaction again, advertised as the interval of the credential response.
PT5M
Duration

How long a wallet should wait before asking for the credentials of a deferred transaction again, advertised as the interval of the credential response.

Type
String
Default
PT5M
Defined by
OidcVerifiableCredentialDeferredIssuanceProperties
cas.authn.oidc.vc.issuer.deferred-issuance.time-to-liveHow long a deferred transaction is kept.
P7D
Duration

How long a deferred transaction is kept. A transaction that is neither approved and collected nor denied within this time expires, and the wallet is told its transaction_id is invalid.

Type
String
Default
P7D
Defined by
OidcVerifiableCredentialDeferredIssuanceProperties
cas.authn.oidc.vc.issuer.displayHow wallets present this credential issuer, one entry per language.
no default

How wallets present this credential issuer, one entry per language. Published as the display of the credential issuer metadata; wallets show the issuer as unnamed without it.

Type
List<OidcVerifiableCredentialsIssuerProperties.IssuerDisplay>
Default
none
Defined by
OidcVerifiableCredentialsIssuerProperties
cas.authn.oidc.vc.issuer.display[0].localeLanguage of this display, as a BCP 47 language tag such as en-US .
no default

Language of this display, as a BCP 47 language tag such as en-US.

Type
String
Default
none
Defined by
IssuerDisplay
cas.authn.oidc.vc.issuer.display[0].logoURL of the credential issuer's logo.
no default

URL of the credential issuer's logo.

Type
String
Default
none
Defined by
IssuerDisplay
cas.authn.oidc.vc.issuer.display[0].logo-alt-textAlternative text for the logo; defaults to the display name.
no default

Alternative text for the logo; defaults to the display name.

Type
String
Default
none
Defined by
IssuerDisplay
cas.authn.oidc.vc.issuer.display[0].nameDisplay name of the credential issuer.
no default

Display name of the credential issuer.

Type
String
Default
none
Defined by
IssuerDisplay
cas.authn.oidc.vc.issuer.encryption.alg-values-supportedJWE key management algorithms ( alg ) the issuer accepts in the key a wallet supplies for response encryption.
no default

JWE key management algorithms (alg) the issuer accepts in the key a wallet supplies for response encryption.

Type
List<String>
Default
none
Defined by
OidcVerifiableCredentialEncryptionProperties
cas.authn.oidc.vc.issuer.encryption.enabledWhether the issuer metadata advertises credential_request_encryption and credential_response_encryption , and the credential endpoint accepts encrypted requests and encrypts responses when asked to.
false

Whether the issuer metadata advertises credential_request_encryption and credential_response_encryption, and the credential endpoint accepts encrypted requests and encrypts responses when asked to. The current encryption keys of the OpenID Connect keystore are published for request encryption: an RSA key is used with RSA-OAEP-256 and an elliptic curve key with ECDH-ES.

Type
Boolean
Default
false
Defined by
OidcVerifiableCredentialEncryptionProperties
cas.authn.oidc.vc.issuer.encryption.enc-values-supportedJWE content encryption algorithms ( enc ) accepted for encrypted requests and offered for encrypted responses.
no default

JWE content encryption algorithms (enc) accepted for encrypted requests and offered for encrypted responses.

Type
List<String>
Default
none
Defined by
OidcVerifiableCredentialEncryptionProperties
cas.authn.oidc.vc.issuer.encryption.request-encryption-requiredWhether every credential request must be encrypted.
false

Whether every credential request must be encrypted.

Type
Boolean
Default
false
Defined by
OidcVerifiableCredentialEncryptionProperties
cas.authn.oidc.vc.issuer.encryption.response-encryption-requiredWhether every credential response must be encrypted, so that a wallet has to supply credential_response_encryption with each request.
false

Whether every credential response must be encrypted, so that a wallet has to supply credential_response_encryption with each request.

Type
Boolean
Default
false
Defined by
OidcVerifiableCredentialEncryptionProperties
cas.authn.oidc.vc.issuer.key-attestation.trust-anchorsLocations of PEM-encoded certificates of the trust anchors that key attestations must chain to, such as those of wallet providers.
no default

Locations of PEM-encoded certificates of the trust anchors that key attestations must chain to, such as those of wallet providers. A key attestation carries its signing certificate, and any intermediate certificates, in its x5c header, which must lead to one of these anchors. Key attestations are not accepted, and the attestation proof type is not offered, until at least one trust anchor is configured.

Type
List<String>
Default
none
Defined by
OidcVerifiableCredentialKeyAttestationProperties
cas.authn.oidc.vc.issuer.status-list.enabledWhether issued SD-JWT VC credentials carry a status claim that points into a status list published by CAS.
false

Whether issued SD-JWT VC credentials carry a status claim that points into a status list published by CAS. Entries are kept in the ticket registry, so the status of a credential survives restarts and is shared between nodes; a stateless ticket registry cannot keep them, and credentials are then issued without status.

Type
Boolean
Default
false
Defined by
OidcVerifiableCredentialStatusListProperties
cas.authn.oidc.vc.issuer.status-list.expirationHow long a status list token is valid after it is issued, advertised as its exp claim.
PT24H
Duration

How long a status list token is valid after it is issued, advertised as its exp claim.

Type
String
Default
PT24H
Defined by
OidcVerifiableCredentialStatusListProperties
cas.authn.oidc.vc.issuer.status-list.sizeNumber of entries in each status list.
131072

Number of entries in each status list. Credentials get random, unpredictable indexes within a list, and a new list is started once a list has little room left. Each entry takes 2 bits, so a multiple of 4 fills whole bytes.

Type
Integer
Default
131072
Defined by
OidcVerifiableCredentialStatusListProperties
cas.authn.oidc.vc.issuer.status-list.time-to-liveHow long a verifier may cache a status list token before fetching it again, advertised as its ttl claim.
PT10M
Duration

How long a verifier may cache a status list token before fetching it again, advertised as its ttl claim. CAS also caches the token it builds for this long.

Type
String
Default
PT10M
Defined by
OidcVerifiableCredentialStatusListProperties
cas.authn.oidc.vc.metadata.include-claimsWhether claims should be included in the metadata.
true

Whether claims should be included in the metadata.

Type
Boolean
Default
true
Defined by
OidcVerifiableCredentialsMetadataProperties
cas.authn.oidc.vc.metadata.signed-metadata-expirationHow long signed credential issuer metadata, returned to wallets that ask for application/jwt , remains valid, advertised as its exp claim.
P1D
Duration

How long signed credential issuer metadata, returned to wallets that ask for application/jwt, remains valid, advertised as its exp claim.

Type
String
Default
P1D
Defined by
OidcVerifiableCredentialsMetadataProperties
cas.authn.oidc.vc.offer.required-principal-attributeThe principal attribute that must be present in the authenticated principal for the offer to be valid.
no default

The principal attribute that must be present in the authenticated principal for the offer to be valid. If not set, the offer is valid for all authenticated principals.

Type
String
Default
none
Defined by
OidcVerifiableCredentialsOfferProperties
cas.authn.oidc.vc.offer.required-principal-attribute-valueThe value of the principal attribute that must be present in the authenticated principal for the offer to be valid.
no default
Regex

The value of the principal attribute that must be present in the authenticated principal for the offer to be valid. If not set, the offer is valid for all authenticated principals.

Type
String
Default
none
Defined by
OidcVerifiableCredentialsOfferProperties
cas.authn.oidc.vc.offer.transaction-code-enabledWhether a transaction code should be attached to credential offers that use the pre-authorized code flow.
true

Whether a transaction code should be attached to credential offers that use the pre-authorized code flow. The code is a secret handed to the issuing party out of band and must be presented back at the token endpoint. Disable this only for wallets that cannot collect the code from the end user, keeping in mind that the pre-authorized code then becomes the only secret protecting the offer.

Type
Boolean
Default
true
Defined by
OidcVerifiableCredentialsOfferProperties
cas.authn.oidc.vc.presentation.client-identifier-prefixHow the wallet is expected to identify and authenticate CAS as the verifier, expressed as an OpenID4VP client identifier prefix.
REDIRECT_URI

How the wallet is expected to identify and authenticate CAS as the verifier, expressed as an OpenID4VP client identifier prefix.

REDIRECT_URI requires no key material, but requests made under it cannot be signed, so the authorization request is carried by value in the deep link and no request URI is offered. X509_SAN_DNS signs the request object with the CAS OpenID Connect signing key and requires that key to carry a certificate chain whose leaf certificate holds a dNSName subject alternative name matching the host of the verifier; only then can the request object be served by reference. X509_HASH, which the OpenID4VC High Assurance Interoperability Profile requires, signs the request object the same way and identifies CAS by the hash of the leaf certificate, so the certificate needs no particular name. Available values are as follows:
  • REDIRECT_URI: The client identifier is the verifier's response URI. Requests cannot be signed and are therefore always passed to the wallet by value.
  • X509_SAN_DNS: The client identifier is a DNS name that must match a dNSName subject alternative name in the leaf certificate used to sign the request object. It requires the CAS OIDC signing key to carry a certificate chain whose leaf certificate holds a dNSName subject alternative name matching the host of the verifier. CAS refuses to serve a request object when it does not, rather than producing one that wallets silently reject.
  • X509_HASH: The client identifier is the base64url-encoded SHA-256 hash of the DER-encoded leaf certificate used to sign the request object. It requires the CAS OIDC signing key to carry a certificate chain.
Type
OidcVerifiableCredentialsPresentationProperties.ClientIdentifierPrefixes
Default
REDIRECT_URI
Defined by
OidcVerifiableCredentialsPresentationProperties
cas.authn.oidc.vc.presentation.response-modeHow the wallet delivers its authorization response, expressed as an OpenID4VP response mode.
DIRECT_POST

How the wallet delivers its authorization response, expressed as an OpenID4VP response mode.

DIRECT_POST posts the response in the clear. DIRECT_POST_JWT has the wallet encrypt it to a key CAS generates for each request and publishes in the request's client metadata, as the OpenID4VC High Assurance Interoperability Profile requires; a presentation that arrives unencrypted is then refused, while an unencrypted error response is still accepted from a wallet that cannot encrypt. DC_API and DC_API_JWT answer through the W3C Digital Credentials API instead, and need the relying party to name the origin of its page in every request. The setting is a floor for encryption: a request may name another mode, but cannot drop encryption where the setting requires it. Available values are as follows:
  • DIRECT_POST: The wallet posts the response parameters unencrypted to the response URI.
  • DIRECT_POST_JWT: The wallet posts the response as an encrypted JWT, in the response parameter, to the response URI. The key is an ephemeral P-256 key for ECDH-ES that CAS generates for each request; the content may be encrypted with A128GCM or A256GCM.
  • DC_API: The wallet answers through the W3C Digital Credentials API to the relying party's page, which hands the answer to CAS. The relying party names the origin of its page in each presentation request.
  • DC_API_JWT: As DC_API, with the answer encrypted as for DIRECT_POST_JWT, as HAIP requires.
Type
OidcVerifiableCredentialsPresentationProperties.ResponseModes
Default
DIRECT_POST
Defined by
OidcVerifiableCredentialsPresentationProperties

Required settings may be needed to activate or affect the feature; review them even when they have a default. Optional settings only need to be set to change a default or to turn on the behavior they control. Third party settings belong to libraries such as Spring Boot that CAS builds on; their own documentation may have more detail.

Signing & encryption

This CAS feature is able to accept signing and encryption crypto keys. In most scenarios if keys are not provided, CAS will auto-generate them. The following instructions apply if you wish to manually and beforehand create the signing and encryption keys.

Note that if you are asked to create a JWK of a certain size for the key, you are to use the following set of commands to generate the token:



1
2



wget https://raw.githubusercontent.com/apereo/cas/master/etc/jwk-gen.jar
java -jar jwk-gen.jar -t oct -s [size]

The outcome would be similar to:



1
2
3
4
5



{
  "kty": "oct",
  "kid": "...",
  "k": "..."
}

The generated value for k needs to be assigned to the relevant CAS settings. Note that keys generated via the above algorithm are processed by CAS using the Advanced Encryption Standard (AES) algorithm which is a specification for the encryption of electronic data established by the U.S. National Institute of Standards and Technology.

Groovy scripting

CAS takes advantage of Apache Groovy in forms of either embedded or external scripts that allow one to, by default, dynamically build constructs, attributes, access strategies and a lot more. To activate the functionality described here, you may need to prepare CAS to support and integrate with Apache Groovy.

Please review this guide to configure your build.

Notes on configuration

Configuration Metadata

The collection of configuration properties listed in this section are automatically generated from the CAS source and components that contain the actual field definitions, types, descriptions, modules, etc. This metadata may not always be 100% accurate, or could be lacking details and sufficient explanations.

Be Selective

This section is meant as a guide only. Do NOT copy/paste the entire collection of settings into your CAS configuration; rather pick only the properties that you need. Do NOT enable settings unless you are certain of their purpose and do NOT copy settings into your configuration only to keep them as reference. All these ideas lead to upgrade headaches, maintenance nightmares and premature aging.

YAGNI

Note that for nearly ALL use cases, declaring and configuring properties listed here is sufficient. You should NOT have to explicitly massage a CAS XML/Java/etc configuration file to design an authentication handler, create attribute release policies, etc. CAS at runtime will auto-configure all required changes for you. If you are unsure about the meaning of a given CAS setting, do NOT turn it on without hesitation. Review the codebase or better yet, ask questions to clarify the intended behavior.

Naming Convention

Property names can be specified in very relaxed terms. For instance cas.someProperty, cas.some-property, cas.some_property are all valid names. While all forms are accepted by CAS, there are certain components (in CAS and other frameworks used) whose activation at runtime is conditional on a property value, where this property is required to have been specified in CAS configuration using kebab case. This is both true for properties that are owned by CAS as well as those that might be presented to the system via an external library or framework such as Spring Boot, etc.

:information_source: Note

When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value. The only possible exception to this rule is when naming actuator endpoints; The name of the actuator endpoints (i.e. ssoSessions) MUST remain in camelCase mode.

Settings and properties that are controlled by the CAS platform directly always begin with the prefix cas. All other settings are controlled and provided to CAS via other underlying frameworks and may have their own schemas and syntax. BE CAREFUL with the distinction. Unrecognized properties are rejected by CAS and/or frameworks upon which CAS depends. This means if you somehow misspell a property definition or fail to adhere to the dot-notation syntax and such, your setting is entirely refused by CAS and likely the feature it controls will never be activated in the way you intend.

Validation

Configuration properties are automatically validated on CAS startup to report issues with configuration binding, especially if defined CAS settings cannot be recognized or validated by the configuration schema. Additional validation processes are also handled via Configuration Metadata and property migrations applied automatically on startup by Spring Boot and family.

Indexed Settings

CAS settings able to accept multiple values are typically documented with an index, such as cas.some.setting[0]=value. The index [0] is meant to be incremented by the adopter to allow for distinct multiple configuration blocks.

Endpoints

The following endpoints are typically involved in the verifiable credential issuance flow.

Issuer Metadata

Publishes issuer capabilities and supported credential configuration metadata.



1



GET /oidc/.well-known/openid-credential-issuer

This endpoint generally advertises:

  • The credential issuer identifier.
  • The credential endpoint.
  • The nonce endpoint, when supported.
  • Supported credential configurations.
  • Supported formats and signing algorithms.
  • How wallets should present the issuer (display: name, language and logo), taken from issuer display settings in CAS configuration; without it wallets show the issuer as unnamed.

Metadata Location

OpenID4VCI locates the credential issuer metadata by inserting /.well-known/openid-credential-issuer into the issuer identifier between the host and the path, rather than by appending it the way OpenID Connect Discovery does; RFC 8414 locates the authorization server metadata the same way. A wallet issued against https://sso.example.org/cas/oidc therefore asks for:



1
2



GET https://sso.example.org/.well-known/openid-credential-issuer/cas/oidc
GET https://sso.example.org/.well-known/oauth-authorization-server/cas/oidc

Verifiers other than CAS locate the keys that sign issued credentials the same way, through the JWT VC Issuer Metadata at https://sso.example.org/.well-known/jwt-vc-issuer/cas/oidc, which names the issuer and points to the OpenID Connect JWKS:



1
2
3
4



{
  "issuer": "https://sso.example.org/cas/oidc",
  "jwks_uri": "https://sso.example.org/cas/oidc/jwks"
}

CAS is normally deployed under the /cas context path, so neither request reaches the application at all and the servlet container answers with its own 404. Route them onto the paths CAS serves, either in the proxy that fronts CAS or with the embedded Tomcat rewrite valve. The valve must be registered on the engine, which runs before a context is selected.

The rewrite rule would be similar to:



1



RewriteRule ^/\.well-known/(openid-credential-issuer|oauth-authorization-server|openid-configuration|jwt-vc-issuer)(/.+)$ $2/.well-known/$1 [L]

Naming the documents explicitly, rather than matching every well-known path, leaves unrelated ones such as /.well-known/acme-challenge/<token> untouched.

A wallet that cannot resolve this metadata may not begin issuance at all.

Signed Metadata

A wallet that asks for application/jwt in its Accept header, preferring it at least as much as JSON, receives the issuer metadata as a JWT of type openidvci-issuer-metadata+jwt, signed with the issuer signing key and carrying its x5c certificate chain, if any, without the trust anchor, as the High Assurance Interoperability Profile requires. Every metadata parameter is a top-level claim, next to sub and iss, both set to the credential issuer, iat and exp:



1
2
3
4
5
6
7
8



{
  "alg": "ES256",
  "typ": "openidvci-issuer-metadata+jwt",
  "kid": "cas-vc-signing",
  "x5c": [
    "MIIB..."
  ]
}





1
2
3
4
5
6
7
8
9
10
11
12
13



{
  "sub": "https://sso.example.org/cas/oidc",
  "iss": "https://sso.example.org/cas/oidc",
  "iat": 1791238400,
  "exp": 1791324800,
  "credential_issuer": "https://sso.example.org/cas/oidc",
  "credential_endpoint": "https://sso.example.org/cas/oidc/oidcVcCredential",
  "credential_configurations_supported": {
    "UniversityDegree": {
      "format": "dc+sd-jwt"
    }
  }
}

Other requests receive the unsigned JSON document. How long signed metadata remains valid is controlled in CAS settings:

The following settings and properties are available from the CAS configuration catalog:

cas.authn.oidc.vc.metadata.include-claimsWhether claims should be included in the metadata.
true

Whether claims should be included in the metadata.

Type
Boolean
Default
true
Defined by
OidcVerifiableCredentialsMetadataProperties
cas.authn.oidc.vc.metadata.signed-metadata-expirationHow long signed credential issuer metadata, returned to wallets that ask for application/jwt , remains valid, advertised as its exp claim.
P1D
Duration

How long signed credential issuer metadata, returned to wallets that ask for application/jwt, remains valid, advertised as its exp claim.

Type
String
Default
P1D
Defined by
OidcVerifiableCredentialsMetadataProperties

Required settings may be needed to activate or affect the feature; review them even when they have a default. Optional settings only need to be set to change a default or to turn on the behavior they control. Third party settings belong to libraries such as Spring Boot that CAS builds on; their own documentation may have more detail.

Notes on configuration

Configuration Metadata

The collection of configuration properties listed in this section are automatically generated from the CAS source and components that contain the actual field definitions, types, descriptions, modules, etc. This metadata may not always be 100% accurate, or could be lacking details and sufficient explanations.

Be Selective

This section is meant as a guide only. Do NOT copy/paste the entire collection of settings into your CAS configuration; rather pick only the properties that you need. Do NOT enable settings unless you are certain of their purpose and do NOT copy settings into your configuration only to keep them as reference. All these ideas lead to upgrade headaches, maintenance nightmares and premature aging.

YAGNI

Note that for nearly ALL use cases, declaring and configuring properties listed here is sufficient. You should NOT have to explicitly massage a CAS XML/Java/etc configuration file to design an authentication handler, create attribute release policies, etc. CAS at runtime will auto-configure all required changes for you. If you are unsure about the meaning of a given CAS setting, do NOT turn it on without hesitation. Review the codebase or better yet, ask questions to clarify the intended behavior.

Naming Convention

Property names can be specified in very relaxed terms. For instance cas.someProperty, cas.some-property, cas.some_property are all valid names. While all forms are accepted by CAS, there are certain components (in CAS and other frameworks used) whose activation at runtime is conditional on a property value, where this property is required to have been specified in CAS configuration using kebab case. This is both true for properties that are owned by CAS as well as those that might be presented to the system via an external library or framework such as Spring Boot, etc.

:information_source: Note

When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value. The only possible exception to this rule is when naming actuator endpoints; The name of the actuator endpoints (i.e. ssoSessions) MUST remain in camelCase mode.

Settings and properties that are controlled by the CAS platform directly always begin with the prefix cas. All other settings are controlled and provided to CAS via other underlying frameworks and may have their own schemas and syntax. BE CAREFUL with the distinction. Unrecognized properties are rejected by CAS and/or frameworks upon which CAS depends. This means if you somehow misspell a property definition or fail to adhere to the dot-notation syntax and such, your setting is entirely refused by CAS and likely the feature it controls will never be activated in the way you intend.

Validation

Configuration properties are automatically validated on CAS startup to report issues with configuration binding, especially if defined CAS settings cannot be recognized or validated by the configuration schema. Additional validation processes are also handled via Configuration Metadata and property migrations applied automatically on startup by Spring Boot and family.

Indexed Settings

CAS settings able to accept multiple values are typically documented with an index, such as cas.some.setting[0]=value. The index [0] is meant to be incremented by the adopter to allow for distinct multiple configuration blocks.

Token Endpoint Authentication

The pre-authorized code grant carries no client credentials. CAS authenticates the exchange from the pre-authorized_code and grant_type request parameters themselves, and the client bound to the credential offer is recorded on the pre-authorization code when the offer is created.

A wallet decides how to authenticate from the authorization server metadata, so the token endpoint has to advertise that it accepts requests with no client authentication. CAS includes none in authentication methods supported for the token endpoint by default for this reason. If the list is narrowed, keep none in it; without it a wallet picks one of the credentialed methods it sees instead and the exchange is rejected, because the wallet has no client registration to authenticate with.

For the same reason the authorization server metadata advertises pre-authorized_grant_anonymous_access_supported as true whenever the pre-authorized code grant is listed in grant_types_supported. A wallet that finds no such value assumes false and may refuse to redeem the code without a client_id it does not have.

In the authorization code flow, wallets authenticate at the pushed authorization request and token endpoints with a wallet attestation, as the High Assurance Interoperability Profile requires, using attestation-based client authentication.

Credential Endpoint

Issues a verifiable credential to the wallet once the access token, proof, and requested credential configuration have been validated.



1



POST /oidc/oidcVcCredential

This endpoint expects:

  • An access token, presented in the Authorization header as Bearer ... or, when the token response named the token type DPoP, as DPoP ... per RFC 9449. An access_token or token request parameter is accepted as well, as it is elsewhere in CAS. A DPoP-bound token must be accompanied by a DPoP proof header bound to that token; a request without one, or with a proof that does not verify, is answered with 401 and WWW-Authenticate: DPoP error="invalid_dpop_proof". A proof may not be reused. Once DPoP nonces are turned on, the proof must also carry one, or the request is answered with 401, use_dpop_nonce and a fresh nonce in the DPoP-Nonce header.
  • The requested credential. When the token response returned credential_identifiers in its authorization details, the request must name one of them with credential_identifier; otherwise it names a credential_configuration_id. The two are mutually exclusive, and using the one that does not apply is invalid_credential_request. Pre-authorized code token responses return no authorization details, so those requests use credential_configuration_id.
  • A proofs object holding one or more proof JWTs, each carrying a nonce claim, or exactly one key attestation as an attestation proof (see Key Attestations).

The endpoint body is expected as:



1
2
3
4
5
6
7
8



{
  "credential_configuration_id": "myorg",
  "proofs": {
    "jwt": [
      "eyJ0eXAiOiJvcGVuaWQ0dmNpL..."
    ]
  }
}

Each proof must be signed with one of the proof-signing-alg-values-supported of the requested credential configuration and name the holder key by one of its cryptographic-binding-methods-supported:

Proof header Binding method Holder key
jwk jwk The key itself. A kid sent alongside it is ignored.
x5c jwk The public key of the first certificate, which must be within its validity period.
kid did:jwk The key encoded in the did:jwk DID URL. Other DID methods cannot be resolved and are refused.

RSA, EC and Ed25519 (EdDSA) keys are accepted. A proof that does not satisfy the configuration is answered with invalid_proof. The defaults are ES256 and RS256 with the jwk binding method.

There is no separate batch credential endpoint. A batch is a single credential request carrying several proofs, and the response holds one credential per proof, all of the same credential configuration. How many proofs are accepted is advertised as batch_credential_issuance in the issuer metadata and controlled by a batch size limit defined in CAS configuration.

The response is:



1
2
3
4
5
6
7



{
  "credentials": [
    {
      "credential": "eyJhbGciOiJSUzI1NiIs..."
    }
  ]
}

Errors carry the codes of OpenID4VCI 1.0 section 8.3.1.2: a credential_identifier the token response did not return is unknown_credential_identifier, a credential configuration CAS does not publish is unknown_credential_configuration, one it publishes but will not issue to this client or access token is credential_request_denied, and a proof that cannot be accepted is invalid_proof, or invalid_nonce when only its nonce is stale.

Encrypted Requests and Responses

Credential requests and responses may be encrypted on top of TLS, as described by OpenID4VCI 1.0 section 10. Once turned on in CAS settings, the issuer metadata advertises both directions:



1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32



{
  "credential_request_encryption": {
    "jwks": {
      "keys": [
        {
          "kty": "RSA",
          "kid": "cas-4bKkzQdW",
          "use": "enc",
          "alg": "RSA-OAEP-256",
          "n": "sLx5PUdqNoSl...",
          "e": "AQAB"
        }
      ]
    },
    "enc_values_supported": [
      "A128GCM",
      "A256GCM"
    ],
    "encryption_required": false
  },
  "credential_response_encryption": {
    "alg_values_supported": [
      "ECDH-ES",
      "RSA-OAEP-256"
    ],
    "enc_values_supported": [
      "A128GCM",
      "A256GCM"
    ],
    "encryption_required": false
  }
}

Requests are encrypted to the current encryption keys of the CAS OpenID Connect keystore: an RSA key is published for RSA-OAEP-256 and an elliptic curve key for ECDH-ES. An encrypted request is sent as application/jwt, a JWE whose payload is the credential request and whose kid header names the key. To receive an encrypted response, the wallet adds the key to encrypt it to, with its alg, and the content encryption algorithm:



1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19



{
  "credential_configuration_id": "myorg",
  "proofs": {
    "jwt": [
      "eyJ0eXAiOiJvcGVuaWQ0dmNpL..."
    ]
  },
  "credential_response_encryption": {
    "jwk": {
      "kty": "EC",
      "crv": "P-256",
      "kid": "wallet",
      "alg": "ECDH-ES",
      "x": "N5rsOYN3J44MRbUT...",
      "y": "IZKX5LyZlKGTHHE8..."
    },
    "enc": "A256GCM"
  }
}

A request asking for an encrypted response must itself be encrypted, so that the response key cannot be swapped on the way. The response is then returned as application/jwt, encrypted to that key and carrying its kid; error responses are never encrypted. Parameters that cannot be used, compression (zip) which CAS does not support, or a missing credential_response_encryption when encrypted responses are required are answered with invalid_encryption_parameters; a request that cannot be decrypted, or a plain request when encrypted requests are required, with invalid_credential_request.

The following settings and properties are available from the CAS configuration catalog:

cas.authn.oidc.vc.issuer.encryption.alg-values-supportedJWE key management algorithms ( alg ) the issuer accepts in the key a wallet supplies for response encryption.
no default

JWE key management algorithms (alg) the issuer accepts in the key a wallet supplies for response encryption.

Type
List<String>
Default
none
Defined by
OidcVerifiableCredentialEncryptionProperties
cas.authn.oidc.vc.issuer.encryption.enabledWhether the issuer metadata advertises credential_request_encryption and credential_response_encryption , and the credential endpoint accepts encrypted requests and encrypts responses when asked to.
false

Whether the issuer metadata advertises credential_request_encryption and credential_response_encryption, and the credential endpoint accepts encrypted requests and encrypts responses when asked to. The current encryption keys of the OpenID Connect keystore are published for request encryption: an RSA key is used with RSA-OAEP-256 and an elliptic curve key with ECDH-ES.

Type
Boolean
Default
false
Defined by
OidcVerifiableCredentialEncryptionProperties
cas.authn.oidc.vc.issuer.encryption.enc-values-supportedJWE content encryption algorithms ( enc ) accepted for encrypted requests and offered for encrypted responses.
no default

JWE content encryption algorithms (enc) accepted for encrypted requests and offered for encrypted responses.

Type
List<String>
Default
none
Defined by
OidcVerifiableCredentialEncryptionProperties
cas.authn.oidc.vc.issuer.encryption.request-encryption-requiredWhether every credential request must be encrypted.
false

Whether every credential request must be encrypted.

Type
Boolean
Default
false
Defined by
OidcVerifiableCredentialEncryptionProperties
cas.authn.oidc.vc.issuer.encryption.response-encryption-requiredWhether every credential response must be encrypted, so that a wallet has to supply credential_response_encryption with each request.
false

Whether every credential response must be encrypted, so that a wallet has to supply credential_response_encryption with each request.

Type
Boolean
Default
false
Defined by
OidcVerifiableCredentialEncryptionProperties

Required settings may be needed to activate or affect the feature; review them even when they have a default. Optional settings only need to be set to change a default or to turn on the behavior they control. Third party settings belong to libraries such as Spring Boot that CAS builds on; their own documentation may have more detail.

Notes on configuration

Configuration Metadata

The collection of configuration properties listed in this section are automatically generated from the CAS source and components that contain the actual field definitions, types, descriptions, modules, etc. This metadata may not always be 100% accurate, or could be lacking details and sufficient explanations.

Be Selective

This section is meant as a guide only. Do NOT copy/paste the entire collection of settings into your CAS configuration; rather pick only the properties that you need. Do NOT enable settings unless you are certain of their purpose and do NOT copy settings into your configuration only to keep them as reference. All these ideas lead to upgrade headaches, maintenance nightmares and premature aging.

YAGNI

Note that for nearly ALL use cases, declaring and configuring properties listed here is sufficient. You should NOT have to explicitly massage a CAS XML/Java/etc configuration file to design an authentication handler, create attribute release policies, etc. CAS at runtime will auto-configure all required changes for you. If you are unsure about the meaning of a given CAS setting, do NOT turn it on without hesitation. Review the codebase or better yet, ask questions to clarify the intended behavior.

Naming Convention

Property names can be specified in very relaxed terms. For instance cas.someProperty, cas.some-property, cas.some_property are all valid names. While all forms are accepted by CAS, there are certain components (in CAS and other frameworks used) whose activation at runtime is conditional on a property value, where this property is required to have been specified in CAS configuration using kebab case. This is both true for properties that are owned by CAS as well as those that might be presented to the system via an external library or framework such as Spring Boot, etc.

:information_source: Note

When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value. The only possible exception to this rule is when naming actuator endpoints; The name of the actuator endpoints (i.e. ssoSessions) MUST remain in camelCase mode.

Settings and properties that are controlled by the CAS platform directly always begin with the prefix cas. All other settings are controlled and provided to CAS via other underlying frameworks and may have their own schemas and syntax. BE CAREFUL with the distinction. Unrecognized properties are rejected by CAS and/or frameworks upon which CAS depends. This means if you somehow misspell a property definition or fail to adhere to the dot-notation syntax and such, your setting is entirely refused by CAS and likely the feature it controls will never be activated in the way you intend.

Validation

Configuration properties are automatically validated on CAS startup to report issues with configuration binding, especially if defined CAS settings cannot be recognized or validated by the configuration schema. Additional validation processes are also handled via Configuration Metadata and property migrations applied automatically on startup by Spring Boot and family.

Indexed Settings

CAS settings able to accept multiple values are typically documented with an index, such as cas.some.setting[0]=value. The index [0] is meant to be incremented by the adopter to allow for distinct multiple configuration blocks.

Nonce Endpoint

Produces a fresh c_nonce that may be used by the wallet in a later proof for the credential request.



1



POST /oidc/oidcVcNonce

This endpoint returns c_nonce. The challenge is never returned from the token endpoint. Once DPoP nonces are turned on, the response also carries a DPoP nonce in its DPoP-Nonce header, for the DPoP proof of the credential request.

Notification Endpoint

Receives notifications from the wallet about the credentials of a credential response, as described by OpenID4VCI 1.0 section 11. Each credential response carries a notification_id, and the issuer metadata advertises the endpoint as notification_endpoint.



1



POST /oidc/oidcVcNotification

The request carries the access token that obtained the credentials, checked as it is at the credential endpoint, and a JSON body:



1
2
3
4
5



{
  "notification_id": "TST-1-...",
  "event": "credential_failure",
  "event_description": "Could not store the Credential. Out of storage."
}

The event is one of credential_accepted, credential_failure or credential_deleted. A notification is answered with 204 and recorded in the CAS audit log as OIDC_VERIFIABLE_CREDENTIAL_NOTIFICATION; sending the same notification again succeeds again. A notification id that is unknown, has expired with the access token, or was issued to another client or user is answered with invalid_notification_id, and a malformed request, an unknown event or an event_description with characters outside the permitted ASCII set with invalid_notification_request.

Deferred Credential Endpoint

Hands out credentials whose issuance was deferred, as described by OpenID4VCI 1.0 section 9. A credential configuration opts in with its deferred-issuance setting, and the issuer metadata then advertises the endpoint as deferred_credential_endpoint. A credential request for such a configuration is validated as usual, proofs included, and answered with 202:



1
2
3
4



{
  "transaction_id": "TST-1-...",
  "interval": 300
}

The transaction is kept in the ticket registry, bound to the client and the user of the access token, with the holder public keys of the validated proofs and nothing else. It stays pending until it is approved or denied through the actuator endpoint below. The wallet asks for the credentials with an access token of the same client and user that still authorizes the credential configuration, such as the original token or one refreshed from it, waiting at least interval seconds between attempts:



1



POST /oidc/oidcVcDeferredCredential





1
2
3



{
  "transaction_id": "TST-1-..."
}

A pending transaction is answered with 202 and the same transaction_id. Once approved, the answer is 200 with the credentials and a notification_id, built at that moment from the user’s attributes, and the transaction_id can no longer be used. A denied transaction is answered with credential_request_denied. A transaction_id that is unknown, expired, already used, or was started by another client or user is answered with invalid_transaction_id. The request may be encrypted and may carry its own credential_response_encryption, as at the credential endpoint, whatever the credential request asked for.

The stateless ticket registry cannot keep transactions, so with it credentials of these configurations are issued immediately.

The following settings and properties are available from the CAS configuration catalog:

cas.authn.oidc.vc.issuer.deferred-issuance.intervalHow long a wallet should wait before asking for the credentials of a deferred transaction again, advertised as the interval of the credential response.
PT5M
Duration

How long a wallet should wait before asking for the credentials of a deferred transaction again, advertised as the interval of the credential response.

Type
String
Default
PT5M
Defined by
OidcVerifiableCredentialDeferredIssuanceProperties
cas.authn.oidc.vc.issuer.deferred-issuance.time-to-liveHow long a deferred transaction is kept.
P7D
Duration

How long a deferred transaction is kept. A transaction that is neither approved and collected nor denied within this time expires, and the wallet is told its transaction_id is invalid.

Type
String
Default
P7D
Defined by
OidcVerifiableCredentialDeferredIssuanceProperties

Required settings may be needed to activate or affect the feature; review them even when they have a default. Optional settings only need to be set to change a default or to turn on the behavior they control. Third party settings belong to libraries such as Spring Boot that CAS builds on; their own documentation may have more detail.

Notes on configuration

Configuration Metadata

The collection of configuration properties listed in this section are automatically generated from the CAS source and components that contain the actual field definitions, types, descriptions, modules, etc. This metadata may not always be 100% accurate, or could be lacking details and sufficient explanations.

Be Selective

This section is meant as a guide only. Do NOT copy/paste the entire collection of settings into your CAS configuration; rather pick only the properties that you need. Do NOT enable settings unless you are certain of their purpose and do NOT copy settings into your configuration only to keep them as reference. All these ideas lead to upgrade headaches, maintenance nightmares and premature aging.

YAGNI

Note that for nearly ALL use cases, declaring and configuring properties listed here is sufficient. You should NOT have to explicitly massage a CAS XML/Java/etc configuration file to design an authentication handler, create attribute release policies, etc. CAS at runtime will auto-configure all required changes for you. If you are unsure about the meaning of a given CAS setting, do NOT turn it on without hesitation. Review the codebase or better yet, ask questions to clarify the intended behavior.

Naming Convention

Property names can be specified in very relaxed terms. For instance cas.someProperty, cas.some-property, cas.some_property are all valid names. While all forms are accepted by CAS, there are certain components (in CAS and other frameworks used) whose activation at runtime is conditional on a property value, where this property is required to have been specified in CAS configuration using kebab case. This is both true for properties that are owned by CAS as well as those that might be presented to the system via an external library or framework such as Spring Boot, etc.

:information_source: Note

When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value. The only possible exception to this rule is when naming actuator endpoints; The name of the actuator endpoints (i.e. ssoSessions) MUST remain in camelCase mode.

Settings and properties that are controlled by the CAS platform directly always begin with the prefix cas. All other settings are controlled and provided to CAS via other underlying frameworks and may have their own schemas and syntax. BE CAREFUL with the distinction. Unrecognized properties are rejected by CAS and/or frameworks upon which CAS depends. This means if you somehow misspell a property definition or fail to adhere to the dot-notation syntax and such, your setting is entirely refused by CAS and likely the feature it controls will never be activated in the way you intend.

Validation

Configuration properties are automatically validated on CAS startup to report issues with configuration binding, especially if defined CAS settings cannot be recognized or validated by the configuration schema. Additional validation processes are also handled via Configuration Metadata and property migrations applied automatically on startup by Spring Boot and family.

Indexed Settings

CAS settings able to accept multiple values are typically documented with an index, such as cas.some.setting[0]=value. The index [0] is meant to be incremented by the adopter to allow for distinct multiple configuration blocks.

Pending transactions are listed, approved and denied through an actuator endpoint, and each decision is recorded in the CAS audit log as OIDC_VERIFIABLE_CREDENTIAL_DEFERRED_ISSUANCE:

oidcVcDeferred
CAS endpoint2 operationsNot exposed by defaultcas-server-support-oidc-vc
1

Include the module that provides this endpoint in the WAR overlay:

Show in CAS Initializr Generate CAS Server WAR Overlay 


1
2
3
4
5



<dependency>
    <groupId>org.apereo.cas</groupId>
    <artifactId>cas-server-support-oidc-vc</artifactId>
    <version>${cas.version}</version>
</dependency>





1



implementation "org.apereo.cas:cas-server-support-oidc-vc:${project.'cas.version'}"





1
2
3
4
5
6
7
8
9



dependencyManagement {
    imports {
        mavenBom "org.apereo.cas:cas-server-support-bom:${project.'cas.version'}"
    }
}

dependencies {
    implementation "org.apereo.cas:cas-server-support-oidc-vc"
}





1
2
3
4
5
6
7
8
9
10



dependencies {
    /*
        The following platform references are included automatically and are listed for reference only.

        implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")
        implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
        
    */
    implementation "org.apereo.cas:cas-server-support-oidc-vc"
}
2

Turn the endpoint on and expose it over the web. One entry covers every operation. By default only info, health and status are exposed.



1
2



management.endpoint.oidcVcDeferred.access=UNRESTRICTED
management.endpoints.web.exposure.include=oidcVcDeferred

Endpoints may be mapped to other paths. For example, to serve health at healthcheck:



1



management.endpoints.web.path-mapping.health=healthcheck

Credential Offer Endpoint

Exposes a prepared credential offer for a previously-created issuance transaction.



1



GET /oidc/oidcVcCredentialOffer/{transactionId}

This endpoint does not establish subject identity on its own. Instead, it dereferences a short-lived server-side issuance transaction and returns the corresponding credential offer document.

Trusted Transaction Creation Endpoint

Creates a server-side issuance transaction for a known subject and returns an opaque transaction identifier and a wallet-facing offer URI.



1



POST /oidc/oidcVcCredentialOfferTransactions

The endpoint body is expected to be:



1
2
3
4
5
6



{
  "principal": "...",
  "credentialConfigurationIds": [
    "..."
  ]
}

The response carries the offer URI and the deep link a wallet opens, typically rendered as a QR code:



1
2
3
4
5
6



{
  "transactionId": "...",
  "credentialOfferUri": "https://sso.example.org/cas/oidc/oidcVcCredentialOffer/...",
  "credentialOfferLink": "openid-credential-offer://?credential_offer_uri=https%3A%2F%2Fsso.example.org%2Fcas%2Foidc%2FoidcVcCredentialOffer%2F...",
  "txCode": "..."
}

This endpoint is intended for trusted callers such as:

  • Administrative tools
  • Internal backend services & APIs
  • Authenticated CAS user interfaces

This endpoint is protected and should not be exposed as an anonymous wallet-facing API.

Token Endpoint

Exchanges an authorization artifact, such as a pre-authorized code, for an access token that may later be used at the credential endpoint.



1



POST /oidc/token

When used for verifiable credential issuance, this endpoint may:

  • Accept the pre-authorized_code grant.
  • Require a tx_code.
  • Return the authorization_details the token was granted, with their credential_identifiers.
  • Produce an access token that is scoped to credential issuance.

Example request:



1
2
3
4
5
6



POST /oidc/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:pre-authorized_code&
pre-authorized_code=L0Qw0sT6dP5P7l7xM0H2AqQ0g9vM2j5fByuYwQ&
tx_code=TST-1234

Nonce Proof

Proofs are expected to carry a nonce claim. The nonce lets CAS tell whether the wallet’s proof is fresh, instead of a replay. In OIDC4VCI, the wallet sends a proof showing it controls the key the credential should be bound to, and the c_nonce is the primary defense against replay of that proof.

Without a nonce, an attacker who somehow gets hold of a previously valid proof could try to send it again and get a duplicate credential issued to the same key.

In practical terms, the flow is:

  • The wallet asks CAS for a fresh c_nonce from the nonce endpoint; the token endpoint never returns one.
  • The wallet builds its proof and includes that nonce.
  • CAS checks that the nonce matches one it issued, is still fresh, and has not already been used.
  • CAS consumes it so the same proof cannot be replayed.

The token endpoint issues the nonce. The credential endpoint enforces it while validating the proof.

Key Attestations

A wallet may vouch for the keys it wants credentials bound to with a key attestation, as described by OpenID4VCI 1.0 Appendix D: a key-attestation+jwt signed by the wallet provider that lists the attested_keys and how they are protected (key_storage, user_authentication). Key attestations are verified once trust anchors are configured in CAS settings as PEM certificates, typically those of the wallet providers that are trusted. Following HAIP 1.0, the attestation carries its signing certificate, and any intermediate certificates, in its x5c header; the chain must lead to a configured trust anchor without including it, and the signer must not be self-signed. The attestation must carry iat and, when it carries exp, must not have expired. A status claim is accepted, and logged as a warning, since its revocation status is not checked.

A key attestation can be presented in two ways:

  • In the key_attestation header of a jwt proof. The proof key must be one of the attested keys.
  • As an attestation proof, standing in for proof JWTs. Its nonce claim must carry a c_nonce issued by CAS, and one credential is issued per attested key, up to the batch size limit.


1
2
3
4
5
6
7
8



{
  "credential_configuration_id": "myorg",
  "proofs": {
    "attestation": [
      "eyJ0eXAiOiJrZXktYXR0ZXN0YXRpb24rand0Ii..."
    ]
  }
}

A credential configuration may require key attestations, and may list the key_storage and user_authentication values it accepts; an attestation must then name at least one accepted value of each list. A jwt proof without a key attestation is refused for such a configuration. The requirement is advertised in the issuer metadata as key_attestations_required, and the attestation proof type is advertised once trust anchors are configured:



1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28



{
  "proof_types_supported": {
    "jwt": {
      "proof_signing_alg_values_supported": [
        "ES256",
        "RS256"
      ],
      "key_attestations_required": {
        "key_storage": [
          "iso_18045_high",
          "iso_18045_moderate"
        ]
      }
    },
    "attestation": {
      "proof_signing_alg_values_supported": [
        "ES256",
        "RS256"
      ],
      "key_attestations_required": {
        "key_storage": [
          "iso_18045_high",
          "iso_18045_moderate"
        ]
      }
    }
  }
}

A key attestation that fails any of these checks is answered with invalid_proof, while a missing, unknown or reused nonce in an attestation proof is answered with invalid_nonce.

Authorization Code Flow

The Authorization Code Flow allows a wallet to obtain authorization to receive one or more verifiable credentials through a standard OAuth 2.0/OpenID Connect authorization process. Unlike the Pre-Authorized Code Flow, where a trusted backend initiates the issuance transaction, the Authorization Code Flow is wallet-driven. The wallet begins by sending an authorization request to the Credential Issuer’s authorization endpoint, requesting one or more credential configurations using the authorization_details parameter. The request may also include the openid scope if the wallet wishes to authenticate the end-user and receive an ID Token as part of the token response. The wallet exchanges the authorization code at the token endpoint to obtain an access token that is specifically authorized for credential issuance.

Instead of authorization details, the wallet may request a credential by the scope its credential configuration publishes in the issuer metadata, for example scope=openid UniversityDegree. Every granted scope that belongs to a credential configuration authorizes that configuration, narrowed by the service’s verifiable credentials policy. These scopes are accepted and advertised in scopes_supported without being listed among the discovery scopes. The token response then carries no credential identifiers, so the credential request names the configuration with credential_configuration_id. A wallet may use both mechanisms in one authorization request.

A refresh token issued in this flow keeps the authorization details of its code, as RFC 9396 describes, so access tokens obtained with it may request the same credentials; scopes are honored as before.

Pre-Authorized Code Flow

In pre-authorized code flows, CAS or a trusted backend prepares the issuance transaction before the wallet starts the OAuth exchange.

The general flow is:

  • A trusted caller creates an issuance transaction.
  • CAS stores the transaction and issues a pre-authorized code.
  • CAS returns a wallet-facing credential_offer_uri.
  • The wallet resolves the offer.
  • The wallet exchanges the pre-authorized code at the token endpoint.
  • CAS returns an access token.
  • The wallet calls the credential endpoint with the access token and proof.
  • CAS validates the request and issues the credential.

The pre-authorized code is single use, as OpenID4VCI requires. It is redeemed and deleted before the access token is minted, so of several concurrent exchanges of the same code exactly one succeeds and the rest are refused; the issuance transaction is removed along with it.

The stateless ticket registry cannot delete anything, so there the pre-authorized code and the nonces handed out by the nonce endpoint are not single use: each stays usable until it expires, which departs from OpenID4VCI. Keep their expiration short. Verifiable presentations are not supported with that registry.

Verifiable Presentations

CAS can also act as a verifier and ask a wallet to present a credential. A relying party creates a presentation request, and CAS returns a deep link the wallet can open, usually rendered as a QR code.

The following settings and properties are available from the CAS configuration catalog:

cas.authn.oidc.vc.presentation.client-identifier-prefixHow the wallet is expected to identify and authenticate CAS as the verifier, expressed as an OpenID4VP client identifier prefix.
REDIRECT_URI

How the wallet is expected to identify and authenticate CAS as the verifier, expressed as an OpenID4VP client identifier prefix.

REDIRECT_URI requires no key material, but requests made under it cannot be signed, so the authorization request is carried by value in the deep link and no request URI is offered. X509_SAN_DNS signs the request object with the CAS OpenID Connect signing key and requires that key to carry a certificate chain whose leaf certificate holds a dNSName subject alternative name matching the host of the verifier; only then can the request object be served by reference. X509_HASH, which the OpenID4VC High Assurance Interoperability Profile requires, signs the request object the same way and identifies CAS by the hash of the leaf certificate, so the certificate needs no particular name. Available values are as follows:
  • REDIRECT_URI: The client identifier is the verifier's response URI. Requests cannot be signed and are therefore always passed to the wallet by value.
  • X509_SAN_DNS: The client identifier is a DNS name that must match a dNSName subject alternative name in the leaf certificate used to sign the request object. It requires the CAS OIDC signing key to carry a certificate chain whose leaf certificate holds a dNSName subject alternative name matching the host of the verifier. CAS refuses to serve a request object when it does not, rather than producing one that wallets silently reject.
  • X509_HASH: The client identifier is the base64url-encoded SHA-256 hash of the DER-encoded leaf certificate used to sign the request object. It requires the CAS OIDC signing key to carry a certificate chain.
Type
OidcVerifiableCredentialsPresentationProperties.ClientIdentifierPrefixes
Default
REDIRECT_URI
Defined by
OidcVerifiableCredentialsPresentationProperties
cas.authn.oidc.vc.presentation.response-modeHow the wallet delivers its authorization response, expressed as an OpenID4VP response mode.
DIRECT_POST

How the wallet delivers its authorization response, expressed as an OpenID4VP response mode.

DIRECT_POST posts the response in the clear. DIRECT_POST_JWT has the wallet encrypt it to a key CAS generates for each request and publishes in the request's client metadata, as the OpenID4VC High Assurance Interoperability Profile requires; a presentation that arrives unencrypted is then refused, while an unencrypted error response is still accepted from a wallet that cannot encrypt. DC_API and DC_API_JWT answer through the W3C Digital Credentials API instead, and need the relying party to name the origin of its page in every request. The setting is a floor for encryption: a request may name another mode, but cannot drop encryption where the setting requires it. Available values are as follows:
  • DIRECT_POST: The wallet posts the response parameters unencrypted to the response URI.
  • DIRECT_POST_JWT: The wallet posts the response as an encrypted JWT, in the response parameter, to the response URI. The key is an ephemeral P-256 key for ECDH-ES that CAS generates for each request; the content may be encrypted with A128GCM or A256GCM.
  • DC_API: The wallet answers through the W3C Digital Credentials API to the relying party's page, which hands the answer to CAS. The relying party names the origin of its page in each presentation request.
  • DC_API_JWT: As DC_API, with the answer encrypted as for DIRECT_POST_JWT, as HAIP requires.
Type
OidcVerifiableCredentialsPresentationProperties.ResponseModes
Default
DIRECT_POST
Defined by
OidcVerifiableCredentialsPresentationProperties

Required settings may be needed to activate or affect the feature; review them even when they have a default. Optional settings only need to be set to change a default or to turn on the behavior they control. Third party settings belong to libraries such as Spring Boot that CAS builds on; their own documentation may have more detail.

Notes on configuration

Configuration Metadata

The collection of configuration properties listed in this section are automatically generated from the CAS source and components that contain the actual field definitions, types, descriptions, modules, etc. This metadata may not always be 100% accurate, or could be lacking details and sufficient explanations.

Be Selective

This section is meant as a guide only. Do NOT copy/paste the entire collection of settings into your CAS configuration; rather pick only the properties that you need. Do NOT enable settings unless you are certain of their purpose and do NOT copy settings into your configuration only to keep them as reference. All these ideas lead to upgrade headaches, maintenance nightmares and premature aging.

YAGNI

Note that for nearly ALL use cases, declaring and configuring properties listed here is sufficient. You should NOT have to explicitly massage a CAS XML/Java/etc configuration file to design an authentication handler, create attribute release policies, etc. CAS at runtime will auto-configure all required changes for you. If you are unsure about the meaning of a given CAS setting, do NOT turn it on without hesitation. Review the codebase or better yet, ask questions to clarify the intended behavior.

Naming Convention

Property names can be specified in very relaxed terms. For instance cas.someProperty, cas.some-property, cas.some_property are all valid names. While all forms are accepted by CAS, there are certain components (in CAS and other frameworks used) whose activation at runtime is conditional on a property value, where this property is required to have been specified in CAS configuration using kebab case. This is both true for properties that are owned by CAS as well as those that might be presented to the system via an external library or framework such as Spring Boot, etc.

:information_source: Note

When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value. The only possible exception to this rule is when naming actuator endpoints; The name of the actuator endpoints (i.e. ssoSessions) MUST remain in camelCase mode.

Settings and properties that are controlled by the CAS platform directly always begin with the prefix cas. All other settings are controlled and provided to CAS via other underlying frameworks and may have their own schemas and syntax. BE CAREFUL with the distinction. Unrecognized properties are rejected by CAS and/or frameworks upon which CAS depends. This means if you somehow misspell a property definition or fail to adhere to the dot-notation syntax and such, your setting is entirely refused by CAS and likely the feature it controls will never be activated in the way you intend.

Validation

Configuration properties are automatically validated on CAS startup to report issues with configuration binding, especially if defined CAS settings cannot be recognized or validated by the configuration schema. Additional validation processes are also handled via Configuration Metadata and property migrations applied automatically on startup by Spring Boot and family.

Indexed Settings

CAS settings able to accept multiple values are typically documented with an index, such as cas.some.setting[0]=value. The index [0] is meant to be incremented by the adopter to allow for distinct multiple configuration blocks.

The relying party creates the request with:



1



POST /oidc/oidcVcPresentationRequest





1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25



{
  "credentials": [
    {
      "id": "university-degree",
      "format": "dc+sd-jwt",
      "vct_values": [
        "https://sso.example.org/cas/oidc/oidcVcCredentialType/UniversityDegreeCredential"
      ],
      "claims": [
        {
          "path": [
            "given_name"
          ]
        },
        {
          "path": [
            "email"
          ],
          "required": false
        }
      ]
    }
  ],
  "redirect_uri": "https://app.example.org/presentation/callback"
}

Claims are required unless marked otherwise. DCQL has no per-claim flag, so optional claims are expressed with claim_sets: every claim first, then the required ones alone, or each optional claim on its own when none is required. The wallet returns the first combination it can satisfy, and CAS accepts any of them.

Wallets may bind credentials to EC, RSA or Ed25519 keys. CAS advertises and accepts the key binding algorithms ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384, PS512 and Ed25519 (also accepted as EdDSA), and advertises the signing algorithms of its dc+sd-jwt credential configurations for the credential itself.

The optional redirect_uri enables a same-device flow and must be registered for the client creating the request. After the wallet answers, CAS sends it to that URI with a fresh response_code in the fragment, as OpenID4VP recommends against session fixation, and releases the outcome only when the relying party presents that code. Without a redirect_uri, as in a cross-device flow with a QR code, the relying party polls for the outcome instead.

With response mode set to DIRECT_POST_JWT, the wallet encrypts its response, as the OpenID4VC High Assurance Interoperability Profile requires. CAS generates an ephemeral P-256 key for each request and publishes it in the request’s client metadata, along with the content encryption algorithms it accepts:



1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19



{
  "jwks": {
    "keys": [
      {
        "kty": "EC",
        "crv": "P-256",
        "kid": "TST-1-...",
        "use": "enc",
        "alg": "ECDH-ES",
        "x": "...",
        "y": "..."
      }
    ]
  },
  "encrypted_response_enc_values_supported": [
    "A128GCM",
    "A256GCM"
  ]
}

The wallet then posts a single response parameter: a JWE, encrypted with ECDH-ES to that key and naming it with kid, whose payload holds vp_token and state. A presentation posted in the clear is refused for such a request; an error response in the clear is still accepted from a wallet that cannot encrypt, as OpenID4VP allows. The default, DIRECT_POST, posts the response unencrypted.

A relying party may also choose per request by adding "response_mode": "direct_post.jwt" (or "direct_post") to the presentation request. The setting acts as a floor: a request may ask for an encrypted response where the deployment does not require one, but asking for direct_post where DIRECT_POST_JWT is configured is refused.

With client identifier prefix set to X509_SAN_DNS, the request object is signed and served by reference. The signing key must carry an x5c certificate chain whose leaf names the issuer host as a DNS subject alternative name. The request carries that chain in its x5c header without a trailing self-signed trust anchor, as HAIP 1.0 requires. HAIP also requires the leaf not to be self-signed; a self-signed leaf is accepted with a warning in the logs.

With the client identifier prefix set to X509_HASH, which HAIP requires of verifiers that sign their requests, the request object is signed and served by reference the same way, and the client identifier is x509_hash: followed by the base64url-encoded SHA-256 hash of the DER-encoded leaf certificate, so the leaf needs no particular name. The signing key must still carry an x5c certificate chain.

Digital Credentials API

A relying party may instead ask the wallet through the W3C Digital Credentials API, as OpenID4VP 1.0 Appendix A describes, by setting "response_mode" to dc_api or dc_api.jwt (encrypted, as the High Assurance Interoperability Profile requires) and naming the origin of its page in the presentation request:



1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20



{
  "credentials": [
    {
      "id": "university-degree",
      "format": "dc+sd-jwt",
      "vct_values": [
        "https://sso.example.org/cas/oidc/oidcVcCredentialType/UniversityDegreeCredential"
      ],
      "claims": [
        {
          "path": [
            "given_name"
          ]
        }
      ]
    }
  ],
  "response_mode": "dc_api.jwt",
  "origin": "https://app.example.org"
}

The origin must be accepted by the client’s registered redirect URIs (as https://app.example.org/), since the wallet binds the presentation to it. CAS answers with a digital_credentials_request for the page to pass, as is, as a request to navigator.credentials.get({digital: {requests: [...]}}). It is unsigned (openid4vp-v1-unsigned) under the REDIRECT_URI client identifier prefix, and signed (openid4vp-v1-signed, with expected_origins) under an x509 prefix. The page then posts what the API returned, with the request id, to the result endpoint, authenticated as the client that created the request:



1



POST /oidc/oidcVcPresentationResult





1
2
3
4
5
6



{
  "request_id": "TST-1-...",
  "data": {
    "response": "eyJhbGciOiJFQ0RILUVTIiwi..."
  }
}

For dc_api the data holds the vp_token instead of the encrypted response. CAS verifies the presentation, which must be bound to origin: followed by the origin of the page, and answers with the outcome right away, as the result endpoint would; the request is consumed. Errors the wallet reports reach the page through the API and are not posted.

The relying party that created the request collects the outcome from:



1



GET /oidc/oidcVcPresentationResult?requestId=...&response_code=...

This endpoint requires the same client authentication as the request creation endpoint, and only the client that created the request may collect its outcome; any other client, or a same-device request without its response_code, gets 404. It answers {"status": "pending"} while the wallet has not responded, and once it has, {"status": "verified"} together with the claims that were disclosed, keyed by credential query id. A wallet that declines or cannot answer posts an error response instead. Nothing authenticates that response, so anyone who saw the request could send one; it is recorded but does not end the request. The request keeps reporting pending until it expires, a valid presentation that arrives meanwhile takes precedence, and only a request that expired without one reports the error:



1
2
3
4
5



{
  "status": "error",
  "error": "access_denied",
  "error_description": "The user declined"
}

The outcome is delivered once and then removed, so a second poll reports 404, as does a request that expired unanswered.

CAS as a verifier trusts only itself. A presented credential is accepted when its iss is this deployment’s own issuer, its vct resolves to one of the credential configurations above, and its signature verifies against this deployment’s own signing key; iat and exp are both required. A credential carrying a status claim must point into a status list CAS publishes, and its entry must be VALID; any other status reference is refused rather than accepted unchecked. There is no external issuer trust list, no x5c chain validation, no DID resolution and no OpenID Federation, so credentials issued elsewhere are rejected.

This is a trust policy rather than a protocol limitation: OpenID4VP leaves issuer trust to the verifier, noting that “Verifiers must verify that the issuer of a received presentation is trusted on their own”.

:information_source: Note

Verified presentations are not connected to Heimdall authorization yet. Passing the claims of a verified presentation to AuthZEN requests as subject properties, so that authorization policies can decide on them, may be supported in the future. Until then, a relying party can send the disclosed claims it collected as subject.properties of its AuthZEN requests.

Authorized Credential Types

The credential configurations above describe what the issuer is able to mint. They say nothing about which relying party may ask for what, so by default every registered client may obtain every credential the deployment defines. A service narrows that down with a verifiable credentials policy:



1
2
3
4
5
6
7
8
9
10
11
12



{
  "@class": "org.apereo.cas.services.OidcRegisteredService",
  "clientId": "client",
  "clientSecret": "secret",
  "serviceId": "^https://app.example.org/.*",
  "name": "Example",
  "id": 1,
  "verifiableCredentialsPolicy": {
    "@class": "org.apereo.cas.oidc.vc.services.DefaultRegisteredServiceOidcVerifiableCredentialsPolicy",
    "allowedCredentialTypes": [ "java.util.HashSet", [ "myorg" ] ]
  }
}

The entries in allowedCredentialTypes are credential configuration ids. A service that defines no policy, or whose policy lists no credential types, may obtain every credential configuration the issuer publishes; only a policy that actually names types restricts the service to those types. A policy can never widen a service beyond what the issuer publishes, so naming a credential configuration that does not exist grants nothing.

The policy is enforced wherever a credential type is claimed: when a credential offer transaction is created, when authorization details are turned into an authorization code, and again at the credential endpoint when the token is spent. That last check reads the policy afresh, so tightening a service takes effect against access tokens that are already outstanding.

Credential Validity

Each credential configuration controls how long the credentials it issues remain valid via credential-validity, which defaults to thirty days. The value sets the exp claim of the issued credential, and the validUntil property for formats that carry one. A wallet stores a credential long after the issuance exchange has finished, so this period describes the useful life of the credential itself and is unrelated to the lifetime of the offer, the pre-authorized code, the nonce or the access token used to obtain it.

Claim values come from principal attributes. A value that reads as a number, such as 95.5, is issued as a number; one whose number would not read back the same way, such as 02134, is issued as text exactly as released.

Credential Status

Issued credentials can carry a status claim, so they can be revoked or suspended after issuance, following the Token Status List specification as the High Assurance Interoperability Profile requires of SD-JWT VC credentials. Once turned on in CAS settings, every dc+sd-jwt credential references its own entry in a status list published by CAS:



1
2
3
4
5
6
7
8



{
  "status": {
    "status_list": {
      "idx": 48213,
      "uri": "https://sso.example.org/cas/oidc/oidcVcStatusList/1"
    }
  }
}

Each credential gets a random, unpredictable index, unique among the unexpired credentials of its status list, and a new status list is started once a list has little room left. Entries are kept in the ticket registry and expire with their credential, so statuses survive restarts and are shared by all nodes that share the registry; an index may be reused once the credential that held it has expired. The stateless ticket registry cannot keep entries, so credentials are issued without status when it is used.

The status list is served by a public endpoint, which allows cross-origin requests:



1



GET /oidc/oidcVcStatusList/{id}

The response is a status list token, of type application/statuslist+jwt, signed with the issuer signing key and carrying its x5c certificate chain, if any. Each entry takes 2 bits, for the VALID, INVALID and SUSPENDED statuses, and verifiers may cache the token for its ttl; CAS caches the token it builds for as long, so a status change is visible to verifiers within that time.



1
2
3
4
5
6
7
8
9
10
11



{
  "sub": "https://sso.example.org/cas/oidc/oidcVcStatusList/1",
  "iat": 1791238400,
  "exp": 1791324800,
  "ttl": 600,
  "status_list": {
    "bits": 2,
    "lst": "eNrtwTEBAAAAwqD1T20ND6AAAAAAAAAAAAAAAAAAAAAAAH4G...",
    "aggregation_uri": "https://sso.example.org/cas/oidc/oidcVcStatusListAggregation"
  }
}

Every status list token also names the status list aggregation as its aggregation_uri, and the authorization server metadata advertises it as status_list_aggregation_endpoint. The aggregation lists the URIs of all status lists that hold unexpired entries, so a verifier can fetch and cache them ahead of time; it is public and allows cross-origin requests as well:



1



GET /oidc/oidcVcStatusListAggregation





1
2
3
4
5
6



{
  "status_lists": [
    "https://sso.example.org/cas/oidc/oidcVcStatusList/1",
    "https://sso.example.org/cas/oidc/oidcVcStatusList/2"
  ]
}

The following settings and properties are available from the CAS configuration catalog:

cas.authn.oidc.vc.issuer.status-list.enabledWhether issued SD-JWT VC credentials carry a status claim that points into a status list published by CAS.
false

Whether issued SD-JWT VC credentials carry a status claim that points into a status list published by CAS. Entries are kept in the ticket registry, so the status of a credential survives restarts and is shared between nodes; a stateless ticket registry cannot keep them, and credentials are then issued without status.

Type
Boolean
Default
false
Defined by
OidcVerifiableCredentialStatusListProperties
cas.authn.oidc.vc.issuer.status-list.expirationHow long a status list token is valid after it is issued, advertised as its exp claim.
PT24H
Duration

How long a status list token is valid after it is issued, advertised as its exp claim.

Type
String
Default
PT24H
Defined by
OidcVerifiableCredentialStatusListProperties
cas.authn.oidc.vc.issuer.status-list.sizeNumber of entries in each status list.
131072

Number of entries in each status list. Credentials get random, unpredictable indexes within a list, and a new list is started once a list has little room left. Each entry takes 2 bits, so a multiple of 4 fills whole bytes.

Type
Integer
Default
131072
Defined by
OidcVerifiableCredentialStatusListProperties
cas.authn.oidc.vc.issuer.status-list.time-to-liveHow long a verifier may cache a status list token before fetching it again, advertised as its ttl claim.
PT10M
Duration

How long a verifier may cache a status list token before fetching it again, advertised as its ttl claim. CAS also caches the token it builds for this long.

Type
String
Default
PT10M
Defined by
OidcVerifiableCredentialStatusListProperties

Required settings may be needed to activate or affect the feature; review them even when they have a default. Optional settings only need to be set to change a default or to turn on the behavior they control. Third party settings belong to libraries such as Spring Boot that CAS builds on; their own documentation may have more detail.

Notes on configuration

Configuration Metadata

The collection of configuration properties listed in this section are automatically generated from the CAS source and components that contain the actual field definitions, types, descriptions, modules, etc. This metadata may not always be 100% accurate, or could be lacking details and sufficient explanations.

Be Selective

This section is meant as a guide only. Do NOT copy/paste the entire collection of settings into your CAS configuration; rather pick only the properties that you need. Do NOT enable settings unless you are certain of their purpose and do NOT copy settings into your configuration only to keep them as reference. All these ideas lead to upgrade headaches, maintenance nightmares and premature aging.

YAGNI

Note that for nearly ALL use cases, declaring and configuring properties listed here is sufficient. You should NOT have to explicitly massage a CAS XML/Java/etc configuration file to design an authentication handler, create attribute release policies, etc. CAS at runtime will auto-configure all required changes for you. If you are unsure about the meaning of a given CAS setting, do NOT turn it on without hesitation. Review the codebase or better yet, ask questions to clarify the intended behavior.

Naming Convention

Property names can be specified in very relaxed terms. For instance cas.someProperty, cas.some-property, cas.some_property are all valid names. While all forms are accepted by CAS, there are certain components (in CAS and other frameworks used) whose activation at runtime is conditional on a property value, where this property is required to have been specified in CAS configuration using kebab case. This is both true for properties that are owned by CAS as well as those that might be presented to the system via an external library or framework such as Spring Boot, etc.

:information_source: Note

When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value. The only possible exception to this rule is when naming actuator endpoints; The name of the actuator endpoints (i.e. ssoSessions) MUST remain in camelCase mode.

Settings and properties that are controlled by the CAS platform directly always begin with the prefix cas. All other settings are controlled and provided to CAS via other underlying frameworks and may have their own schemas and syntax. BE CAREFUL with the distinction. Unrecognized properties are rejected by CAS and/or frameworks upon which CAS depends. This means if you somehow misspell a property definition or fail to adhere to the dot-notation syntax and such, your setting is entirely refused by CAS and likely the feature it controls will never be activated in the way you intend.

Validation

Configuration properties are automatically validated on CAS startup to report issues with configuration binding, especially if defined CAS settings cannot be recognized or validated by the configuration schema. Additional validation processes are also handled via Configuration Metadata and property migrations applied automatically on startup by Spring Boot and family.

Indexed Settings

CAS settings able to accept multiple values are typically documented with an index, such as cas.some.setting[0]=value. The index [0] is meant to be incremented by the adopter to allow for distinct multiple configuration blocks.

The status of issued credentials is managed through an actuator endpoint, which lists the credentials issued to a user and changes the status of one, to revoke, suspend or reinstate it:

oidcVcStatus
CAS endpoint2 operationsNot exposed by defaultcas-server-support-oidc-vc
1

Include the module that provides this endpoint in the WAR overlay:

Show in CAS Initializr Generate CAS Server WAR Overlay 


1
2
3
4
5



<dependency>
    <groupId>org.apereo.cas</groupId>
    <artifactId>cas-server-support-oidc-vc</artifactId>
    <version>${cas.version}</version>
</dependency>





1



implementation "org.apereo.cas:cas-server-support-oidc-vc:${project.'cas.version'}"





1
2
3
4
5
6
7
8
9



dependencyManagement {
    imports {
        mavenBom "org.apereo.cas:cas-server-support-bom:${project.'cas.version'}"
    }
}

dependencies {
    implementation "org.apereo.cas:cas-server-support-oidc-vc"
}





1
2
3
4
5
6
7
8
9
10



dependencies {
    /*
        The following platform references are included automatically and are listed for reference only.

        implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")
        implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
        
    */
    implementation "org.apereo.cas:cas-server-support-oidc-vc"
}
2

Turn the endpoint on and expose it over the web. One entry covers every operation. By default only info, health and status are exposed.



1
2



management.endpoint.oidcVcStatus.access=UNRESTRICTED
management.endpoints.web.exposure.include=oidcVcStatus

Endpoints may be mapped to other paths. For example, to serve health at healthcheck:



1



management.endpoints.web.path-mapping.health=healthcheck

Key attestations and wallet attestations that carry a status claim are still accepted with a warning; their status lists are not fetched.

Credential Formats

Each credential configuration is described in the issuer metadata the way its format requires. A dc+sd-jwt configuration publishes its vct. A jwt_vc_json configuration publishes a credential_definition with the credential type, and a jwt_vc_json-ld configuration adds its @context. The type is VerifiableCredential plus the configuration’s scope, or its id when no scope is set, and the context is the W3C Verifiable Credentials Data Model 2.0 base context alone, whose vocabulary covers the credential’s claims. Issued credentials carry exactly what the metadata publishes:



1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17



{
  "credential_configurations_supported": {
    "employee": {
      "format": "jwt_vc_json-ld",
      "scope": "EmployeeCredential",
      "credential_definition": {
        "@context": [
          "https://www.w3.org/ns/credentials/v2"
        ],
        "type": [
          "VerifiableCredential",
          "EmployeeCredential"
        ]
      }
    }
  }
}

Credential Signing

After claims are collected and validated, CAS signs the credential with its own issuer key, selected the same way as for other OpenID Connect artifacts and honoring the service’s jwksKeyId when one is set. The credential names that key with kid and does not say which client it was issued to, so verifiers cannot correlate the holder with the relying party; CAS as a verifier finds the key by kid as well.

A credential is not an ID token, and the relying party’s ID token settings do not apply to it. The algorithm is the first entry of the credential configuration’s credential-signing-alg-values-supported that the issuer’s signing key can perform, so the order of that list is a preference the deployment expresses, and that list is also the permitted set, so no other algorithm can be used. This is what keeps issuance consistent with the issuer metadata and with what a verifier, CAS included, accepts.

When the issuer signing key in the keystore carries an x5c certificate chain, the credential carries it as its x5c header, leaf certificate first, as HAIP 1.0 requires, so a verifier can take the issuer key from the leaf and validate the chain against its trust list. A trailing self-signed certificate is treated as the trust anchor and left out, as HAIP requires. HAIP also requires the leaf not to be self-signed; a self-signed signing certificate is still sent, and CAS logs a warning since wallets that follow HAIP may refuse it. A key without a chain produces credentials without x5c.

A service may narrow the algorithms used for its own credentials through its verifiable credentials policy:



1
2
3
4
5
6
7
8
9
10
11



{
  "@class": "org.apereo.cas.services.OidcRegisteredService",
  "clientId": "client",
  "serviceId": "^https://app.example.org/.*",
  "name": "Example",
  "id": 1,
  "verifiableCredentialsPolicy": {
    "@class": "org.apereo.cas.oidc.vc.services.DefaultRegisteredServiceOidcVerifiableCredentialsPolicy",
    "credentialSigningAlgValuesSupported": [ "java.util.HashSet", [ "ES256" ] ]
  }
}

As with allowedCredentialTypes, this can only narrow: the result is the intersection with what the credential configuration advertises, so naming an algorithm the configuration does not offer leaves the service with nothing and the request is refused. A policy that names no algorithms leaves the service with everything the configuration advertises.