mirror of
https://github.com/optim-enterprises-bv/vault.git
synced 2025-10-30 18:17:55 +00:00
119 lines
3.5 KiB
Plaintext
119 lines
3.5 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: GitHub - Auth Methods
|
|
description: The GitHub auth method allows authentication with Vault using GitHub.
|
|
---
|
|
|
|
# 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.
|
|
|
|
~> If the GitHub team is part of an organization with SSO enabled, the user will
|
|
need to authorize the personal access token. Failing to do so for SSO users will
|
|
result in the personal access token not providing identity information. The token
|
|
issued by the auth method will only be assigned the default policy.
|
|
|
|
## 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.
|
|
|
|
```shell-session
|
|
$ 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`.
|
|
|
|
```shell-session
|
|
$ 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`:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```text
|
|
$ vault auth enable github
|
|
```
|
|
|
|
1. Use the `/config` endpoint to configure Vault to talk to GitHub.
|
|
|
|
```text
|
|
$ vault write auth/github/config organization=hashicorp
|
|
```
|
|
|
|
For the complete list of configuration options, please see the API
|
|
documentation.
|
|
|
|
1. Map the users/teams of that GitHub organization to policies in Vault. Team
|
|
names must be "slugified":
|
|
|
|
```text
|
|
$ 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:
|
|
|
|
```text
|
|
$ 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](/vault/api-docs/auth/github) for more
|
|
details.
|