3.6 KiB
layout | page_title | sidebar_current | description |
---|---|---|---|
docs | Auth Backend: GitHub | docs-auth-github | The GitHub auth backend allows authentication with Vault using GitHub. |
Auth Backend: GitHub
Name: github
The GitHub auth backend can be used to authenticate with Vault using a GitHub personal access token. This method of authentication is most useful for humans: operators or developers using Vault directly via the CLI.
Authentication
Via the CLI
$ vault auth -method=github token=<api token>
...
Via the API
The endpoint for the GitHub login is auth/github/login
.
The github
mountpoint value in the url is the default mountpoint value. If you have mounted the github
backend with a different mountpoint, use that value.
The token
should be sent in the POST body encoded as JSON.
$ curl $VAULT_ADDR/v1/auth/github/login \
-d '{ "token": "your_github_personal_access_token" }'
The response will be in JSON. For example:
{
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": null,
"warnings": null,
"auth": {
"client_token": "c4f280f6-fdb2-18eb-89d3-589e2e834cdb",
"policies": [
"root"
],
"metadata": {
"org": "test_org",
"username": "rajanadar",
},
"lease_duration": 0,
"renewable": false
}
}
Configuration
First, you must enable the GitHub auth backend:
$ vault auth-enable github
Successfully enabled 'github' at 'github'!
Now when you run vault auth -methods
, the GitHub backend is available:
Path Type Description
github/ github
token/ token token based credentials
Prior to using the GitHub auth backend, it must be configured. To
configure it, use the /config
endpoint with the following arguments:
organization
(string, required) - The organization name a user must be a part of to authenticate.base_url
(string, optional) - For GitHub Enterprise or other API-compatible servers, the base URL to access the server.max_ttl
(string, optional) - Maximum duration after which authentication will be expired. This must be a string in a format parsable by Go's time.ParseDurationttl
(string, optional) - Duration after which authentication will be expired. This must be a string in a format parsable by Go's time.ParseDuration
###Generate a GitHub Personal Access Token
Access your Personal Access Tokens in GitHub at https://github.com/settings/tokens.
Generate a new Token that has the scope read:org
. Save the generated token. This is what you will provide to vault.
For example:
$ vault write auth/github/config organization=hashicorp
Success! Data written to: auth/github/config
After configuring that, you must map the teams of that organization to
policies within Vault. Use the map/teams/<team>
endpoints to do that.
Team names must be slugified, so if your team name is: Some Amazing Team
,
you will need to include it as: some-amazing-team
.
Example:
$ vault write auth/github/map/teams/owners value=root
Success! Data written to: auth/github/map/teams/owners
The above would make anyone in the "owners" team a root user in Vault (not recommended).
You can then auth with a user that is a member of the "owners" team using a Personal Access Token with the read:org
scope.
$ vault auth -method=github token=000000905b381e723b3d6a7d52f148a5d43c4b45
Successfully authenticated! The policies that are associated
with this token are listed below:
root