Setup Single Sign-On of Hashicorp Vault with Opstella

Prerequisites

To Setup Single Sign-On with Opstella, you need

• 📦Opstella Keycloak
  • Your dedicated Keycloak Realm. foobar-opstella ; Please change accordingly
• 🔑OpenID Connect Credentials: Client ID, Client Secret.
  • Gather Client ID, Client Secret - from Procuring Keycloak Credentials
• 🗝️ Vault Root Token
  • Token will be xyz.AbC123...dEf456 format (28 Characters)
  • See more on: Gather Credentials from Auto-Unsealing Process

Vault Single Sign-On Integration

1. Connect to 🟢 Management Kubernetes Cluster ; i.e w/ Kubeconfig File

   Set Kubeconfig File

   export KUBECONFIG="$HOME/opstella-installation/kubeconfigs/management_cluster.yaml"

2. Get into vault-0 (Vault Cluster-Lead Instance) container using kubectl exec.

   kubectl exec -i -t --namespace devsecops-system pod/vault-0 -- sh

   Note

   Your shell prompt will be changed to the container

   YOUR-SHELL $> kubectl exec -i -t --namespace devsecops-system pod/vault-0 -- sh
   / $

3. Use the retrieved 🗝️ Vault Root Token to authenticate with Vault

   • Token will be xyz.AbC123...dEf456 format (28 Characters)

   export VAULT_TOKEN="CHANGEME"

4. Enable Single Sign-On with OIDC Authentication

   vault auth enable oidc

5. Specify OIDC Authentication Information

   Using Opstella Keycloak Information

   • Opstella Keycloak Domain: ${KEYCLOAK_DOMAIN} (idp.${BASE_DOMAIN} by default)

     ⚠️ Do not re-export it here. KEYCLOAK_DOMAIN is already set in Shell Variables; re-exporting the default overwrites a site that uses a different hostname, and the resulting issuer only fails later, at OIDC discovery time.

   • Opstella Keycloak Realm Name: ${KEYCLOAK_REALM}

     💡 Your dedicated Keycloak Realm. foobar-opstella ; Please change accordingly

     export KEYCLOAK_REALM="foobar-opstella"

   • OIDC Issuer Endpoint from Opstella Keycloak Information

     export OIDC_ISSUER_ENDPOINT="https://${KEYCLOAK_DOMAIN}/realms/${KEYCLOAK_REALM}"

   • Client ID: vault

   • Client secret: CHANGEME

     export VAULT_OIDC_CLIENT_ID="vault"

     export VAULT_OIDC_CLIENT_SECRET="CHANGEME"

6. Create OIDC Authentication Configuration

   If your Keycloak uses an internal certificate, you need to provide the internal Root CA to Vault. Set VAULT_TRUST_ROOT_CA_PATH to the exact path of that certificate.

   export VAULT_TRUST_ROOT_CA_PATH="/path/to/your/root-ca.pem"

   cat <<EOF > /tmp/oidc_config.json
   {
     "oidc_discovery_url": "${OIDC_ISSUER_ENDPOINT}",
     "oidc_client_id": "${VAULT_OIDC_CLIENT_ID}",
     "oidc_client_secret": "${VAULT_OIDC_CLIENT_SECRET}",
     "default_role": "default",
     "oidc_discovery_ca_pem": $(jq -R -s '.' < ${VAULT_TRUST_ROOT_CA_PATH})
   }
   EOF

   💡 Note: With a publicly trusted certificate, drop the oidc_discovery_ca_pem line (and the trailing comma on the line above it).

   💡 Note on jq: $(jq -R -s '.' < file) escapes the multi-line PEM safely for a JSON value. Avoid chaining the flags as -Rs, which behaves differently across jq versions.

   vault write auth/oidc/config validates while it writes

   Vault fetches the discovery document as part of the write. If the certificate is not trusted, the command fails and nothing is stored — there is no half-configured state to fix up afterwards, so get the CA right before running the next step.

7. Create OIDC Authentication Backend Configuration

   • Vault Domain: ${VAULT_DOMAIN} is assumed to be exported as defined in the Shell Variables guide.

     cat <<EOF > /tmp/oidc_backend.json
     {
     "role_type": "oidc",
     "token_ttl": "1h",
     "token_max_ttl": "1h",
     "bound_audiences": "vault",
     "user_claim": "sub",
     "groups_claim": "groups",
     "claim_mappings": {
         "preferred_username": "username",
         "email": "email"
     },
     "allowed_redirect_uris": [
         "https://${VAULT_DOMAIN}/ui/vault/auth/oidc/oidc/callback",
         "http://${VAULT_DOMAIN}/oidc/callback"
     ]
     }
     EOF

8. Write OIDC Authentication Configuration

   Confirm Vault can reach the Identity Provider first — the write below performs discovery and stores nothing at all if it fails:

   curl -s -o /dev/null -w "%{http_code}\n" \
     "https://${KEYCLOAK_DOMAIN}/realms/${KEYCLOAK_REALM}/.well-known/openid-configuration"

   💡 Must print 200, run from a host on the same network path as the Vault Pod. Do not continue on anything else: the auth method stays enabled with no configuration behind it, which is worse than not having started.

   vault write auth/oidc/config @/tmp/oidc_config.json

   vault write sys/auth/oidc/tune token_type="default-service" listing_visibility="unauth" description="Opstella SSO Integration" default_lease_ttl="1h" max_lease_ttl="1h"

9. Write OIDC Authentication Backend Configuration

   vault write auth/oidc/role/default @/tmp/oidc_backend.json

10. Verify the OIDC endpoint answers

    curl -s "https://${VAULT_DOMAIN}/v1/auth/oidc/oidc/auth_url" \
      --request POST \
      --data "{\"role\":\"default\",\"redirect_uri\":\"https://${VAULT_DOMAIN}/ui/vault/auth/oidc/oidc/callback\"}"

    💡 The response contains an auth_url pointing at your Keycloak Realm. An empty auth_url means the role or the redirect URI does not match.

    Paths that are easy to get wrong

    • The auth URL path is auth/oidc/oidc/auth_url. auth/oidc/oidc_auth_url returns Code: 404 ... unsupported path.
    • The browser callback is /v1/auth/oidc/oidc/callback?state=...&code=....
    • The vault-0 container ships without curl, so run this from a host that can reach the Vault Ingress.

11. Clean up

    rm -r /tmp/*.json

You will be testing Single Sign-On Integration in End-to-End Testing/Single Sign-On for Vault