HashiCorp Vault — OIDC & GitHub Auth

2 minute read

OIDC enables browser-based SSO authentication for humans, while GitHub auth lets developer teams authenticate using their GitHub credentials. Both provide a smooth user experience.

OIDC Auth Method

OIDC (OpenID Connect) enables SSO through identity providers like Google, Okta, Azure AD, and Auth0.

Enable OIDC

vault auth enable oidc

Configure OIDC (Okta Example)

vault write auth/oidc/config \
    oidc_discovery_url="https://your-org.okta.com" \
    oidc_client_id="0oa1abc..." \
    oidc_client_secret="client-secret-here" \
    default_role="default"

Create an OIDC Role

vault write auth/oidc/role/default \
    user_claim="email" \
    bound_audiences="0oa1abc..." \
    allowed_redirect_uris="http://localhost:8250/oidc/callback" \
    allowed_redirect_uris="https://vault.example.com:8200/ui/vault/auth/oidc/oidc/callback" \
    token_policies="dev-team" \
    token_ttl=8h

Login with OIDC

# CLI — opens a browser for SSO
vault login -method=oidc

# Specify a role
vault login -method=oidc role=default

# In the Vault UI, select "OIDC" from the login dropdown

OIDC with Azure AD

vault write auth/oidc/config \
    oidc_discovery_url="https://login.microsoftonline.com/TENANT_ID/v2.0" \
    oidc_client_id="app-client-id" \
    oidc_client_secret="client-secret" \
    default_role="azure-users"

vault write auth/oidc/role/azure-users \
    user_claim="email" \
    groups_claim="groups" \
    bound_audiences="app-client-id" \
    allowed_redirect_uris="http://localhost:8250/oidc/callback" \
    allowed_redirect_uris="https://vault.example.com:8200/ui/vault/auth/oidc/oidc/callback" \
    token_policies="default" \
    token_ttl=8h

Map OIDC Groups to Policies

# Create external group alias for "engineering" group
vault write identity/group \
    name="engineering" \
    policies="dev-team" \
    type="external"

GitHub Auth Method

GitHub auth validates a user’s GitHub personal access token and maps GitHub teams/organizations to Vault policies.

Enable GitHub

vault auth enable github

Configure GitHub Organization

vault write auth/github/config \
    organization="my-org" \
    token_ttl=8h \
    token_max_ttl=24h

Map Teams to Policies

# Map GitHub team "backend" to Vault policies
vault write auth/github/map/teams/backend value="dev-team,deploy"

# Map GitHub team "sre" to ops policies
vault write auth/github/map/teams/sre value="ops-team,admin-read"

# Map specific users
vault write auth/github/map/users/alice value="admin-team"

Login with GitHub

# Generate a GitHub Personal Access Token with "read:org" scope
# Then login:
vault login -method=github token="ghp_abc123..."

Expected output:

Key                    Value
---                    -----
token                  hvs.CAESI...
token_accessor         abc123
token_duration         8h
token_renewable        true
token_policies         ["default", "dev-team", "deploy"]
token_meta_org         my-org
token_meta_username    alice

API Login

curl -s --request POST \
     --data '{"token": "ghp_abc123..."}' \
     "$VAULT_ADDR/v1/auth/github/login" | jq

OIDC vs GitHub Comparison

Feature OIDC GitHub
Provider Any OIDC provider (Okta, Azure AD, Google, Auth0) GitHub.com or GitHub Enterprise
Login flow Browser redirect (SSO) Personal access token
Group mapping Via OIDC claims Via GitHub teams
MFA Provider-managed GitHub-managed
Best for Enterprise SSO Developer teams using GitHub
Setup complexity Medium Low

Quick Reference

Command Description
vault auth enable oidc Enable OIDC
vault write auth/oidc/config ... Configure OIDC provider
vault write auth/oidc/role/NAME ... Create OIDC role
vault login -method=oidc Login via OIDC (browser)
vault auth enable github Enable GitHub
vault write auth/github/config organization=ORG Configure GitHub org
vault write auth/github/map/teams/TEAM value=POLICY Map team
vault login -method=github token=TOKEN Login via GitHub

Next: Kubernetes & AWS Auth

You may also enjoy