• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Vault
  • Install
  • Tutorials
  • Documentation
  • API
  • Integrations
  • Try Cloud(opens in new tab)
  • Sign up
Vault Home

Documentation

Skip to main content
  • Documentation
  • What is Vault?
  • Use Cases

  • Browser Support
  • Installing Vault

    • Overview
    • AppRole
    • AliCloud
    • AWS
    • Azure
    • Cloud Foundry
    • GitHub
    • Google Cloud
    • Kerberos
    • Kubernetes
    • LDAP
    • Oracle Cloud Infrastructure
    • Okta
    • RADIUS
    • TLS Certificates
    • Tokens
    • Username & Password

    • App ID
      DEPRECATEDDEPRECATED
  • Vault Integration Program
  • Vault Interoperability Matrix
  • Troubleshoot






  • Glossary


  • Resources

  • Tutorial Library
  • Certifications
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  1. Developer
  2. Vault
  3. Documentation
  4. Auth Methods
  5. GitHub
  • Vault
  • v1.11.x
  • v1.10.x
  • v1.9.x
  • v1.8.x
  • v1.7.x
  • v1.6.x
  • v1.5.x
  • v1.4.x

ยปGitHub Auth Method

The github auth method 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.

IMPORTANT NOTE: Vault does not support an OAuth workflow to generate GitHub tokens, so does not act as a GitHub application. As a result, this method uses personal access tokens. If the risks below are unacceptable to you, consider using a different authentication method.

Any valid GitHub access token with the read:org scope for any user belonging to the Vault-configured organization can be used for authentication. If such a token is stolen from a third party service, and the attacker is able to make network calls to Vault, they will be able to log in as the user that generated the access token.

Authentication

Via the CLI

The default path is /github. If this auth method was enabled at a different path, specify -path=/my-path in the CLI.

$ vault login -method=github token="MY_TOKEN"

Via the API

The default endpoint is auth/github/login. If this auth method was enabled at a different path, use that value instead of github.

$ curl \
    --request POST \
    --data '{"token": "MY_TOKEN"}' \
    http://127.0.0.1:8200/v1/auth/github/login

The response will contain a token at auth.client_token:

{
  "auth": {
    "renewable": true,
    "lease_duration": 2764800,
    "metadata": {
      "username": "my-user",
      "org": "my-org"
    },
    "policies": ["default", "dev-policy"],
    "accessor": "f93c4b2d-18b6-2b50-7a32-0fecf88237b8",
    "client_token": "1977fceb-3bfa-6c71-4d1f-b64af98ac018"
  }
}

Configuration

Auth methods must be configured in advance before users or machines can authenticate. These steps are usually completed by an operator or configuration management tool.

  1. Enable the GitHub auth method:

    $ vault auth enable github
    
  2. Use the /config endpoint to configure Vault to talk to GitHub.

    $ vault write auth/github/config organization=hashicorp
    

    For the complete list of configuration options, please see the API documentation.

  3. Map the users/teams of that GitHub organization to policies in Vault. Team names must be "slugified":

    $ vault write auth/github/map/teams/dev value=dev-policy
    

    In this example, when members of the team "dev" in the organization "hashicorp" authenticate to Vault using a GitHub personal access token, they will be given a token with the "dev-policy" policy attached.


    You can also create mappings for a specific user map/users/<user> endpoint:

    $ vault write auth/github/map/users/sethvargo value=sethvargo-policy
    

    In this example, a user with the GitHub username sethvargo will be assigned the sethvargo-policy policy in addition to any team policies.

API

The GitHub auth method has a full HTTP API. Please see the GitHub Auth API for more details.

Edit this page on GitHub

On this page

  1. GitHub Auth Method
  2. Authentication
  3. Configuration
  4. API
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)