2017-08-08 16:28:17 +00:00
|
|
|
---
|
2020-01-18 00:18:09 +00:00
|
|
|
layout: api
|
|
|
|
page_title: GitHub - Auth Methods - HTTP API
|
|
|
|
description: This is the API documentation for the Vault GitHub auth method.
|
2017-08-08 16:28:17 +00:00
|
|
|
---
|
|
|
|
|
2018-07-10 15:11:03 +00:00
|
|
|
# GitHub Auth Method (API)
|
2017-08-08 16:28:17 +00:00
|
|
|
|
2018-07-10 15:11:03 +00:00
|
|
|
This is the API documentation for the Vault GitHub auth method. For
|
|
|
|
general information about the usage and operation of the GitHub method, please
|
2020-01-22 20:05:41 +00:00
|
|
|
see the [Vault GitHub method documentation](/docs/auth/github).
|
2017-08-08 16:28:17 +00:00
|
|
|
|
2018-07-10 15:11:03 +00:00
|
|
|
This documentation assumes the GitHub method is enabled at the `/auth/github`
|
2017-09-21 17:39:12 +00:00
|
|
|
path in Vault. Since it is possible to enable auth methods at any location,
|
2017-08-09 15:22:19 +00:00
|
|
|
please update your API calls accordingly.
|
|
|
|
|
2017-09-13 01:48:52 +00:00
|
|
|
## Configure Method
|
2017-08-09 15:22:19 +00:00
|
|
|
|
2017-09-13 01:48:52 +00:00
|
|
|
Configures the connection parameters for GitHub. This path honors the
|
2017-08-09 15:22:19 +00:00
|
|
|
distinction between the `create` and `update` capabilities inside ACL policies.
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
| Method | Path |
|
|
|
|
| :----- | :-------------------- |
|
|
|
|
| `POST` | `/auth/github/config` |
|
2017-08-09 15:22:19 +00:00
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
2017-09-13 01:48:52 +00:00
|
|
|
- `organization` `(string: <required>)` - The organization users must be part
|
2017-08-09 15:22:19 +00:00
|
|
|
of.
|
2021-12-16 15:41:20 +00:00
|
|
|
- `organization_id` `(int: 0)` - The ID of the organization users must be part
|
|
|
|
of. Vault will attempt to fetch and set this value if it is not provided.
|
2017-08-09 15:22:19 +00:00
|
|
|
- `base_url` `(string: "")` - The API endpoint to use. Useful if you are running
|
|
|
|
GitHub Enterprise or an API-compatible authentication server.
|
2019-07-30 19:58:32 +00:00
|
|
|
|
2020-12-17 21:53:33 +00:00
|
|
|
@include 'tokenfields.mdx'
|
2017-08-09 15:22:19 +00:00
|
|
|
|
|
|
|
### Sample Payload
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"organization": "acme-org"
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2017-08-09 15:22:19 +00:00
|
|
|
$ curl \
|
|
|
|
--header "X-Vault-Token: ..." \
|
|
|
|
--request POST \
|
|
|
|
--data @payload.json \
|
2018-03-23 15:41:51 +00:00
|
|
|
http://127.0.0.1:8200/v1/auth/github/config
|
2017-08-09 15:22:19 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
## Read Configuration
|
|
|
|
|
2017-09-21 17:39:12 +00:00
|
|
|
Reads the GitHub configuration.
|
2017-08-09 15:22:19 +00:00
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
| Method | Path |
|
|
|
|
| :----- | :-------------------- |
|
|
|
|
| `GET` | `/auth/github/config` |
|
2017-08-09 15:22:19 +00:00
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2017-08-09 15:22:19 +00:00
|
|
|
$ curl \
|
|
|
|
--header "X-Vault-Token: ..." \
|
2018-03-23 15:41:51 +00:00
|
|
|
http://127.0.0.1:8200/v1/auth/github/config
|
2017-08-09 15:22:19 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6",
|
|
|
|
"lease_id": "",
|
|
|
|
"lease_duration": 0,
|
|
|
|
"renewable": false,
|
|
|
|
"data": {
|
|
|
|
"organization": "acme-org",
|
|
|
|
"base_url": "",
|
|
|
|
"ttl": "",
|
|
|
|
"max_ttl": ""
|
|
|
|
},
|
|
|
|
"warnings": null
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2018-03-26 23:56:14 +00:00
|
|
|
## Map GitHub Teams
|
|
|
|
|
|
|
|
Map a list of policies to a team that exists in the configured GitHub organization.
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
| Method | Path |
|
|
|
|
| :----- | :---------------------------------- |
|
|
|
|
| `POST` | `/auth/github/map/teams/:team_name` |
|
2018-03-26 23:56:14 +00:00
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
2019-11-19 22:17:45 +00:00
|
|
|
- `team_name` `(string)` - GitHub team name in "slugified" format
|
2018-03-26 23:56:14 +00:00
|
|
|
- `value` `(string)` - Comma separated list of policies to assign
|
|
|
|
|
|
|
|
### Sample Payload
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"value": "dev-policy"
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2018-03-26 23:56:14 +00:00
|
|
|
$ curl \
|
|
|
|
--header "X-Vault-Token: ..." \
|
|
|
|
--request POST \
|
|
|
|
--data @payload.json \
|
|
|
|
http://127.0.0.1:8200/v1/auth/github/map/teams/dev
|
|
|
|
```
|
|
|
|
|
|
|
|
## Read Team Mapping
|
|
|
|
|
|
|
|
Reads the GitHub team policy mapping.
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
| Method | Path |
|
|
|
|
| :----- | :---------------------------------- |
|
|
|
|
| `GET` | `/auth/github/map/teams/:team_name` |
|
2018-03-26 23:56:14 +00:00
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2018-03-26 23:56:14 +00:00
|
|
|
$ curl \
|
|
|
|
--header "X-Vault-Token: ..." \
|
|
|
|
http://127.0.0.1:8200/v1/auth/github/map/teams/dev
|
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6",
|
|
|
|
"lease_id": "",
|
|
|
|
"renewable": false,
|
|
|
|
"lease_duration": 0,
|
|
|
|
"data": {
|
|
|
|
"key": "dev",
|
|
|
|
"value": "dev-policy"
|
|
|
|
},
|
|
|
|
"wrap_info": null,
|
|
|
|
"warnings": null,
|
|
|
|
"auth": null
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
## Map GitHub Users
|
|
|
|
|
|
|
|
Map a list of policies to a specific GitHub user exists in the configured
|
|
|
|
organization.
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
| Method | Path |
|
|
|
|
| :----- | :---------------------------------- |
|
|
|
|
| `POST` | `/auth/github/map/users/:user_name` |
|
2018-03-26 23:56:14 +00:00
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
2019-11-19 22:17:45 +00:00
|
|
|
- `user_name` `(string)` - GitHub user name
|
2018-03-26 23:56:14 +00:00
|
|
|
- `value` `(string)` - Comma separated list of policies to assign
|
|
|
|
|
|
|
|
### Sample Payload
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"value": "sethvargo-policy"
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2018-03-26 23:56:14 +00:00
|
|
|
$ curl \
|
|
|
|
--header "X-Vault-Token: ..." \
|
|
|
|
--request POST \
|
|
|
|
--data @payload.json \
|
|
|
|
http://127.0.0.1:8200/v1/auth/github/map/users/sethvargo
|
|
|
|
```
|
|
|
|
|
|
|
|
The user with username `sethvargo` will be assigned the `sethvargo-policy`
|
|
|
|
policy **in addition to** any team policies.
|
|
|
|
|
|
|
|
## Read User Mapping
|
|
|
|
|
|
|
|
Reads the GitHub user policy mapping.
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
| Method | Path |
|
|
|
|
| :----- | :---------------------------------- |
|
|
|
|
| `GET` | `/auth/github/map/users/:user_name` |
|
2018-03-26 23:56:14 +00:00
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2018-03-26 23:56:14 +00:00
|
|
|
$ curl \
|
|
|
|
--header "X-Vault-Token: ..." \
|
|
|
|
http://127.0.0.1:8200/v1/auth/github/map/users/sethvargo
|
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"request_id": "764b6f88-efba-51bd-ed62-cf1c9e80e37a",
|
|
|
|
"lease_id": "",
|
|
|
|
"renewable": false,
|
|
|
|
"lease_duration": 0,
|
|
|
|
"data": {
|
|
|
|
"key": "sethvargo",
|
|
|
|
"value": "sethvargo-policy"
|
|
|
|
},
|
|
|
|
"wrap_info": null,
|
|
|
|
"warnings": null,
|
|
|
|
"auth": null
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2017-08-09 15:22:19 +00:00
|
|
|
## Login
|
|
|
|
|
|
|
|
Login using GitHub access token.
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
| Method | Path |
|
|
|
|
| :----- | :------------------- |
|
|
|
|
| `POST` | `/auth/github/login` |
|
2017-08-09 15:22:19 +00:00
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
- `token` `(string: <required>)` - GitHub personal API token.
|
|
|
|
|
|
|
|
### Sample Payload
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"token": "ABC123..."
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2017-08-09 15:22:19 +00:00
|
|
|
$ curl \
|
|
|
|
--request POST \
|
2018-03-23 15:41:51 +00:00
|
|
|
http://127.0.0.1:8200/v1/auth/github/login
|
2017-08-09 15:22:19 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
```javascript
|
|
|
|
{
|
|
|
|
"lease_id": "",
|
|
|
|
"renewable": false,
|
|
|
|
"lease_duration": 0,
|
|
|
|
"data": null,
|
|
|
|
"warnings": null,
|
|
|
|
"auth": {
|
|
|
|
"client_token": "64d2a8f2-2a2f-5688-102b-e6088b76e344",
|
|
|
|
"accessor": "18bb8f89-826a-56ee-c65b-1736dc5ea27d",
|
|
|
|
"policies": ["default"],
|
|
|
|
"metadata": {
|
|
|
|
"username": "fred",
|
|
|
|
"org": "acme-org"
|
|
|
|
},
|
|
|
|
},
|
|
|
|
"lease_duration": 7200,
|
|
|
|
"renewable": true
|
|
|
|
}
|
2020-01-18 00:18:09 +00:00
|
|
|
```
|