Configuration Security - Vault
You can also store sensitive settings inside Vault. Vault can store your existing secrets, or it can dynamically generate new secrets to control access to third-party resources or provide time-limited credentials for your infrastructure. To learn more about Vault and its installation process, please visit the project website.
Once vault is accessible and configured inside CAS, support is provided via the following dependency:
1
2
3
4
5
<dependency>
<groupId>org.apereo.cas</groupId>
<artifactId>cas-server-support-configuration-cloud-vault</artifactId>
<version>${cas.version}</version>
</dependency>
1
implementation "org.apereo.cas:cas-server-support-configuration-cloud-vault:${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-configuration-cloud-vault"
}
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-configuration-cloud-vault"
}
The following settings and properties are available from the CAS configuration catalog:
spring.cloud.vault.app-id.app-id-pathMount path of the AppId authentication backend.
app-idMount path of the AppId authentication backend.
spring.cloud.vault.app-id.network-interfaceNetwork interface hint for the "MAC_ADDRESS" UserId mechanism.
Network interface hint for the "MAC_ADDRESS" UserId mechanism.
spring.cloud.vault.app-id.user-idUserId mechanism.
MAC_ADDRESSUserId mechanism. Can be either "MAC_ADDRESS", "IP_ADDRESS", a string or a class name.
spring.cloud.vault.app-role.app-role-pathMount path of the AppRole authentication backend.
approleMount path of the AppRole authentication backend.
spring.cloud.vault.app-role.roleName of the role, optional, used for pull-mode.
Name of the role, optional, used for pull-mode.
spring.cloud.vault.app-role.role-idThe RoleId.
The RoleId.
spring.cloud.vault.app-role.secret-idThe SecretId.
The SecretId.
spring.cloud.vault.application-nameApplication name for AppId authentication.
applicationApplication name for AppId authentication.
spring.cloud.vault.authentication
tokenspring.cloud.vault.aws-ec2.aws-ec2-pathMount path of the AWS-EC2 authentication backend.
aws-ec2Mount path of the AWS-EC2 authentication backend.
spring.cloud.vault.aws-ec2.identity-documentURL of the AWS-EC2 PKCS7 identity document.
http://169.254.169.254/latest/dynamic/instance-identity/pkcs7URL of the AWS-EC2 PKCS7 identity document.
spring.cloud.vault.aws-ec2.nonceNonce used for AWS-EC2 authentication.
Nonce used for AWS-EC2 authentication. An empty nonce defaults to nonce generation.
spring.cloud.vault.aws-ec2.roleName of the role, optional.
Name of the role, optional.
spring.cloud.vault.aws-iam.aws-pathMount path of the AWS authentication backend.
awsMount path of the AWS authentication backend.
spring.cloud.vault.aws-iam.endpoint-uriSTS server URI.
STS server URI. @since 2.2
spring.cloud.vault.aws-iam.regionName of the region, optional.
Name of the region, optional. Inferred by AWS defaults if not set. @since 4.0.1
spring.cloud.vault.aws-iam.roleName of the role, optional.
Name of the role, optional. Defaults to the friendly IAM name if not set.
spring.cloud.vault.aws-iam.server-nameName of the server used to set X-Vault-AWS-IAM-Server-ID header in the headers of login requests.
Name of the server used to set X-Vault-AWS-IAM-Server-ID header in the headers of login requests.
spring.cloud.vault.azure-msi.azure-pathMount path of the Azure MSI authentication backend.
azureMount path of the Azure MSI authentication backend.
spring.cloud.vault.azure-msi.identity-token-serviceIdentity token service URI.
Identity token service URI. @since 3.0
spring.cloud.vault.azure-msi.metadata-serviceInstance metadata service URI.
Instance metadata service URI. @since 3.0
spring.cloud.vault.azure-msi.roleName of the role.
Name of the role.
spring.cloud.vault.config.lifecycle.enabledEnable lifecycle management.
trueEnable lifecycle management.
spring.cloud.vault.config.lifecycle.expiry-thresholdThe expiry threshold.
The expiry threshold. Lease is renewed the given Duration before it expires. @since 2.2
spring.cloud.vault.config.lifecycle.lease-endpointsSet the LeaseEndpoints to delegate renewal/revocation calls to.
Set the LeaseEndpoints to delegate renewal/revocation calls to. LeaseEndpoints encapsulates differences between Vault versions that affect the location of renewal/revocation endpoints. Can be LeaseEndpoints#SysLeases for version 0.8 or above of Vault or LeaseEndpoints#Legacy for older versions (the default). @since 2.2
spring.cloud.vault.config.lifecycle.lease-strategySets the LeaseStrategy to be used with org.springframework.vault.core.lease.SecretLeaseContainer#setLeaseStrategy(LeaseStrategy) to retain or drop tokens on renewal errors.
Sets the LeaseStrategy to be used with org.springframework.vault.core.lease.SecretLeaseContainer#setLeaseStrategy(LeaseStrategy) to retain or drop tokens on renewal errors. @since 4.1
spring.cloud.vault.config.lifecycle.min-renewalThe time period that is at least required before renewing a lease.
The time period that is at least required before renewing a lease. @since 2.2
spring.cloud.vault.config.orderUsed to set a org.springframework.core.env.PropertySource priority.
0Used to set a org.springframework.core.env.PropertySource priority. This is useful to use Vault as an override on other property sources. @see org.springframework.core.PriorityOrdered
spring.cloud.vault.connection-timeoutConnection timeout.
5000Connection timeout.
spring.cloud.vault.discovery.enabledFlag to indicate that Vault server discovery is enabled (vault server URL will be looked up via discovery).
falseFlag to indicate that Vault server discovery is enabled (vault server URL will be looked up via discovery).
spring.cloud.vault.discovery.service-idService id to locate Vault.
vaultService id to locate Vault.
spring.cloud.vault.enabledEnable Vault config server.
trueEnable Vault config server.
spring.cloud.vault.fail-fastFail fast if data cannot be obtained from Vault.
falseFail fast if data cannot be obtained from Vault.
spring.cloud.vault.gcp-gce.gcp-pathMount path of the Kubernetes authentication backend.
gcpMount path of the Kubernetes authentication backend.
spring.cloud.vault.gcp-gce.roleName of the role against which the login is being attempted.
Name of the role against which the login is being attempted.
spring.cloud.vault.gcp-gce.service-accountOptional service account id.
Optional service account id. Using the default id if left unconfigured.
spring.cloud.vault.gcp-iam.credentials.encoded-keyThe base64 encoded contents of an OAuth2 account private key in JSON format.
The base64 encoded contents of an OAuth2 account private key in JSON format.
spring.cloud.vault.gcp-iam.credentials.locationLocation of the OAuth2 credentials private key.
Location of the OAuth2 credentials private key.
Since this is a Resource, the private key can be in a multitude of locations, such as a local file system, classpath, URL, etc.
spring.cloud.vault.gcp-iam.gcp-pathMount path of the Kubernetes authentication backend.
gcpMount path of the Kubernetes authentication backend.
spring.cloud.vault.gcp-iam.jwt-validityValidity of the JWT token.
15mValidity of the JWT token.
spring.cloud.vault.gcp-iam.project-idOverrides the GCP project Id.
Overrides the GCP project Id.
spring.cloud.vault.gcp-iam.roleName of the role against which the login is being attempted.
Name of the role against which the login is being attempted.
spring.cloud.vault.gcp-iam.service-account-idOverrides the GCP service account Id.
Overrides the GCP service account Id.
spring.cloud.vault.github.github-pathMount path of the GitHub authentication backend.
githubMount path of the GitHub authentication backend.
spring.cloud.vault.github.tokenGitHub personal token.
GitHub personal token.
spring.cloud.vault.hostVault server host.
localhostVault server host.
spring.cloud.vault.kubernetes.kubernetes-pathMount path of the Kubernetes authentication backend.
kubernetesMount path of the Kubernetes authentication backend.
spring.cloud.vault.kubernetes.roleName of the role against which the login is being attempted.
Name of the role against which the login is being attempted.
spring.cloud.vault.kubernetes.service-account-token-filePath to the service account token file.
/var/run/secrets/kubernetes.io/serviceaccount/tokenPath to the service account token file.
spring.cloud.vault.kv.application-nameApplication name to be used for the context.
applicationApplication name to be used for the context.
spring.cloud.vault.kv.backendName of the default backend.
secretName of the default backend.
spring.cloud.vault.kv.backend-versionKey-Value backend version.
2- Version 1 (unversioned key-value backend).
- Version 2 (versioned key-value backend).
spring.cloud.vault.kv.default-contextName of the default context.
applicationName of the default context.
spring.cloud.vault.kv.enabledEnable the key-value backend.
trueEnable the key-value backend.
spring.cloud.vault.kv.profile-separatorProfile-separator to combine application name and profile.
/Profile-separator to combine application name and profile.
spring.cloud.vault.kv.profilesList of active profiles.
List of active profiles. @since 3.0
spring.cloud.vault.namespaceVault namespace (requires Vault Enterprise).
Vault namespace (requires Vault Enterprise).
spring.cloud.vault.pcf.instance-certificatePath to the instance certificate (PEM).
Path to the instance certificate (PEM). Defaults to CF_INSTANCE_CERT env variable.
spring.cloud.vault.pcf.instance-keyPath to the instance key (PEM).
Path to the instance key (PEM). Defaults to CF_INSTANCE_KEY env variable.
spring.cloud.vault.pcf.pcf-pathMount path of the Kubernetes authentication backend.
pcfMount path of the Kubernetes authentication backend.
spring.cloud.vault.pcf.roleName of the role against which the login is being attempted.
Name of the role against which the login is being attempted.
spring.cloud.vault.portVault server port.
8200Vault server port.
spring.cloud.vault.reactive.enabledFlag to indicate that reactive discovery is enabled.
trueFlag to indicate that reactive discovery is enabled.
spring.cloud.vault.read-timeoutRead timeout.
15000Read timeout.
spring.cloud.vault.schemeProtocol scheme.
httpsProtocol scheme. Can be either "http" or "https".
spring.cloud.vault.session.lifecycle.enabledEnable session lifecycle management.
trueEnable session lifecycle management.
spring.cloud.vault.session.lifecycle.expiry-thresholdThe expiry threshold for a LoginToken .
7sThe expiry threshold for a LoginToken. The threshold represents a minimum TTL duration to consider a login token as valid. Tokens with a shorter TTL are considered expired and are not used anymore. Should be greater than refreshBeforeExpiry to prevent token expiry.
spring.cloud.vault.session.lifecycle.refresh-before-expiryThe time period that is at least required before renewing the LoginToken .
5sThe time period that is at least required before renewing the LoginToken.
spring.cloud.vault.ssl.cert-auth-pathMount path of the TLS cert authentication backend.
certMount path of the TLS cert authentication backend.
spring.cloud.vault.ssl.enabled-cipher-suitesList of enabled SSL/TLS cipher suites.
List of enabled SSL/TLS cipher suites. @since 3.0.2
spring.cloud.vault.ssl.enabled-protocolsList of enabled SSL/TLS protocol.
List of enabled SSL/TLS protocol. @since 3.0.2
spring.cloud.vault.ssl.key-storeTrust store that holds certificates and private keys.
Trust store that holds certificates and private keys.
spring.cloud.vault.ssl.key-store-passwordPassword used to access the key store.
Password used to access the key store.
spring.cloud.vault.ssl.key-store-typeType of the key store.
Type of the key store. @since 3.0
spring.cloud.vault.ssl.roleName of the role against which the login is being attempted.
Name of the role against which the login is being attempted. @since 5.0
spring.cloud.vault.ssl.trust-storeTrust store that holds SSL certificates.
Trust store that holds SSL certificates.
spring.cloud.vault.ssl.trust-store-passwordPassword used to access the trust store.
Password used to access the trust store.
spring.cloud.vault.ssl.trust-store-typeType of the trust store.
Type of the trust store. @since 3.0
spring.cloud.vault.tokenStatic vault token.
Static vault token. Required if #authentication is TOKEN.
spring.cloud.vault.uriVault URI.
Vault URI. Can be set with scheme, host and port.
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.
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.
With CAS, secrets are picked up at startup of the application server. CAS uses the data and settings
from the application name (i.e. cas) and active profiles to determine contexts paths in
which secrets should be stored and later fetched.
These context paths typically are:
1
2
/secret/{application}/{profile}
/secret/{application}
As an example, you may write the following CAS setting to Vault:
1
vault write secret/cas/native <setting-name>=<value>
CAS will execute the equivalent of the following command to read settings later when needed:
1
vault read secret/cas/native
All settings and secrets that are stored inside Vault may be reloaded at any given time. To learn more about how CAS allows you to reload configuration changes, please review this guide. To learn more about how configuration is managed and profiled by CAS, please review this guide.
Troubleshooting
To enable additional logging, modify the logging configuration file to add the following:
1
2
3
4
<Logger name="org.springframework.cloud.vault" level="debug" additivity="false">
<AppenderRef ref="casConsole"/>
<AppenderRef ref="casFile"/>
</Logger>