676 lines
27 KiB
Plaintext
676 lines
27 KiB
Plaintext
[[vault.config.authentication]]
|
||
= Authentication methods
|
||
|
||
Different organizations have different requirements for security and authentication.
|
||
Vault reflects that need by shipping multiple authentication methods.
|
||
Spring Cloud Vault supports token and AppId authentication.
|
||
|
||
[[vault.config.authentication.token]]
|
||
== Token authentication
|
||
|
||
Tokens are the core method for authentication within Vault.
|
||
Token authentication requires a static token to be provided using the configuration.
|
||
As a fallback, the token may also be retrieved from `~/.vault-token` which is the default location used by the Vault CLI to cache tokens.
|
||
|
||
NOTE: Token authentication is the default authentication method.
|
||
If a token is disclosed an unintended party gains access to Vault and can access secrets for the intended client.
|
||
|
||
.application.yml
|
||
[source,yaml]
|
||
----
|
||
spring.cloud.vault:
|
||
authentication: TOKEN
|
||
token: 00000000-0000-0000-0000-000000000000
|
||
----
|
||
|
||
* `authentication` setting this value to `TOKEN` selects the Token authentication method
|
||
* `token` sets the static token to use. If missing or empty, then an attempt will be made to retrieve a token from ~/.vault-token.
|
||
|
||
See also:
|
||
|
||
* https://www.vaultproject.io/docs/concepts/tokens.html[Vault Documentation: Tokens]
|
||
* https://www.vaultproject.io/docs/commands/login[Vault Documentation: CLI login]
|
||
* https://www.vaultproject.io/docs/commands/token-helper[Vault Documentation: CLI default to ~/.vault-token]
|
||
|
||
[[vault.config.authentication.vault-agent]]
|
||
== Vault Agent authentication
|
||
|
||
Vault ships a sidecar utility with Vault Agent since version 0.11.0. Vault Agent implements the functionality of Spring Vault's `SessionManager`
|
||
with its Auto-Auth feature.
|
||
Applications can reuse cached session credentials by relying on Vault Agent running on `localhost`.
|
||
Spring Vault can send requests without the
|
||
`X-Vault-Token` header.
|
||
Disable Spring Vault's authentication infrastructure to disable client authentication and session management.
|
||
|
||
.application.yml
|
||
[source,yaml]
|
||
----
|
||
spring.cloud.vault:
|
||
authentication: NONE
|
||
----
|
||
|
||
* `authentication` setting this value to `NONE` disables `ClientAuthentication`
|
||
and `SessionManager`.
|
||
|
||
See also: https://www.vaultproject.io/docs/agent/index.html[Vault Documentation: Agent]
|
||
|
||
[[vault.config.authentication.appid]]
|
||
== AppId authentication
|
||
|
||
Vault supports https://www.vaultproject.io/docs/auth/app-id.html[AppId]
|
||
authentication that consists of two hard to guess tokens.
|
||
The AppId defaults to `spring.application.name` that is statically configured.
|
||
The second token is the UserId which is a part determined by the application, usually related to the runtime environment.
|
||
IP address, Mac address or a Docker container name are good examples.
|
||
Spring Cloud Vault Config supports IP address, Mac address and static UserId's (e.g. supplied via System properties).
|
||
The IP and Mac address are represented as Hex-encoded SHA256 hash.
|
||
|
||
IP address-based UserId's use the local host's IP address.
|
||
|
||
.application.yml using SHA256 IP-Address UserId's
|
||
[source,yaml]
|
||
----
|
||
spring.cloud.vault:
|
||
authentication: APPID
|
||
app-id:
|
||
user-id: IP_ADDRESS
|
||
----
|
||
|
||
* `authentication` setting this value to `APPID` selects the AppId authentication method
|
||
* `app-id-path` sets the path of the AppId mount to use
|
||
* `user-id` sets the UserId method.
|
||
Possible values are `IP_ADDRESS`,
|
||
`MAC_ADDRESS` or a class name implementing a custom `AppIdUserIdMechanism`
|
||
|
||
The corresponding command to generate the IP address UserId from a command line is:
|
||
|
||
----
|
||
$ echo -n 192.168.99.1 | sha256sum
|
||
----
|
||
|
||
NOTE: Including the line break of `echo` leads to a different hash value so make sure to include the `-n` flag.
|
||
|
||
Mac address-based UserId's obtain their network device from the localhost-bound device.
|
||
The configuration also allows specifying a `network-interface` hint to pick the right device.
|
||
The value of
|
||
`network-interface` is optional and can be either an interface name or interface index (0-based).
|
||
|
||
.application.yml using SHA256 Mac-Address UserId's
|
||
[source,yaml]
|
||
----
|
||
spring.cloud.vault:
|
||
authentication: APPID
|
||
app-id:
|
||
user-id: MAC_ADDRESS
|
||
network-interface: eth0
|
||
----
|
||
|
||
* `network-interface` sets network interface to obtain the physical address
|
||
|
||
|
||
The corresponding command to generate the IP address UserId from a command line is:
|
||
|
||
----
|
||
$ echo -n 0AFEDE1234AC | sha256sum
|
||
----
|
||
|
||
NOTE: The Mac address is specified uppercase and without colons.
|
||
Including the line break of `echo` leads to a different hash value so make sure to include the `-n` flag.
|
||
|
||
[[custom-userid]]
|
||
=== Custom UserId
|
||
|
||
The UserId generation is an open mechanism.
|
||
You can set
|
||
`spring.cloud.vault.app-id.user-id` to any string and the configured value will be used as static UserId.
|
||
|
||
A more advanced approach lets you set `spring.cloud.vault.app-id.user-id` to a classname.
|
||
This class must be on your classpath and must implement the `org.springframework.cloud.vault.AppIdUserIdMechanism` interface and the `createUserId` method.
|
||
Spring Cloud Vault will obtain the UserId by calling `createUserId` each time it authenticates using AppId to obtain a token.
|
||
|
||
.application.yml
|
||
[source,yaml]
|
||
----
|
||
spring.cloud.vault:
|
||
authentication: APPID
|
||
app-id:
|
||
user-id: com.examlple.MyUserIdMechanism
|
||
----
|
||
|
||
.MyUserIdMechanism.java
|
||
[source,yaml]
|
||
----
|
||
public class MyUserIdMechanism implements AppIdUserIdMechanism {
|
||
|
||
@Override
|
||
public String createUserId() {
|
||
String userId = ...
|
||
return userId;
|
||
}
|
||
}
|
||
----
|
||
|
||
See also: https://www.vaultproject.io/docs/auth/app-id.html[Vault Documentation: Using the App ID auth backend]
|
||
|
||
[[approle-authentication]]
|
||
== AppRole authentication
|
||
|
||
https://www.vaultproject.io/docs/auth/app-id.html[AppRole] is intended for machine authentication, like the deprecated (since Vault 0.6.1) xref:authentication.adoc#vault.config.authentication.appid[AppId authentication].
|
||
AppRole authentication consists of two hard to guess (secret) tokens: RoleId and SecretId.
|
||
|
||
Spring Vault supports various AppRole scenarios (push/pull mode and wrapped).
|
||
|
||
RoleId and optionally SecretId must be provided by configuration, Spring Vault will not look up these or create a custom SecretId.
|
||
|
||
.application.yml with AppRole authentication properties
|
||
[source,yaml]
|
||
----
|
||
spring.cloud.vault:
|
||
authentication: APPROLE
|
||
app-role:
|
||
role-id: bde2076b-cccb-3cf0-d57e-bca7b1e83a52
|
||
----
|
||
|
||
The following scenarios are supported along the required configuration details:
|
||
|
||
.Configuration
|
||
|===
|
||
| *Method* | *RoleId* | *SecretId*| *RoleName* | *Token*
|
||
| Provided RoleId/SecretId | Provided | Provided | |
|
||
| Provided RoleId without SecretId | Provided | | |
|
||
| Provided RoleId, Pull SecretId | Provided | | Provided | Provided
|
||
| Pull RoleId, provided SecretId | | Provided | Provided | Provided
|
||
| Full Pull Mode | | | Provided | Provided
|
||
| Wrapped | | | | Provided
|
||
| Wrapped RoleId, provided SecretId | | Provided | | Provided
|
||
| Provided RoleId, wrapped SecretId | Provided | | | Provided
|
||
|===
|
||
|
||
.Pull/Push/Wrapped Matrix
|
||
|===
|
||
| *RoleId* | *SecretId* | *Supported*
|
||
| Provided | Provided | ✅
|
||
| Provided | Pull | ✅
|
||
| Provided | Wrapped | ✅
|
||
| Provided | Absent | ✅
|
||
| Pull | Provided | ✅
|
||
| Pull | Pull | ✅
|
||
| Pull | Wrapped | ❌
|
||
| Pull | Absent | ❌
|
||
| Wrapped | Provided | ✅
|
||
| Wrapped | Pull | ❌
|
||
| Wrapped | Wrapped | ✅
|
||
| Wrapped | Absent | ❌
|
||
|===
|
||
|
||
NOTE: You can use still all combinations of push/pull/wrapped modes by providing a configured `AppRoleAuthentication` bean within the context.
|
||
Spring Cloud Vault cannot derive all possible AppRole combinations from the configuration properties.
|
||
|
||
IMPORTANT: AppRole authentication is limited to simple pull mode using reactive infrastructure.
|
||
Full pull mode is not yet supported.
|
||
Using Spring Cloud Vault with the Spring WebFlux stack enables Vault's reactive auto-configuration which can be disabled by setting `spring.cloud.vault.reactive.enabled=false`.
|
||
|
||
.application.yml with all AppRole authentication properties
|
||
[source,yaml]
|
||
----
|
||
spring.cloud.vault:
|
||
authentication: APPROLE
|
||
app-role:
|
||
role-id: bde2076b-cccb-3cf0-d57e-bca7b1e83a52
|
||
secret-id: 1696536f-1976-73b1-b241-0b4213908d39
|
||
role: my-role
|
||
app-role-path: approle
|
||
----
|
||
|
||
* `role-id` sets the RoleId.
|
||
* `secret-id` sets the SecretId.
|
||
SecretId can be omitted if AppRole is configured without requiring SecretId (See `bind_secret_id`).
|
||
* `role`: sets the AppRole name for pull mode.
|
||
* `app-role-path` sets the path of the approle authentication mount to use.
|
||
|
||
See also: https://www.vaultproject.io/docs/auth/approle.html[Vault Documentation: Using the AppRole auth backend]
|
||
|
||
[[vault.config.authentication.awsec2]]
|
||
== AWS-EC2 authentication
|
||
|
||
The https://www.vaultproject.io/docs/auth/aws-ec2.html[aws-ec2]
|
||
auth backend provides a secure introduction mechanism for AWS EC2 instances, allowing automated retrieval of a Vault token.
|
||
Unlike most Vault authentication backends, this backend does not require first-deploying, or provisioning security-sensitive credentials (tokens, username/password, client certificates, etc.).
|
||
Instead, it treats AWS as a Trusted Third Party and uses the cryptographically signed dynamic metadata information that uniquely represents each EC2 instance.
|
||
|
||
.application.yml using AWS-EC2 Authentication
|
||
[source,yaml]
|
||
----
|
||
spring.cloud.vault:
|
||
authentication: AWS_EC2
|
||
----
|
||
|
||
AWS-EC2 authentication enables nonce by default to follow the Trust On First Use (TOFU) principle.
|
||
Any unintended party that gains access to the PKCS#7 identity metadata can authenticate against Vault.
|
||
|
||
During the first login, Spring Cloud Vault generates a nonce that is stored in the auth backend aside the instance Id.
|
||
Re-authentication requires the same nonce to be sent.
|
||
Any other party does not have the nonce and can raise an alert in Vault for further investigation.
|
||
|
||
The nonce is kept in memory and is lost during application restart.
|
||
You can configure a static nonce with `spring.cloud.vault.aws-ec2.nonce`.
|
||
|
||
AWS-EC2 authentication roles are optional and default to the AMI.
|
||
You can configure the authentication role by setting the
|
||
`spring.cloud.vault.aws-ec2.role` property.
|
||
|
||
.application.yml with configured role
|
||
[source,yaml]
|
||
----
|
||
spring.cloud.vault:
|
||
authentication: AWS_EC2
|
||
aws-ec2:
|
||
role: application-server
|
||
----
|
||
|
||
.application.yml with all AWS EC2 authentication properties
|
||
[source,yaml]
|
||
----
|
||
spring.cloud.vault:
|
||
authentication: AWS_EC2
|
||
aws-ec2:
|
||
role: application-server
|
||
aws-ec2-path: aws-ec2
|
||
identity-document: http://...
|
||
nonce: my-static-nonce
|
||
----
|
||
|
||
* `authentication` setting this value to `AWS_EC2` selects the AWS EC2 authentication method
|
||
* `role` sets the name of the role against which the login is being attempted.
|
||
* `aws-ec2-path` sets the path of the AWS EC2 mount to use
|
||
* `identity-document` sets URL of the PKCS#7 AWS EC2 identity document
|
||
* `nonce` used for AWS-EC2 authentication.
|
||
An empty nonce defaults to nonce generation
|
||
|
||
See also: https://www.vaultproject.io/docs/auth/aws.html[Vault Documentation: Using the aws auth backend]
|
||
|
||
[[vault.config.authentication.awsiam]]
|
||
== AWS-IAM authentication
|
||
|
||
The https://www.vaultproject.io/docs/auth/aws-ec2.html[aws] backend provides a secure authentication mechanism for AWS IAM roles, allowing the automatic authentication with vault based on the current IAM role of the running application.
|
||
Unlike most Vault authentication backends, this backend does not require first-deploying, or provisioning security-sensitive credentials (tokens, username/password, client certificates, etc.).
|
||
Instead, it treats AWS as a Trusted Third Party and uses the 4 pieces of information signed by the caller with their IAM credentials to verify that the caller is indeed using that IAM role.
|
||
|
||
The current IAM role the application is running in is automatically calculated.
|
||
If you are running your application on AWS ECS then the application will use the IAM role assigned to the ECS task of the running container.
|
||
If you are running your application naked on top of an EC2 instance then the IAM role used will be the one assigned to the EC2 instance.
|
||
|
||
When using the AWS-IAM authentication you must create a role in Vault and assign it to your IAM role.
|
||
An empty `role` defaults to the friendly name the current IAM role.
|
||
|
||
.application.yml with required AWS-IAM Authentication properties
|
||
[source,yaml]
|
||
----
|
||
spring.cloud.vault:
|
||
authentication: AWS_IAM
|
||
----
|
||
|
||
.application.yml with all AWS-IAM Authentication properties
|
||
[source,yaml]
|
||
----
|
||
spring.cloud.vault:
|
||
authentication: AWS_IAM
|
||
aws-iam:
|
||
region: aws-global
|
||
role: my-dev-role
|
||
aws-path: aws
|
||
server-name: some.server.name
|
||
endpoint-uri: https://sts.eu-central-1.amazonaws.com
|
||
----
|
||
|
||
* `region` sets the name of the AWS region. If not supplied, the region will be determined by AWS defaults.
|
||
* `role` sets the name of the role against which the login is being attempted.
|
||
This should be bound to your IAM role.
|
||
If one is not supplied then the friendly name of the current IAM user will be used as the vault role.
|
||
* `aws-path` sets the path of the AWS mount to use
|
||
* `server-name` sets the value to use for the `X-Vault-AWS-IAM-Server-ID` header preventing certain types of replay attacks.
|
||
* `endpoint-uri` sets the value to use for the AWS STS API used for the `iam_request_url` parameter.
|
||
|
||
AWS-IAM requires the AWS Java SDK v2 dependency (`software.amazon.awssdk:auth`) as the authentication implementation uses AWS SDK types for credentials and request signing.
|
||
|
||
See also: https://www.vaultproject.io/docs/auth/aws.html[Vault Documentation: Using the aws auth backend]
|
||
|
||
[[vault.config.authentication.azuremsi]]
|
||
== Azure MSI authentication
|
||
|
||
The https://www.vaultproject.io/docs/auth/azure.html[azure]
|
||
auth backend provides a secure introduction mechanism for Azure VM instances, allowing automated retrieval of a Vault token.
|
||
Unlike most Vault authentication backends, this backend does not require first-deploying, or provisioning security-sensitive credentials (tokens, username/password, client certificates, etc.).
|
||
Instead, it treats Azure as a Trusted Third Party and uses the managed service identity and instance metadata information that can be bound to a VM instance.
|
||
|
||
.application.yml with required Azure Authentication properties
|
||
[source,yaml]
|
||
----
|
||
spring.cloud.vault:
|
||
authentication: AZURE_MSI
|
||
azure-msi:
|
||
role: my-dev-role
|
||
----
|
||
|
||
.application.yml with all Azure Authentication properties
|
||
[source,yaml]
|
||
----
|
||
spring.cloud.vault:
|
||
authentication: AZURE_MSI
|
||
azure-msi:
|
||
role: my-dev-role
|
||
azure-path: azure
|
||
metadata-service: http://169.254.169.254/metadata/instance…
|
||
identity-token-service: http://169.254.169.254/metadata/identity…
|
||
----
|
||
|
||
* `role` sets the name of the role against which the login is being attempted.
|
||
* `azure-path` sets the path of the Azure mount to use
|
||
* `metadata-service` sets the URI at which to access the instance metadata service
|
||
* `identity-token-service` sets the URI at which to access the identity token service
|
||
|
||
Azure MSI authentication obtains environmental details about the virtual machine (subscription Id, resource group, VM name) from the instance metadata service.
|
||
The Vault server has Resource Id defaults to `https://vault.hashicorp.com`.
|
||
To change this, set `spring.cloud.vault.azure-msi.identity-token-service` accordingly.
|
||
|
||
See also:
|
||
|
||
* https://www.vaultproject.io/docs/auth/azure.html[Vault Documentation: Using the azure auth backend]
|
||
* https://docs.microsoft.com/en-us/azure/virtual-machines/windows/instance-metadata-service[Azure Documentation: Azure Instance Metadata Service]
|
||
|
||
[[vault.config.authentication.clientcert]]
|
||
== TLS certificate authentication
|
||
|
||
The `cert` auth backend allows authentication using SSL/TLS client certificates that are either signed by a CA or self-signed.
|
||
|
||
To enable `cert` authentication you need to:
|
||
|
||
1. Use SSL, see xref:advanced-topics.adoc#vault.config.ssl[Vault Client SSL configuration]
|
||
2. Configure a Java `Keystore` that contains the client certificate and the private key
|
||
3. Set the `spring.cloud.vault.authentication` to `CERT`
|
||
|
||
.application.yml
|
||
[source,yaml]
|
||
----
|
||
spring.cloud.vault:
|
||
authentication: CERT
|
||
ssl:
|
||
key-store: classpath:keystore.jks
|
||
key-store-password: changeit
|
||
key-store-type: JKS
|
||
cert-auth-path: cert
|
||
----
|
||
|
||
See also: https://www.vaultproject.io/docs/auth/cert.html[Vault Documentation: Using the Cert auth backend]
|
||
|
||
[[vault.config.authentication.cubbyhole]]
|
||
== Cubbyhole authentication
|
||
|
||
Cubbyhole authentication uses Vault primitives to provide a secured authentication workflow.
|
||
Cubbyhole authentication uses tokens as primary login method.
|
||
An ephemeral token is used to obtain a second, login VaultToken from Vault's Cubbyhole secret backend.
|
||
The login token is usually longer-lived and used to interact with Vault.
|
||
The login token will be retrieved from a wrapped response stored at `/cubbyhole/response`.
|
||
|
||
*Creating a wrapped token*
|
||
|
||
NOTE: Response Wrapping for token creation requires Vault 0.6.0 or higher.
|
||
|
||
.Creating and storing tokens
|
||
[source,shell]
|
||
----
|
||
$ vault token-create -wrap-ttl="10m"
|
||
Key Value
|
||
--- -----
|
||
wrapping_token: 397ccb93-ff6c-b17b-9389-380b01ca2645
|
||
wrapping_token_ttl: 0h10m0s
|
||
wrapping_token_creation_time: 2016-09-18 20:29:48.652957077 +0200 CEST
|
||
wrapped_accessor: 46b6aebb-187f-932a-26d7-4f3d86a68319
|
||
----
|
||
|
||
.application.yml
|
||
[source,yaml]
|
||
----
|
||
spring.cloud.vault:
|
||
authentication: CUBBYHOLE
|
||
token: 397ccb93-ff6c-b17b-9389-380b01ca2645
|
||
----
|
||
|
||
See also:
|
||
|
||
* https://www.vaultproject.io/docs/concepts/tokens.html[Vault Documentation: Tokens]
|
||
* https://www.vaultproject.io/docs/secrets/cubbyhole/index.html[Vault Documentation: Cubbyhole Secret Backend]
|
||
* https://www.vaultproject.io/docs/concepts/response-wrapping.html[Vault Documentation: Response Wrapping]
|
||
|
||
[[vault.config.authentication.gcpgce]]
|
||
== GCP-GCE authentication
|
||
|
||
The https://www.vaultproject.io/docs/auth/gcp.html[gcp]
|
||
auth backend allows Vault login by using existing GCP (Google Cloud Platform) IAM and GCE credentials.
|
||
|
||
GCP GCE (Google Compute Engine) authentication creates a signature in the form of a JSON Web Token (JWT) for a service account.
|
||
A JWT for a Compute Engine instance is obtained from the GCE metadata service using https://cloud.google.com/compute/docs/instances/verifying-instance-identity[Instance identification].
|
||
This API creates a JSON Web Token that can be used to confirm the instance identity.
|
||
|
||
Unlike most Vault authentication backends, this backend does not require first-deploying, or provisioning security-sensitive credentials (tokens, username/password, client certificates, etc.).
|
||
Instead, it treats GCP as a Trusted Third Party and uses the cryptographically signed dynamic metadata information that uniquely represents each GCP service account.
|
||
|
||
.application.yml with required GCP-GCE Authentication properties
|
||
[source,yaml]
|
||
----
|
||
spring.cloud.vault:
|
||
authentication: GCP_GCE
|
||
gcp-gce:
|
||
role: my-dev-role
|
||
----
|
||
|
||
.application.yml with all GCP-GCE Authentication properties
|
||
[source,yaml]
|
||
----
|
||
spring.cloud.vault:
|
||
authentication: GCP_GCE
|
||
gcp-gce:
|
||
gcp-path: gcp
|
||
role: my-dev-role
|
||
service-account: my-service@projectid.iam.gserviceaccount.com
|
||
----
|
||
|
||
* `role` sets the name of the role against which the login is being attempted.
|
||
* `gcp-path` sets the path of the GCP mount to use
|
||
* `service-account` allows overriding the service account Id to a specific value.
|
||
Defaults to the `default` service account.
|
||
|
||
See also:
|
||
|
||
* https://www.vaultproject.io/docs/auth/gcp.html[Vault Documentation: Using the GCP auth backend]
|
||
* https://cloud.google.com/compute/docs/instances/verifying-instance-identity[GCP Documentation: Verifying the Identity of Instances]
|
||
|
||
[[vault.config.authentication.gcpiam]]
|
||
== GCP-IAM authentication
|
||
|
||
The https://www.vaultproject.io/docs/auth/gcp.html[gcp]
|
||
auth backend allows Vault login by using existing GCP (Google Cloud Platform) IAM and GCE credentials.
|
||
|
||
GCP IAM authentication creates a signature in the form of a JSON Web Token (JWT) for a service account.
|
||
A JWT for a service account is obtained by calling GCP IAM's https://cloud.google.com/iam/reference/rest/v1/projects.serviceAccounts/signJwt[`projects.serviceAccounts.signJwt`] API. The caller authenticates against GCP IAM and proves thereby its identity.
|
||
This Vault backend treats GCP as a Trusted Third Party.
|
||
|
||
IAM credentials can be obtained from either the runtime environment , specifically the https://cloud.google.com/docs/authentication/production[`GOOGLE_APPLICATION_CREDENTIALS`]
|
||
environment variable, the Google Compute metadata service, or supplied externally as e.g. JSON or base64 encoded.
|
||
JSON is the preferred form as it carries the project id and service account identifier required for calling ``projects.serviceAccounts.signJwt``.
|
||
|
||
.application.yml with required GCP-IAM Authentication properties
|
||
[source,yaml]
|
||
----
|
||
spring.cloud.vault:
|
||
authentication: GCP_IAM
|
||
gcp-iam:
|
||
role: my-dev-role
|
||
----
|
||
|
||
.application.yml with all GCP-IAM Authentication properties
|
||
[source,yaml]
|
||
----
|
||
spring.cloud.vault:
|
||
authentication: GCP_IAM
|
||
gcp-iam:
|
||
credentials:
|
||
location: classpath:credentials.json
|
||
encoded-key: e+KApn0=
|
||
gcp-path: gcp
|
||
jwt-validity: 15m
|
||
project-id: my-project-id
|
||
role: my-dev-role
|
||
service-account-id: my-service@projectid.iam.gserviceaccount.com
|
||
----
|
||
|
||
* `role` sets the name of the role against which the login is being attempted.
|
||
* `credentials.location` path to the credentials resource that contains Google credentials in JSON format.
|
||
* `credentials.encoded-key` the base64 encoded contents of an OAuth2 account private key in the JSON format.
|
||
* `gcp-path` sets the path of the GCP mount to use
|
||
* `jwt-validity` configures the JWT token validity.
|
||
Defaults to 15 minutes.
|
||
* `project-id` allows overriding the project Id to a specific value.
|
||
Defaults to the project Id from the obtained credential.
|
||
* `service-account` allows overriding the service account Id to a specific value.
|
||
Defaults to the service account from the obtained credential.
|
||
|
||
GCP IAM authentication requires the Google Cloud Java SDK dependency (`com.google.apis:google-api-services-iam` and `com.google.auth:google-auth-library-oauth2-http`) as the authentication implementation uses Google APIs for credentials and JWT signing.
|
||
|
||
NOTE: Google credentials require an OAuth 2 token maintaining the token lifecycle.
|
||
All API is synchronous therefore, `GcpIamAuthentication` does not support `AuthenticationSteps` which is required for reactive usage.
|
||
|
||
See also:
|
||
|
||
* https://www.vaultproject.io/docs/auth/gcp.html[Vault Documentation: Using the GCP auth backend]
|
||
* https://cloud.google.com/iam/reference/rest/v1/projects.serviceAccounts/signJwt[GCP Documentation: projects.serviceAccounts.signJwt]
|
||
|
||
[[vault.authentication.gcpiam]]
|
||
[[vault.config.authentication.kubernetes]]
|
||
== Kubernetes authentication
|
||
|
||
Kubernetes authentication mechanism (since Vault 0.8.3) allows to authenticate with Vault using a Kubernetes Service Account Token.
|
||
The authentication is role based and the role is bound to a service account name and a namespace.
|
||
|
||
A file containing a JWT token for a pod’s service account is automatically mounted at `/var/run/secrets/kubernetes.io/serviceaccount/token`.
|
||
|
||
.application.yml with all Kubernetes authentication properties
|
||
[source,yaml]
|
||
----
|
||
spring.cloud.vault:
|
||
authentication: KUBERNETES
|
||
kubernetes:
|
||
role: my-dev-role
|
||
kubernetes-path: kubernetes
|
||
service-account-token-file: /var/run/secrets/kubernetes.io/serviceaccount/token
|
||
----
|
||
|
||
* `role` sets the Role.
|
||
* `kubernetes-path` sets the path of the Kubernetes mount to use.
|
||
* `service-account-token-file` sets the location of the file containing the Kubernetes Service Account Token.
|
||
Defaults to `/var/run/secrets/kubernetes.io/serviceaccount/token`.
|
||
|
||
See also:
|
||
|
||
* https://www.vaultproject.io/docs/auth/kubernetes.html[Vault Documentation: Kubernetes]
|
||
* https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/[Kubernetes Documentation: Configure Service Accounts for Pods]
|
||
|
||
[[vault.config.authentication.pcf]]
|
||
== Pivotal CloudFoundry authentication
|
||
|
||
The https://www.vaultproject.io/docs/auth/pcf.html[pcf]
|
||
auth backend provides a secure introduction mechanism for applications running within Pivotal's CloudFoundry instances allowing automated retrieval of a Vault token.
|
||
Unlike most Vault authentication backends, this backend does not require first-deploying, or provisioning security-sensitive credentials (tokens, username/password, client certificates, etc.) as identity provisioning is handled by PCF itself.
|
||
Instead, it treats PCF as a Trusted Third Party and uses the managed instance identity.
|
||
|
||
.application.yml with required PCF Authentication properties
|
||
[source,yaml]
|
||
----
|
||
spring.cloud.vault:
|
||
authentication: PCF
|
||
pcf:
|
||
role: my-dev-role
|
||
----
|
||
|
||
.application.yml with all PCF Authentication properties
|
||
[source,yaml]
|
||
----
|
||
spring.cloud.vault:
|
||
authentication: PCF
|
||
pcf:
|
||
role: my-dev-role
|
||
pcf-path: path
|
||
instance-certificate: /etc/cf-instance-credentials/instance.crt
|
||
instance-key: /etc/cf-instance-credentials/instance.key
|
||
----
|
||
|
||
* `role` sets the name of the role against which the login is being attempted.
|
||
* `pcf-path` sets the path of the PCF mount to use.
|
||
* `instance-certificate` sets the path to the PCF instance identity certificate.
|
||
Defaults to `$\{CF_INSTANCE_CERT}` env variable.
|
||
* `instance-key` sets the path to the PCF instance identity key.
|
||
Defaults to `$\{CF_INSTANCE_KEY}` env variable.
|
||
|
||
NOTE: PCF authentication requires BouncyCastle (bcpkix-jdk15on) to be on the classpath for RSA PSS signing.
|
||
|
||
See also: https://www.vaultproject.io/docs/auth/pcf.html[Vault Documentation: Using the pcf auth backend]
|
||
|
||
[[vault.config.acl]]
|
||
== ACL Requirements
|
||
|
||
This section explains which paths are accessed by Spring Vault so you can derive your policy declarations from the required capabilities.
|
||
|
||
|===
|
||
|Capability |Associated HTTP verbs
|
||
|
||
|create
|
||
|`POST`/`PUT`
|
||
|
||
|read
|
||
|`GET`
|
||
|
||
|update
|
||
|`POST`/`PUT`
|
||
|
||
|delete
|
||
|`DELETE`
|
||
|
||
|list
|
||
|`LIST` (`GET`)
|
||
|===
|
||
|
||
|
||
See also https://www.vaultproject.io/guides/identity/policies.
|
||
|
||
[[authentication]]
|
||
== Authentication
|
||
|
||
Login: `POST auth/$authMethod/login`
|
||
|
||
[[keyvalue-mount-discovery]]
|
||
== KeyValue Mount Discovery
|
||
|
||
`GET sys/internal/ui/mounts/$mountPath`
|
||
|
||
[[secretleasecontainer]]
|
||
== SecretLeaseContainer
|
||
|
||
`SecretLeaseContainer` uses different paths depending on the configured lease endpoint.
|
||
|
||
`LeaseEndpoints.Legacy`
|
||
|
||
* Revocation: `PUT sys/revoke`
|
||
* Renewal: `PUT sys/renew`
|
||
|
||
`LeaseEndpoints.Leases` (`SysLeases`)
|
||
|
||
* Revocation: `PUT sys/leases/revoke`
|
||
* Renewal: `PUT sys/leases/renew`
|
||
|
||
[[session-management]]
|
||
== Session Management
|
||
|
||
* Token lookup: `GET auth/token/lookup-self`
|
||
* Renewal: `POST auth/token/renew-self`
|
||
* Revoke: `POST auth/token/revoke-self`
|