Added guides for requesting certificates remotely using

username-password or Entra ID authentication.

docs/vault-userpass.md

@@ -0,0 +1,109 @@
+# 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.
+
+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 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
+
+read -r -s -p "Password: " PASSWORD; echo
+printf '%s' "${PASSWORD}" | vault write auth/userpass/users/alice \
+    password=- \
+    token_policies=pki-client \
+    token_ttl=15m \
+    token_max_ttl=1h
+unset PASSWORD
+```
+
+`password=-` makes the CLI read the password from standard input, so it does not appear in the process list or in the shell history.
+
+> **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. Log in. The CLI asks for the password and stores the token in the token helper file (`~/.vault-token`).
+
+    ```bash
+    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)
+```