Chris Hoffman
GitHub
parent
1b6847c8e5
commit
b7ef4a3a6f
|
|
@ -0,0 +1,323 @@
|
|||
---
|
||||
layout: "api"
|
||||
page_title: "Azure - Auth Methods - HTTP API"
|
||||
sidebar_current: "docs-http-auth-azure"
|
||||
description: |-
|
||||
This is the API documentation for the Vault Azure authentication
|
||||
method plugin.
|
||||
---
|
||||
|
||||
# Azure Auth Method (API)
|
||||
|
||||
This is the API documentation for the Vault Azure auth method
|
||||
plugin. To learn more about the usage and operation, see the
|
||||
[Vault Azure method documentation](/docs/auth/azure.html).
|
||||
|
||||
This documentation assumes the plugin method is mounted at the
|
||||
`/auth/azure` path in Vault. Since it is possible to enable auth methods
|
||||
at any location, please update your API calls accordingly.
|
||||
|
||||
## Configure
|
||||
|
||||
Configures the credentials required for the plugin to perform API calls
|
||||
to Azure. These credentials will be used to query the metadata about the
|
||||
virtual machine.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `POST` | `/auth/azure/config` | `204 (empty body)` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `tenant_id` `(string: <required>)` - The tenant id for the Azure Active Directory organization.
|
||||
- `resource` `(string: <required>)` - The configured URL for the application registered in Azure Active Directory.
|
||||
- `client_id` `(string: '')` - The client id for credentials to query the Azure APIs. Currently read permissions to query compute resources are required.
|
||||
- `client_secret` `(string: '')` - The client secret for credentials to query the Azure APIs.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"tenant_id": "kd83...",
|
||||
"resource": "https://vault.hashicorp.com/",
|
||||
"client_id": "12ud...",
|
||||
"client_secret": "DUJDS3..."
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data @payload.json \
|
||||
https://vault.rocks/v1/auth/azure/config
|
||||
```
|
||||
|
||||
# Read Config
|
||||
|
||||
Returns the previously configured config, including credentials.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `GET` | `/auth/azure/config` | `200 application/json` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
https://vault.rocks/v1/auth/azure/config
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"data":{
|
||||
"tenant_id": "kd83...",
|
||||
"resource": "https://vault.hashicorp.com/",
|
||||
"client_id": "12ud...",
|
||||
"client_secret": "DUJDS3..."
|
||||
},
|
||||
...
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
## Delete Config
|
||||
|
||||
Deletes the previously configured Azure config and credentials.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `DELETE` | `/auth/azure/config` | `204 (empty body)` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request DELETE \
|
||||
https://vault.rocks/v1/auth/azure/config
|
||||
```
|
||||
|
||||
## Create Role
|
||||
|
||||
Registers a role in the method. Role types have specific entities
|
||||
that can perform login operations against this endpoint. Constraints specific
|
||||
to the role type must be set on the role. These are applied to the authenticated
|
||||
entities attempting to login.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `POST` | `/auth/azure/role/:name` | `204 (empty body)` |
|
||||
|
||||
### Parameters
|
||||
- `name` `(string: <required>)` - Name of the role.
|
||||
- `policies` `(array: [])` - Policies to be set on tokens issued using this
|
||||
role.
|
||||
- `ttl` `(string: "")` - The TTL period of tokens issued using this role in
|
||||
seconds.
|
||||
- `max_ttl` `(string: "")` - The maximum allowed lifetime of tokens
|
||||
issued in seconds using this role.
|
||||
- `period` `(string: "")` - If set, indicates that the token generated using
|
||||
this role should never expire. The token should be renewed within the duration
|
||||
specified by this value. At each renewal, the token's TTL will be set to the
|
||||
value of this parameter.
|
||||
- `bound_service_principal_ids` `(array: [])` - The list of Service Principal IDs
|
||||
that login is restricted to.
|
||||
- `bound_group_ids` `(array: [])` - The list of group ids that login is restricted
|
||||
to.
|
||||
- `bound_location` `(array: [])` - The list of locations that login is restricted to.
|
||||
- `bound_subscription_ids` `(array: [])` - The list of subscription IDs that login
|
||||
is restricted to.
|
||||
- `bound_resource_group_names` `(array: [])` - The list of resource groups that
|
||||
login is restricted to.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"policies": [
|
||||
"default",
|
||||
"dev",
|
||||
"prod"
|
||||
],
|
||||
"max_ttl": 1800000,
|
||||
"max_jwt_exp": 10000,
|
||||
"bound_resource_groups": [
|
||||
"vault-dev",
|
||||
"vault-staging",
|
||||
"vault-prod"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data @payload.json \
|
||||
https://vault.rocks/v1/auth/azure/role/dev-role
|
||||
```
|
||||
|
||||
## Read Role
|
||||
|
||||
Returns the previously registered role configuration.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `GET` | `/auth/azure/role/:name` | `200 application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `name` `(string: <required>)` - Name of the role.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
https://vault.rocks/v1/auth/azure/role/dev-role
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"data":{
|
||||
"policies": [
|
||||
"default",
|
||||
"dev",
|
||||
"prod"
|
||||
],
|
||||
"max_ttl": 1800000,
|
||||
"max_jwt_exp": 10000,
|
||||
"bound_resource_groups": [
|
||||
"vault-dev",
|
||||
"vault-staging",
|
||||
"vault-prod"
|
||||
]
|
||||
},
|
||||
...
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
## List Roles
|
||||
|
||||
Lists all the roles that are registered with the plugin.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `LIST` | `/auth/azure/roles` | `200 application/json` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request LIST \
|
||||
https://vault.rocks/v1/auth/azure/roles
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"keys": [
|
||||
"dev-role",
|
||||
"prod-role"
|
||||
]
|
||||
},
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
## Delete Role
|
||||
|
||||
Deletes the previously registered role.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `DELETE` | `/auth/azure/role/:name` | `204 (empty body)` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `name` `(string: <required>)` - Name of the role.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request DELETE \
|
||||
https://vault.rocks/v1/auth/azure/role/dev-role
|
||||
```
|
||||
|
||||
## Login
|
||||
|
||||
Fetch a token. This endpoint takes a signed JSON Web Token (JWT) and
|
||||
a role name for some entity. It verifies the JWT signature to authenticate that
|
||||
entity and then authorizes the entity for the given role.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :--------------------------- | :--------------------- |
|
||||
| `POST` | `/auth/azure/login` | `200 application/json` |
|
||||
|
||||
### Sample Payload
|
||||
|
||||
- `role` `(string: <required>)` - Name of the role against which the login is being
|
||||
attempted.
|
||||
- `jwt` `(string: <required>)` - Signed [JSON Web Token](https://tools.ietf.org/html/rfc7519) (JWT) from Azure MSI.
|
||||
- `subscription_id` `(string: "")` - The subscription ID for the machine that
|
||||
generated the MSI token. This information can be obtained through instance
|
||||
metadata.
|
||||
- `resource_group_name` `(string: "")` - The resource group for the machine that
|
||||
generated the MSI token. This information can be obtained through instance
|
||||
metadata.
|
||||
- `vm_name` `(string: "")` - The virtual machine name for the machine that
|
||||
generated the MSI token. This information can be obtained through instance
|
||||
metadata.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"role": "dev-role",
|
||||
"jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--request POST \
|
||||
--data @payload.json \
|
||||
https://vault.rocks/v1/auth/azure/login
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"auth":{
|
||||
"client_token":"f33f8c72-924e-11f8-cb43-ac59d697597c",
|
||||
"accessor":"0e9e354a-520f-df04-6867-ee81cae3d42d",
|
||||
"policies":[
|
||||
"default",
|
||||
"dev",
|
||||
"prod"
|
||||
],
|
||||
"lease_duration":2764800,
|
||||
"renewable":true
|
||||
},
|
||||
...
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,190 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Azure - Auth Methods"
|
||||
sidebar_current: "docs-auth-azure"
|
||||
description: |-
|
||||
The azure auth method plugin allows automated authentication of Azure Active
|
||||
Directory.
|
||||
---
|
||||
|
||||
# Azure Auth Method
|
||||
|
||||
The `azure` auth method allows authentication against Vault using
|
||||
Azure Active Directory credentials. It treats Azure as a Trusted Third Party
|
||||
and expects a [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519)
|
||||
signed by Azure Active Directory for the configured tenant.
|
||||
|
||||
Currently supports authentication for:
|
||||
|
||||
* [Azure Managed Service Identity (MSI)](https://docs.microsoft.com/en-us/azure/active-directory/managed-service-identity/overview)
|
||||
|
||||
## Prerequisites:
|
||||
|
||||
The following documentation assumes that the method has been
|
||||
[mounted](/docs/plugin/index.html) at `auth/azure`.
|
||||
|
||||
* A configured [Azure AD application](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-integrating-applications) which is used as the resource for generating MSI access tokens.
|
||||
* Client credentials (shared secret) for accessing the Azure Resource Manager with read access to compute endpoints. See [Azure AD Service to Service Client Credentials](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-protocols-oauth-service-to-service)
|
||||
|
||||
If Vault is hosted on Azure, Vault can use MSI to access Azure instead of a shared secret. MSI must be [enabled]((https://docs.microsoft.com/en-us/azure/active-directory/managed-service-identity/qs-configure-portal-windows-vm) on the VMs hosting Vault.
|
||||
|
||||
The next sections review how the authN/Z workflows work. If you
|
||||
have already reviewed these sections, here are some quick links to:
|
||||
|
||||
* [Usage](#usage)
|
||||
* [API documentation](/api/auth/azure/index.html) docs.
|
||||
|
||||
## Authentication
|
||||
|
||||
### Via the CLI
|
||||
|
||||
The default path is `/auth/azure`. If this auth method was enabled at a different
|
||||
path, specify `auth/my-path/login` instead.
|
||||
|
||||
```text
|
||||
$ vault write auth/azure/login \
|
||||
role="dev-role" \
|
||||
jwt="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
|
||||
subscription_id="12345-..." \
|
||||
resource_group_name="test-group" \
|
||||
vm_name="test-vm"
|
||||
```
|
||||
|
||||
The `role` and `jwt` parameters are required. When using bound_service_pricipal_ids and bound_groups in the token roles, all the information is required in the JWT. When using other bound_* parameters, calls to Azure APIs will be made and subscription id, resource group name, and vm name are all required and can be obtained through instance metadata.
|
||||
|
||||
### Via the API
|
||||
|
||||
The default endpoint is `auth/azure/login`. If this auth method was enabled
|
||||
at a different path, use that value instead of `azure`.
|
||||
|
||||
```sh
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data '{"role": "dev-role", "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}' \
|
||||
https://vault.rocks/v1/auth/azure/login
|
||||
```
|
||||
|
||||
The response will contain the token at `auth.client_token`:
|
||||
|
||||
```json
|
||||
{
|
||||
"auth": {
|
||||
"client_token": "f33f8c72-924e-11f8-cb43-ac59d697597c",
|
||||
"accessor": "0e9e354a-520f-df04-6867-ee81cae3d42d",
|
||||
"policies": [
|
||||
"default",
|
||||
"dev",
|
||||
"prod"
|
||||
],
|
||||
"lease_duration": 2764800,
|
||||
"renewable": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Auth methods must be configured in advance before machines can authenticate.
|
||||
These steps are usually completed by an operator or configuration management
|
||||
tool.
|
||||
|
||||
### Via the CLI
|
||||
|
||||
1. Enable Azure authentication in Vault:
|
||||
|
||||
```text
|
||||
$ vault auth enable azure
|
||||
```
|
||||
|
||||
1. Configure the Azure auth method:
|
||||
|
||||
```text
|
||||
$ vault write auth/azure/config \
|
||||
tenant_id= 7cd1f227-ca67-4fc6-a1a4-9888ea7f388c \
|
||||
resource=https://vault.hashicorp.com \
|
||||
client_id=dd794de4-4c6c-40b3-a930-d84cd32e9699 \
|
||||
client_secret=IT3B2XfZvWnfB98s1cie8EMe7zWg483Xy8zY004=
|
||||
```
|
||||
|
||||
For the complete list of configuration options, please see the API
|
||||
documentation.
|
||||
|
||||
1. Create a role:
|
||||
|
||||
```text
|
||||
$ vault write auth/azure/role/dev-role \
|
||||
policies="prod,dev" \
|
||||
bound_subscription_ids=6a1d5988-5917-4221-b224-904cd7e24a25 \
|
||||
bound_resource_groups=vault
|
||||
```
|
||||
|
||||
Roles are associated with an authentication type/entity and a set of Vault
|
||||
policies. Roles are configured with constraints specific to the
|
||||
authentication type, as well as overall constraints and configuration for
|
||||
the generated auth tokens.
|
||||
|
||||
For the complete list of role options, please see the API documentation.
|
||||
|
||||
### Via the API
|
||||
|
||||
1. Enable Azure authentication in Vault:
|
||||
|
||||
```sh
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data '{"type": "azure"}' \
|
||||
https://vault.rocks/v1/sys/auth/azure
|
||||
```
|
||||
|
||||
1. Configure the Azure auth method:
|
||||
|
||||
```sh
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data '{"tenant_id": "...", "resource": "..."}' \
|
||||
https://vault.rocks/v1/auth/azure/config
|
||||
```
|
||||
|
||||
1. Create a role:
|
||||
|
||||
```sh
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data '{"policies": ["dev", "prod"], ...}' \
|
||||
https://vault.rocks/v1/auth/azure/role/dev-role
|
||||
```
|
||||
|
||||
### Plugin Setup
|
||||
|
||||
~> The following section is only relevant if you decide to enable the azure auth
|
||||
method as an external plugin. The azure plugin method is integrated into Vault as
|
||||
a builtin method by default.
|
||||
|
||||
Assuming you have saved the binary `vault-plugin-auth-azure` to some folder and
|
||||
configured the [plugin directory](/docs/internals/plugins.html#plugin-directory)
|
||||
for your server at `path/to/plugins`:
|
||||
|
||||
|
||||
1. Enable the plugin in the catalog:
|
||||
|
||||
```text
|
||||
$ vault write sys/plugins/catalog/azure-auth \
|
||||
command="vault-plugin-auth-azure" \
|
||||
sha_256="..."
|
||||
```
|
||||
|
||||
1. Enable the azure auth method as a plugin:
|
||||
|
||||
```text
|
||||
$ vault auth enable -path=azure -plugin-name=azure-auth plugin
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
The Azure Auth Plugin has a full HTTP API. Please see the [API docs]
|
||||
(/api/auth/azure/index.html) for more details.
|
||||
|
||||
|
|
@ -135,6 +135,9 @@
|
|||
<li<%= sidebar_current("docs-http-auth-aws") %>>
|
||||
<a href="/api/auth/aws/index.html">AWS</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-http-auth-azure") %>>
|
||||
<a href="/api/auth/azure/index.html">Azure</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-http-auth-github") %>>
|
||||
<a href="/api/auth/github/index.html">Github</a>
|
||||
</li>
|
||||
|
|
|
|||
|
|
@ -472,6 +472,10 @@
|
|||
<a href="/docs/auth/aws.html">AWS</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-auth-azure") %>>
|
||||
<a href="/docs/auth/azure.html">Azure</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-auth-gcp") %>>
|
||||
<a href="/docs/auth/gcp.html">Google Cloud</a>
|
||||
</li>
|
||||
|
|
|
|||
Loading…
Reference in New Issue