Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: MFA API #3109

Merged
merged 1 commit into from
Aug 4, 2017
Merged

docs: MFA API #3109

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
241 changes: 241 additions & 0 deletions website/source/api/system/mfa.html.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,241 @@
---
layout: "api"
page_title: "/sys/mfa - HTTP API"
sidebar_current: "docs-http-system-mfa"
description: |-
The '/sys/mfa' endpoint focuses on managing MFA behaviors in Vault Enterprise MFA.
---

# `/sys/mfa`

~> **Enterprise Only** – These endpoints require Vault Enterprise.

## Configure MFA Method

This endpoint defines a specific `type` of MFA method. Once set, the `type` of the MFA
method is immutable.

| Method | Path | Produces |
| :------- | :------------------------ | :--------------------- |
| `POST` | `/sys/mfa/method/:name` | `204 (empty body)` |

### Parameters

- `name` `(string: <required>)` – Name of the MFA method.

- `type` `(string: <required>)` - Type of the MFA method. Currently it only
supports `totp`.

#### Type `totp` Parameters

- `totp_issuer` (string: <required>) - The name of the key's issuing organization.

- `totp_period` (int or duration format string: 30) - The length of time used to generate a counter for the TOTP token calculation.

- `totp_key_size` `(int: 20)` – Specifies the size in bytes of the generated key.

- `totp_qr_size` `(int: 200)` - The pixel size of the generated square QR code.

- `totp_algorithm` `(string: "SHA1")` – Specifies the hashing algorithm used to generate the TOTP code. Options include "SHA1", "SHA256" and "SHA512".

- `totp_digits` `(int: 6)` - The number of digits in the generated TOTP token. This value can either be 6 or 8.

- `totp_skew` `(int: 1)` - The number of delay periods that are allowed when validating a TOTP token. This value can either be 0 or 1.


### Sample Payload

```
{
"type": "totp",
"issuer": "vault",
}
```

### Sample Request

```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/sys/mfa/method/my_totp
```

## Read MFA Method

This endpoint queries the MFA configuration for a given name.

| Method | Path | Produces |
| :------- | :------------------------ | :----------------------- |
| `GET` | `/sys/mfa/method/:name` | `200 application/json` |

### Parameters

- `name` `(string: <required>)` – Name of the MFA method.

### Sample Request

```
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
https://vault.rocks/v1/sys/mfa/method/my_totp

```

### Sample Response

```
{
"data": {
"algorithm": "SHA1",
"digits": 6,
"id": "2dad2a3e-8ef0-fcf5-8b6f-d8ca14cabac4",
"issuer": "vault",
"key_size": 20,
"name": "my_totp",
"period": 30,
"qr_size": 200,
"skew": 1,
"type": "totp"
}
}
```

## Delete MFA Method

This endpoint deletes a MFA configuration.

| Method | Path | Produces |
| :------- | :------------------------ | :----------------------- |
| `DELETE` | `/sys/mfa/method/:name` | `204 (empty body)` |


### Parameters

- `name` `(string: <required>)` - Name of the MFA method.

### Sample Request

```
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
https://vault.rocks/v1/sys/mfa/method/my_totp

```

## Generate MFA Secret

This endpoint generates an MFA secret in the entity of the calling token, if it
doesn't exist already.

| Method | Path | Produces |
| :------- | :------------------------------- | :----------------------- |
| `GET` | `/sys/mfa/method/:name/generate` | `200 application/json` |

### Parameters

- `name` `(string: <required>)` - Name of the MFA method.

### Sample Request

```
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
https://vault.rocks/v1/sys/mfa/method/my_totp/generate
```

### Sample Response

```
{
"data": {
"barcode": "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 rkJggg==",
"url": "otpauth://totp/vault:4746fb81-028c-cd4e-026b-7dd18fe4c2f4?algorithm=SHA1&digits=6&issuer=vault&period=30&secret=XVE7TOZWJVEWQOATOD7 U53IEAJG72Z2I"
}
}
```

## Administratively Generate MFA Secret

This endpoint is can be used to generate an MFA secret on a given entity ID as
opposed to entity of the calling token.

| Method | Path | Produces |
| :------- | :-------------------------------------- | :----------------------- |
| `POST` | `/sys/mfa/method/:name/admin-generate` | `200 application/json` |

### Parameters

- `name` `(string: <required>)` - Name of the MFA method.

- `entity_id` `(string: <required>)` - Entity ID on which the generated secret
needs to get stored.

### Sample Payload

```
{
"entity_id":"4746fb81-028c-cd4e-026b-7dd18fe4c2f4"
}
```

### Sample Request

```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json
https://vault.rocks/v1/sys/mfa/method/my_totp/admin-generate
```

### Sample Response

```
{
"data": {
"barcode": "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",
"url": "otpauth://totp/vault:4746fb81-028c-cd4e-026b-7dd18fe4c2f4?algorithm=SHA1&digits=6&issuer=vault&period=30&secret=6HQ4RZ7GM6MMLRKVDCI23LXNZF7UDZ2U"
}
}
```

### Administratively Destroy MFA Secret

This endpoint deletes an MFA secret from the given entity ID. This needs to be
called if an existing secret in an entity needs to be overwritten by calling
`generate` or `admin-generate` APIs.

| Method | Path | Produces |
| :------- | :-------------------------------------- | :--------------------- |
| `POST` | `/sys/mfa/method/:name/admin-destroy` | `204 (empty body)` |

### Parameters

- `name` `(string: <required>)` – Name of the MFA method.

- `entity_id` `(string: <required>)` - Entity ID from which the MFA secret
should be removed.


### Sample Payload

```
{
"entity_id": "4746fb81-028c-cd4e-026b-7dd18fe4c2f4"
}
```

### Sample Request

```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json
https://vault.rocks/v1/sys/mfa/method/my_totp/admin-destroy
```
3 changes: 3 additions & 0 deletions website/source/layouts/api.erb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,9 @@
<li<%= sidebar_current("docs-http-system-leases") %>>
<a href="/api/system/leases.html"><tt>/sys/leases</tt></a>
</li>
<li<%= sidebar_current("docs-http-system-mfa") %>>
<a href="/api/system/mfa.html"><tt>/sys/mfa</tt></a>
</li>
<li<%= sidebar_current("docs-http-system-mounts") %>>
<a href="/api/system/mounts.html"><tt>/sys/mounts</tt></a>
</li>
Expand Down