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:

{
  "auth": {
    "renewable": true,
    "lease_duration": 2764800,
    "metadata": {
      "username": "vishalnayak",
      "org": "hashicorp"
    },
    "policies": [
      "default",
      "dev-policy"
    ],
    "accessor": "f93c4b2d-18b6-2b50-7a32-0fecf88237b8",
    "client_token": "1977fceb-3bfa-6c71-4d1f-b64af98ac018"
  },
  "warnings": null,
  "wrap_info": null,
  "data": null,
  "lease_duration": 0,
  "renewable": false,
  "lease_id": "",
  "request_id": "3c346f3b-e089-39ab-a953-a349f2284e3c"
}

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/dev value=dev-policy
Success! Data written to: auth/github/map/teams/dev

The above would make anyone in the dev team receive tokens with the policy dev-policy.

You can then auth with a user that is a member of the dev team using a Personal Access Token with the read:org scope.

GitHub token can also be supplied from the env variable VAULT_AUTH_GITHUB_TOKEN.

$ vault auth -method=github token=000000905b381e723b3d6a7d52f148a5d43c4b45
Successfully authenticated! You are now logged in.
The token below is already saved in the session. You do not
need to "vault auth" again with the token.
token: 0d9ab511-bc25-4fb6-a58b-94ce12b8da9c
token_duration: 2764800
token_policies: [default dev-policy]

Clients can use this token to perform an allowed set of operations on all the paths contained by the policy set.