GitHub Teams can grant developers access to Vault secrets.
Here’s how it works, in action:
Let’s say we have a Vault server running and we want to give developers in our engineering/backend GitHub team access to a secret at kv/data/database/production.
First, we configure Vault’s GitHub auth method. This involves telling Vault how to communicate with GitHub.
vault auth enable github
vault write auth/github/config \
organization="my-github-org" \
api_url="https://api.github.com/" \
bearer_token="YOUR_GITHUB_PAT"
The bearer_token is a GitHub Personal Access Token (PAT) with read:org and read:user scopes. This allows Vault to query GitHub about your organization’s users and teams.
Next, we define a policy that grants access to the desired secret. Let’s call this policy backend-db-access.
# backend-db-access.hcl
path "kv/data/database/production" {
capabilities = ["read"]
}
We then load this policy into Vault:
vault policy write backend-db-access backend-db-access.hcl
Now, the crucial part: we create a role in Vault that maps the GitHub team to this policy. This role tells Vault: "When someone authenticates via GitHub and is a member of this specific team, grant them the following policies."
vault write auth/github/role/backend-developers \
organizations="my-github-org" \
teams="engineering/backend" \
token_policies="backend-db-access" \
token_ttl="30m"
Here, organizations specifies the GitHub organization, teams specifies the team (in owner/repo or owner/team_slug format if it’s an organization team), and token_policies lists the policies to be applied. token_ttl sets how long the Vault token issued to the developer will be valid.
When a developer from the engineering/backend team wants to access the secret, they’ll use their GitHub credentials to log in to Vault. This typically involves a CLI command like:
vault login -method=github user="your-github-username" org="my-github-org" token="YOUR_GITHUB_OAUTH_TOKEN"
Vault, using the provided OAuth token, will verify the user’s identity with GitHub and check their team memberships. If the user is indeed in the engineering/backend team, Vault will issue them a short-lived Vault token with the backend-db-access policy attached.
They can then read the secret:
vault kv get kv/data/database/production
The api_url can also point to a GitHub Enterprise instance if you’re not using GitHub.com.
The surprising truth about how this all ties together is that Vault doesn’t store GitHub users or teams. It relies entirely on GitHub’s API to perform these checks in real-time during the authentication process. When a developer logs in, Vault asks GitHub, "Is this user X a member of team Y in organization Z?" GitHub responds with a definitive yes or no, and Vault acts accordingly. This means your Vault configuration is always synchronized with your GitHub team structure without any manual updates on the Vault side for team membership changes.
This dynamic authorization based on external identity providers is a powerful pattern for managing access in complex organizations.
The next step is often to manage secrets for different environments, like staging and production, using distinct GitHub teams and Vault roles.