upstream/vault
1
0
Fork 0
mirror of https://github.com/hashicorp/vault.git synced 2026-06-09 08:55:13 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 11

Add PingID MFA docs (#3182)

Browse source
This commit is contained in:
Jeff Mitchell 2017-08-15 22:01:34 -04:00 committed by GitHub
parent 15f3418a7d
commit 443df65ae5
8 changed files with 272 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

108
website/source/api/system/mfa-pingid.html.md Normal file
View file

@ -0,0 +1,108 @@
---
layout: "api"
page_title: "/sys/mfa/method/pingid - HTTP API"
sidebar_current: "docs-http-system-mfa-pingid"
description: |-
The '/sys/mfa/method/pingid' endpoint focuses on managing PingID MFA behaviors in Vault Enterprise.
---
## Configure PingID MFA Method
This endpoint defines a MFA method of type PingID.
| Method | Path | Produces |
| :------- | :----------------------------- | :--------------------- |
| `POST` | `/sys/mfa/method/pingid/:name` | `204 (empty body)` |
### Parameters
- `name` `(string: <required>)` – Name of the MFA method.
- `mount_accessor` `(string: <required>)` - The mount to tie this method to for use in automatic mappings. The mapping will use the Name field of Personas associated with this mount as the username in the mapping.
- `username_format` `(string)` - A format string for mapping Identity names to MFA method names. Values to substitute should be placed in `{{}}`. For example, `"{{persona.name}}@example.com"`. If blank, the Persona's Name field will be used as-is. Currently-supported mappings:
- persona.name: The name returned by the mount configured via the `mount_accessor` parameter
- `settings_file_base64` `(string)` - A base64-encoded third-party settings file retrieved from PingID's configuration page.
### Sample Payload
```json
{
"mount_accessor": "auth_userpass_1793464a",
"settings_file_base64": "AA8owj3..."
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/sys/mfa/method/pingid/ping
```
## Read PingiD MFA Method
This endpoint queries the MFA configuration of PingID type for a given method
name.
| Method | Path | Produces |
| :------- | :----------------------------- | :----------------------- |
| `GET` | `/sys/mfa/method/pingid/: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/pingid/ping
```
### Sample Response
```json
{
"data": {
"use_signature": true,
"idp_url": "https://idpxnyl3m.pingidentity.com/pingid",
"admin_url": "https://idpxnyl3m.pingidentity.com/pingid",
"authenticator_url": "https://authenticator.pingone.com/pingid/ppm",
"mount_accessor": "auth_userpass_1793464a",
"name": "ping",
"org_alias": "181459b0-9fb1-4938-8c86...",
"type": "pingid",
"username_format": ""
}
}
```
## Delete PingID MFA Method
This endpoint deletes a PingID MFA method.
| Method | Path | Produces |
| :------- | :----------------------------- | :----------------------- |
| `DELETE` | `/sys/mfa/method/pingid/: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/pingid/ping
```

5
website/source/docs/vault-enterprise/mfa/index.html.md
View file

@ -32,6 +32,11 @@ MFA in Vault can be of the following types.
to the API. The Duo username will be derived from the caller identity's
persona.
- `PingID` - If PingID push is configured and enabled on a path, then the
enrolled device of the user will get a push notification to approve or deny
the access to the API. The PingID username will be derived from the caller
identity's persona.
## Configuring MFA Methods
MFA methods are globally managed within the `System Backend` using the HTTP API.

2
website/source/docs/vault-enterprise/mfa/mfa-duo.html.md
View file

@ -6,7 +6,7 @@ description: |-
Vault Enterprise supports Duo MFA type.
---
# MFA Duo
# Duo MFA
This page demonstrates the Duo MFA on ACL'd paths of Vault.

4
website/source/docs/vault-enterprise/mfa/mfa-okta.html.md
View file

@ -6,7 +6,7 @@ description: |-
Vault Enterprise supports Okta MFA type.
---
# MFA Okta
# Okta MFA
This page demonstrates the Okta MFA on ACL'd paths of Vault.
@ -34,7 +34,7 @@ userpass/ userpass auth_userpass_54b8e339 system system replicated
### Configure Okta MFA method
```
vault write sys/mfa/method/okta/okta mount_accessor=auth_userpass_54b8e339 org_name="dev-262775" api_token="0071u8PrReNkzmATGJAP2oDyIXwwveqx9vIOEyCZDC"
vault write sys/mfa/method/okta/my_okta mount_accessor=auth_userpass_54b8e339 org_name="dev-262775" api_token="0071u8PrReNkzmATGJAP2oDyIXwwveqx9vIOEyCZDC"
```
### Create Policy

141
website/source/docs/vault-enterprise/mfa/mfa-ping.html.md Normal file
View file

@ -0,0 +1,141 @@
---
layout: "docs"
page_title: "Vault Enterprise PingID MFA"
sidebar_current: "docs-vault-enterprise-mfa-pingid"
description: |-
Vault Enterprise supports PingID MFA type.
---
# PingID MFA
This page demonstrates PingID MFA on ACL'd paths of Vault.
## Steps
### Enable Auth Backend
```
vault auth-enable userpass
```
### Fetch Mount Accessor
```
vault auth -methods
```
```
Path Type Accessor Default TTL Max TTL Replication Behavior Description
...
userpass/ userpass auth_userpass_54b8e339 system system replicated
```
### Configure PingID MFA method
```
vault write sys/mfa/method/pingid/ping mount_accessor=auth_userpass_54b8e339 settings_file_base64="AABDwWaR..."
```
### Create Policy
Create a policy that gives access to secret through the MFA method created
above.
#### Sample Payload
```hcl
path "secret/foo" {
capabilities = ["read"]
mfa_methods = ["ping"]
}
```
```
vault policy-write ping-policy payload.hcl
```
### Create User
MFA works only for tokens that have identity information on them. Tokens
created by logging in using authentication backends will have the associated
identity information. Let's create a user in the `userpass` backend and
authenticate against it.
```
vault write auth/userpass/users/testuser password=testpassword policies=ping-policy
```
### Create Login Token
```
vault write auth/userpass/login/testuser password=testpassword
```
```
Key Value
--- -----
token 70f97438-e174-c03c-40fe-6bcdc1028d6c
token_accessor a91d97f4-1c7d-6af3-e4bf-971f74f9fab9
token_duration 768h0m0s
token_renewable true
token_policies [default ping-policy]
token_meta_username "testuser"
```
Note that the CLI is not authenticated with the newly created token yet, we did
not call `vault auth`, instead we used the login API to simply return a token.
### Fetch Entity ID From Token
Caller identity is represented by the `entity_id` property of the token.
```
vault token-lookup 70f97438-e174-c03c-40fe-6bcdc1028d6c
```
```
Key Value
--- -----
accessor a91d97f4-1c7d-6af3-e4bf-971f74f9fab9
creation_time 1502245243
creation_ttl 2764800
display_name userpass-testuser
entity_id 307d6c16-6f5c-4ae7-46a9-2d153ffcbc63
expire_time 2017-09-09T22:20:43.448543132-04:00
explicit_max_ttl 0
id 70f97438-e174-c03c-40fe-6bcdc1028d6c
issue_time 2017-08-08T22:20:43.448543003-04:00
meta map[username:testuser]
num_uses 0
orphan true
path auth/userpass/login/testuser
policies [default ping-policy]
renewable true
ttl 2764623
```
### Login
Authenticate the CLI to use the newly created token.
```
vault auth 70f97438-e174-c03c-40fe-6bcdc1028d6c
```
### Read Secret
Reading the secret will trigger a PingID push. This will be a blocking call until
the push notification is either approved or declined.
```
vault read secret/foo
```
```
Key Value
--- -----
refresh_interval 768h0m0s
data which can only be read after MFA validation
```

2
website/source/docs/vault-enterprise/mfa/mfa-totp.html.md
View file

@ -6,7 +6,7 @@ description: |-
Vault Enterprise supports TOTP MFA type.
---
# MFA TOTP
# TOTP MFA
This page demonstrates the TOTP MFA on ACL'd paths of Vault.

11
website/source/layouts/api.erb
View file

@ -179,14 +179,17 @@
<li<%= sidebar_current("docs-http-system-mfa") %>>
<a href="/api/system/mfa.html"><tt>/sys/mfa</tt></a>
<ul class="nav">
<li<%= sidebar_current("docs-http-system-mfa-totp") %>>
<a href="/api/system/mfa-totp.html"><tt>/sys/mfa/method/totp</tt></a>
<li<%= sidebar_current("docs-http-system-mfa-duo") %>>
<a href="/api/system/mfa-duo.html"><tt>/sys/mfa/method/duo</tt></a>
</li>
<li<%= sidebar_current("docs-http-system-mfa-okta") %>>
<a href="/api/system/mfa-okta.html"><tt>/sys/mfa/method/okta</tt></a>
</li>
<li<%= sidebar_current("docs-http-system-mfa-duo") %>>
<a href="/api/system/mfa-duo.html"><tt>/sys/mfa/method/duo</tt></a>
<li<%= sidebar_current("docs-http-system-mfa-pingid") %>>
<a href="/api/system/mfa-pingid.html"><tt>/sys/mfa/method/pingid</tt></a>
</li>
<li<%= sidebar_current("docs-http-system-mfa-totp") %>>
<a href="/api/system/mfa-totp.html"><tt>/sys/mfa/method/totp</tt></a>
</li>
</ul>
</li>

11
website/source/layouts/docs.erb
View file

@ -384,14 +384,17 @@
<li <%= sidebar_current("docs-vault-enterprise-mfa")%> >
<a href="/docs/vault-enterprise/mfa/index.html">MFA</a>
<ul class="nav">
<li <%= sidebar_current("docs-vault-enterprise-mfa-totp")%>>
<a href="/docs/vault-enterprise/mfa/mfa-totp.html">TOTP MFA</a>
<li <%= sidebar_current("docs-vault-enterprise-mfa-duo")%>>
<a href="/docs/vault-enterprise/mfa/mfa-duo.html">Duo MFA</a>
</li>
<li <%= sidebar_current("docs-vault-enterprise-mfa-okta")%>>
<a href="/docs/vault-enterprise/mfa/mfa-okta.html">Okta MFA</a>
</li>
<li <%= sidebar_current("docs-vault-enterprise-mfa-duo")%>>
<a href="/docs/vault-enterprise/mfa/mfa-duo.html">Duo MFA</a>
<li <%= sidebar_current("docs-vault-enterprise-mfa-pingid")%>>
<a href="/docs/vault-enterprise/mfa/mfa-pingid.html">PingID MFA</a>
</li>
<li <%= sidebar_current("docs-vault-enterprise-mfa-totp")%>>
<a href="/docs/vault-enterprise/mfa/mfa-totp.html">TOTP MFA</a>
</li>
</ul>
</li>