127 lines
4.8 KiB
Markdown
127 lines
4.8 KiB
Markdown
# Requesting a client certificate from a remote Vault server with user and password authentication
|
|
|
|
This guide shows how an administrator configures the Vault userpass authentication method, and how a user logs in to a remote Vault server and gets a client certificate signed by the Vault CA.
|
|
|
|
## Prerequisites
|
|
|
|
- The Vault PKI configured as described in step 1a of the main `README.md`: the `pki_int` mount and the `wif-client` role (`vault_configure.sh`).
|
|
- A Vault server reachable over HTTPS. The examples use `https://vault.example.com:8200`.
|
|
- `vault` and `openssl` on the workstation of the administrator and of the user, and Node.js 24 or later on the workstation of the administrator.
|
|
|
|
The commands are written for bash.
|
|
|
|
## 1. Configure the authentication
|
|
|
|
Role: **Administrator**
|
|
|
|
Point the CLI at the server and authenticate with an administrator token:
|
|
|
|
```bash
|
|
export VAULT_ADDR=https://vault.example.com:8200
|
|
export VAULT_TOKEN=<admin-token>
|
|
```
|
|
|
|
1. Create a policy that allows signing certificate requests with the `wif-client` role and nothing else.
|
|
2. Enable the userpass authentication method.
|
|
3. Create the user with `vault_create_user.mjs` and attach the policy. The token of the user is valid for 15 minutes and can be renewed up to 1 hour.
|
|
|
|
`pki-client.hcl`:
|
|
|
|
```hcl
|
|
path "pki_int/sign/wif-client" {
|
|
capabilities = ["update"]
|
|
}
|
|
```
|
|
|
|
```bash
|
|
vault policy write pki-client pki-client.hcl
|
|
|
|
vault auth enable userpass
|
|
|
|
node vault_create_user.mjs --policy pki-client alice
|
|
```
|
|
|
|
`vault_create_user.mjs` takes the user name and one or more `--policy` options, one for each policy. The optional `--token-ttl` (default `15m`) and `--token-max-ttl` (default `1h`) options set the lifetime of the tokens of the user. It asks for the password twice without echoing it and creates the user through the Vault HTTP API with the `VAULT_ADDR` and `VAULT_TOKEN` of the administrator. The password never appears in the process list or in the shell history. It needs only Node.js 24 or later, no npm packages. When the server certificate is issued by a private CA, point Node.js at the CA certificate:
|
|
|
|
```bash
|
|
export NODE_EXTRA_CA_CERTS=/path/to/server-ca.pem
|
|
```
|
|
|
|
> **Note:** The `wif-client` role accepts any common name (`allow_any_name=true`). Every user with the `pki-client` policy can therefore request a certificate with any subject CN, including the CN that other users or workloads rely on as the WiF subject. Restrict the role (`allowed_domains`, `allow_bare_domains`, `enforce_hostnames`) when the users must not choose their CN freely.
|
|
|
|
## 2. Request a certificate
|
|
|
|
Role: **User**
|
|
|
|
1. Set the address of the Vault server. Set `VAULT_CACERT` as well when the server certificate is issued by a private CA.
|
|
|
|
```bash
|
|
export VAULT_ADDR=https://vault.example.com:8200
|
|
export VAULT_CACERT=/path/to/server-ca.pem
|
|
```
|
|
|
|
2. Unset `VAULT_TOKEN`, because a token in this environment variable takes precedence over the token stored by `vault login` and the CLI would keep using it. Then log in. The CLI asks for the password and stores the token in the token helper file (`~/.vault-token`).
|
|
|
|
```bash
|
|
unset VAULT_TOKEN
|
|
vault login -method=userpass username=alice
|
|
```
|
|
|
|
3. Generate the client key and the CSR locally. The key is never sent to Vault.
|
|
|
|
```bash
|
|
openssl req \
|
|
-newkey rsa:4096 \
|
|
-keyout client_key.pem \
|
|
-noenc \
|
|
-subj "/CN=test-client" \
|
|
-out client.csr
|
|
```
|
|
|
|
4. Sign the CSR with the Vault CA.
|
|
|
|
```bash
|
|
vault write -field=certificate pki_int/sign/wif-client \
|
|
csr=@client.csr \
|
|
common_name=test-client \
|
|
ttl=8760h > client_cert.pem
|
|
```
|
|
|
|
5. Check the certificate.
|
|
|
|
```bash
|
|
openssl x509 -in client_cert.pem -noout -subject -issuer -dates -ext extendedKeyUsage
|
|
```
|
|
|
|
6. Revoke the token when the work is done.
|
|
|
|
```bash
|
|
vault token revoke -self
|
|
```
|
|
|
|
The user token can only sign with the `wif-client` role. Reading the role or any other path returns `permission denied`.
|
|
|
|
To avoid storing the token on disk, log in with `-no-store -token-only` and keep the token in the environment:
|
|
|
|
```bash
|
|
export VAULT_TOKEN=$(vault login -no-store -token-only -method=userpass username=alice)
|
|
```
|
|
|
|
## Next steps
|
|
|
|
1. Create the credentials configuration `cred.json` for `client_cert.pem` and `client_key.pem`. The names come from `env.sh`.
|
|
|
|
```bash
|
|
gcloud iam workload-identity-pools create-cred-config \
|
|
"projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${POOL_ID}/providers/${PROVIDER_ID}" \
|
|
--service-account="${SA_EMAIL}" \
|
|
--credential-cert-path=client_cert.pem \
|
|
--credential-cert-private-key-path=client_key.pem \
|
|
--output-file=cred.json
|
|
```
|
|
|
|
2. Activate the service account with `gcloud auth login --cred-file=cred.json`.
|
|
3. Run the WIF tests.
|
|
|
|
Example test commands are in `test_wif.sh`.
|