Vault Auth using GitHub Personal Tokens

A while back, I wrote a post entitled Managing and Rotating API Tokens with PowerShell that touched on the topic of storing secrets into HashiCorp Vault. There is great value in having something like Vault to store encrypted secrets and using rotation to regularly render tokens and keys useless after a short period of time. My plan is to get deeper into how this all works and what has been configured.

In this post, I’ll lay the starting groundwork for the series by showcasing how to configure Vault to use an external authentication source: GitHub Personal Access Tokens. This makes it much easier for individuals and teams to automatically inherit the appropriate Vault policy and access and manage their desired secrets engines. The trade-off is that personal tokens are static and require more consideration when designing and deploying Vault, especially in a public space.

Everyone loves a secure vault.

In my case, Vault is deployed on an AWS EC2 t2.micro instance and is only accessible from an internal network that is piped directly into a co-location. There is no public access to Vault permitted and only ports 22 (SSH) and 8200 (UI/API) are allowed. This seemed like the most efficient design for the use case.

GitHub Personal Token Setup

Start by heading to GitHub to create a Personal Access Token that will be used to verify your identity. This can be found in Settings > Developer Settings > Personal Access Tokens (or use the link). Click on the Generate New Token button to start the wizard.

Enter a description in the Note field (mandatory) so that you don’t forget the purpose of this token. Mine is just vault-rubrik since this particular token is only used for the Vault instance running in the Rubrik lab.

The only permission you’ll need to grant is the read:org permission.

The only permission required is read:org for your GitHub token.

Click Generate Token at the bottom and then record the token value in your password safe. I suppose you could even store the token value in Vault since you can always go back into GitHub and generate a new token if this one is lost. However, I tend to keep my identity information stored apart from my applications and systems.

GitHub Single Sign-On (SSO) Organizations

If your GitHub Team is part of an SSO organization, you’ll need to authorize the token for access.

Use the Enable SSO drop down button next to your token to select the desired organization.
Click Authorize to complete the workflow with your SSO provider.

Make sure to authenticate your token with your organization’s SSO provider.

Failure to complete this step for SSO users will result in the token not being able to provide identify information. Your GitHub login will be restricted to the default policy.

HashiCorp Vault Auth for GitHub

The Vault documentation and API documentation do a good job at showing you the few commands required to configure GitHub as an authentication source. It really boils down to the commands below. I’ve substituted in a few {variables} that should be replaced with your GitHub Organization, GitHub Team, and Vault policy.

vault auth enable github
vault write auth/github/config organization={GITHUB_ORG}
vault write auth/github/map/teams/{GITHUB_TEAM} value={VAULT_POLICY}

Once complete, you can check out the GitHub auth configuration to make sure things are setup as desired. In my case, the GitHub Organization is rubrikinc.

vault read auth/github/config
 Key                        Value
 ---                        -----
 base_url                   n/a
 organization               rubrikinc
 token_bound_cidrs          []
 token_explicit_max_ttl     0s
 token_max_ttl              0s
 token_no_default_policy    false
 token_num_uses             0
 token_period               0s
 token_policies             []
 token_ttl                  0s
 token_type                 default

Look at the policy map to ensure it’s correct. The GitHub Team is developer-relations and the Vault policy is rubrik-manage for this scenario.

vault read auth/github/map/teams/developer-relations
 Key      Value
 ---      -----
 key      developer-relations
 value    rubrik-manage

If desired, you can also map users directly to a Vault policy as shown below. This is handy in case you are not part of a team or want to grant yourself a specific policy.

 vault write auth/github/map/users/chriswahl value=rubrik-manage

Note: You cannot map a team or user to the root policy. This is reserved for the root token.

If you find that a mistake was made, or you change your mind on the configuration of your organization, teams, or users, just run the related command an additional time with the correct values.

Vault Sign-in Using GitHub

Let’s try using our snazzy new GitHub token to authenticate against Vault. Change the Method to GitHub and supply your GitHub token to sign in.

Signing into Vault using a GitHub token.

After you authenticate via GitHub token, a new entity will appear with the desired policy associated. This represents your session. There is also an alias that leads back to the GitHub account information to see more information on the entity.

Here is an example of my entity after using GitHub to authenticate.

My account has been authorized by Vault via the GitHub auth.

At this point I have all of the permissions defined in the associated policy and can begin managing secrets that are accessible to me.

Thoughts

Giving your team access to Vault is a good first step in getting them to use Vault. I have found that most folks have a GitHub account, making the use of a GitHub personal token fairly trivial. However, applications and services that wish to use Vault would benefit more from other auth methods such as AppRole. Either way, avoiding the storage of secrets in plain text in spreadsheets or hard coded in scripts will go a long way in increasing your security awareness and defense in depth.