GitHub OIDC and Kubernetes Authentication with HashiCorp Vault

Modern applications require secure access to secrets throughout the software delivery lifecycle. From CI/CD pipelines to Kubernetes workloads, managing credentials securely is critical. Traditionally, teams store Vault tokens, API keys, and other credentials as static secrets. This creates operational overhead and increases security risks. HashiCorp Vault provides two powerful authentication methods that eliminate the need for long-lived credentials: - GitHub OIDC Authentication for CI/CD pipelines - Kubernetes Authentication for workloads running inside Kubernetes clusters This blog explains how both authentication methods work and how to configure them for secure secret management. Official Vault Documentation: https://developer.hashicorp.com/vault --- ## Why Use Identity-Based Authentication Identity-based authentication provides: - No static Vault tokens - No hardcoded credentials - Short-lived authentication - Improved auditability - Better access control - Reduced attack surface - Easier credential management For teams deploying applications on https://nife.io/platform, identity-based authentication simplifies secret management while improving security. --- # Part 1: GitHub OIDC Authentication with Vault ## How GitHub OIDC Works Authentication flow: ```text GitHub Actions ↓ Requests OIDC Token ↓ GitHub Issues JWT Token ↓ Vault JWT Authentication ↓ Vault Validates: - Issuer - Audience - Repository Claim ↓ Vault Issues Temporary Token ↓ GitHub Reads Secrets ``` Instead of storing Vault credentials in GitHub Secrets, GitHub proves its identity using a signed JWT token. --- ## Step 1: Start Vault Server ```bash export VAULT_ADDR='http://127.0.0.1:8200' export VAULT_TOKEN='ROOT_TOKEN' ``` Verify: ```bash vault status ``` --- ## Step 2: Enable KV Secrets Engine ```bash vault secrets enable -path=kv kv-v2 ``` Verify: ```bash vault secrets list ``` --- ## Step 3: Store Example Secrets ```bash vault kv put kv/demo \ USERNAME="admin" \ PASSWORD="mypassword" ``` Verify: ```bash vault kv get kv/demo ``` --- ## Step 4: Create Vault Policy ```bash cat > demo-policy.hcl <<EOF path "kv/data/demo" { capabilities = ["read"] } EOF ``` ```bash vault policy write demo-policy demo-policy.hcl ``` --- ## Step 5: Enable JWT Authentication ```bash vault auth enable jwt ``` Verify: ```bash vault auth list ``` --- ## Step 6: Configure GitHub OIDC Provider ```bash vault write auth/jwt/config \ oidc_discovery_url="https://token.actions.githubusercontent.com" \ bound_issuer="https://token.actions.githubusercontent.com" \ jwt_supported_algs="RS256" \ default_role="github-role" ``` Verify: ```bash vault read auth/jwt/config ``` --- ## Step 7: Create Vault JWT Role ```bash cat > role.json <<EOF { "role_type": "jwt", "user_claim": "repository", "bound_audiences": "https://token.actions.githubusercontent.com", "bound_claims": { "repository": "myorg/myrepo" }, "policies": "demo-policy", "ttl": "15m" } EOF ``` Replace `myorg/myrepo` with your GitHub repository. ```bash vault write auth/jwt/role/github-role @role.json ``` --- ## Step 8: Add GitHub Secret Navigate to: ```text Repository Settings → Secrets and Variables → Actions ``` Add: | Secret Name | Value | |------------|--------| | VAULT_ADDR | https://your-vault-domain.com | --- ## Step 9: Create GitHub Workflow ```yaml name: GitHub OIDC Vault Demo on: workflow_dispatch: jobs: demo: runs-on: ubuntu-latest permissions: id-token: write contents: read steps: - name: Checkout Repository uses: actions/checkout@v4 - name: Authenticate to Vault uses: hashicorp/vault-action@v2 with: url: ${{ secrets.VAULT_ADDR }} method: jwt path: jwt role: github-role jwtGithubAudience: https://token.actions.githubusercontent.com secrets: | kv/data/demo USERNAME | USERNAME kv/data/demo PASSWORD | PASSWORD ``` --- ## Step 10: Run the Workflow Navigate to: ```text Actions → GitHub OIDC Vault Demo → Run Workflow ``` Expected: ```text USERNAME=*** PASSWORD=*** ``` GitHub automatically masks secret values. --- # Part 2: Kubernetes Authentication with Vault GitHub OIDC solves authentication for CI/CD pipelines. For applications running inside Kubernetes, Vault provides Kubernetes Authentication. Instead of using Vault tokens, applications authenticate using Kubernetes ServiceAccounts. --- ## How Kubernetes Authentication Works ```text Application Pod ↓ ServiceAccount Token ↓ Vault Kubernetes Auth ↓ Vault Validates Token ↓ Vault Issues Temporary Token ↓ Application Reads Secrets ``` This allows workloads to securely access Vault without storing credentials. --- ## Step 1: Enable Kubernetes Authentication ```bash vault auth enable kubernetes ``` Verify: ```bash vault auth list ``` Expected: ```text kubernetes/ ``` --- ## Step 2: Create Vault Policy ```bash cat > sampleapp-policy.hcl <<EOF path "kv/data/sampleapp" { capabilities = ["read"] } EOF ``` ```bash vault policy write sampleapp-policy sampleapp-policy.hcl ``` --- ## Step 3: Create ServiceAccount ```yaml apiVersion: v1 kind: ServiceAccount metadata: name: sampleapp-sa namespace: sampleapp123 ``` Apply: ```bash kubectl apply -f sa.yaml ``` --- ## Step 4: Get Kubernetes API Information Get Kubernetes API server: ```bash kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}' ``` Example: ```text https://127.0.0.1:8443 ``` Export CA certificate: ```bash kubectl config view --raw --minify \ --flatten \ -o jsonpath='{.clusters[0].cluster.certificate-authority-data}' | base64 -d > ca.crt ``` Generate ServiceAccount token: ```bash kubectl create token sampleapp-sa -n sampleapp123 ``` Copy the generated token. --- ## Step 5: Configure Vault Kubernetes Authentication ```bash vault write auth/kubernetes/config \ token_reviewer_jwt="PASTE_TOKEN_HERE" \ kubernetes_host="https://127.0.0.1:8443" \ kubernetes_ca_cert=@ca.crt ``` If using Minikube, verify the API endpoint: ```bash kubectl cluster-info ``` Use the correct Kubernetes API address if different. --- ## Step 6: Create Vault Kubernetes Role ```bash vault write auth/kubernetes/role/sampleapp-role \ bound_service_account_names=sampleapp-sa \ bound_service_account_namespaces=sampleapp123 \ policies=sampleapp-policy \ ttl=24h ``` This role maps Kubernetes identities to Vault policies. --- ## Step 7: Update Deployment Add ServiceAccount to your deployment: ```yaml spec: serviceAccountName: sampleapp-sa ``` --- ## Step 8: Configure Application Environment Variables Remove: ```yaml - name: VAULT_TOKEN ``` Use: ```yaml env: - name: USE_VAULT value: "true" - name: VAULT_ADDR value: "http://vault-ip:8200" - name: VAULT_SECRET_PATH value: "kv/sampleapp" - name: VAULT_ROLE value: "sampleapp-role" ``` Important: Do not use: ```text http://127.0.0.1:8200 ``` inside Kubernetes pods. Use: ```text http:// :8200 ``` or ```text https://vault.example.com ``` --- ## Step 9: Application Authentication Flow Inside the pod: ```text /var/run/secrets/kubernetes.io/serviceaccount/token ``` Application calls: ```text /v1/auth/kubernetes/login ``` Vault validates the ServiceAccount token and returns a temporary Vault token. The application can then read secrets from: ```text kv/sampleapp ``` --- ## Simplified GitHub Deployment Workflow After moving authentication to Kubernetes workloads, GitHub no longer needs direct Vault access. ```yaml - name: Deploy uses: appleboy/ssh-action@v1.1.0 with: host: ${{ secrets.HOST_DNS }} username: ${{ secrets.USERNAME }} key: ${{ secrets.AWS_SSH_PRIVATE_KEY }} script: | kubectl set image deployment/sampleapp-deployment \ sampleapp-container=nife123/sampleapp:${VERSION} \ -n sampleapp123 kubectl rollout restart deployment/sampleapp-deployment -n sampleapp123 kubectl rollout status deployment/sampleapp-deployment -n sampleapp123 ``` --- ## OIDC vs Kubernetes Authentication | Feature | GitHub OIDC | Kubernetes Auth | |----------|------------|----------------| | Used By | CI/CD Pipelines | Running Applications | | Identity Source | GitHub OIDC Token | ServiceAccount Token | | Vault Token | Temporary | Temporary | | Static Credentials | No | No | | Recommended | Yes | Yes | --- ## Best Practices - Enable Vault audit logging - Use HTTPS everywhere - Apply least-privilege policies - Restrict GitHub repositories using bound claims - Restrict Kubernetes roles by namespace - Use short token TTL values - Rotate Kubernetes ServiceAccount credentials regularly --- ## Conclusion HashiCorp Vault provides multiple identity-based authentication mechanisms that eliminate the need for static credentials. GitHub OIDC enables secure CI/CD authentication, while Kubernetes Authentication enables secure workload authentication using ServiceAccounts. Together, these approaches improve security, simplify secret management, and provide a scalable foundation for cloud-native applications. When combined with platforms like https://nife.io/solutions/deploy_containarized_apps, they help build secure and production-ready deployment workflows. Learn more: https://nife.io

Deploy your next app in minutes, not days.