open-vault/website/source/docs/auth/github.html.md

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.ParseDuration
• ttl (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/admins value=root
Success! Data written to: auth/github/map/teams/admins

The above would make anyone in the "admins" team a root user in Vault (not recommended).

You can then auth with a user that is a member of the "admins" 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