From 443df65ae52cb17b03efe254100bfec97aed58c8 Mon Sep 17 00:00:00 2001 From: Jeff Mitchell Date: Tue, 15 Aug 2017 22:01:34 -0400 Subject: [PATCH] Add PingID MFA docs (#3182) --- website/source/api/system/mfa-pingid.html.md | 108 ++++++++++++++ .../docs/vault-enterprise/mfa/index.html.md | 5 + .../docs/vault-enterprise/mfa/mfa-duo.html.md | 2 +- .../vault-enterprise/mfa/mfa-okta.html.md | 4 +- .../vault-enterprise/mfa/mfa-ping.html.md | 141 ++++++++++++++++++ .../vault-enterprise/mfa/mfa-totp.html.md | 2 +- website/source/layouts/api.erb | 11 +- website/source/layouts/docs.erb | 11 +- 8 files changed, 272 insertions(+), 12 deletions(-) create mode 100644 website/source/api/system/mfa-pingid.html.md create mode 100644 website/source/docs/vault-enterprise/mfa/mfa-ping.html.md diff --git a/website/source/api/system/mfa-pingid.html.md b/website/source/api/system/mfa-pingid.html.md new file mode 100644 index 0000000000..59b75ed3d6 --- /dev/null +++ b/website/source/api/system/mfa-pingid.html.md @@ -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: )` – Name of the MFA method. + +- `mount_accessor` `(string: )` - 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: )` – 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: )` - Name of the MFA method. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/sys/mfa/method/pingid/ping + +``` diff --git a/website/source/docs/vault-enterprise/mfa/index.html.md b/website/source/docs/vault-enterprise/mfa/index.html.md index 78b8c7abd1..20dfa2a8e9 100644 --- a/website/source/docs/vault-enterprise/mfa/index.html.md +++ b/website/source/docs/vault-enterprise/mfa/index.html.md @@ -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. diff --git a/website/source/docs/vault-enterprise/mfa/mfa-duo.html.md b/website/source/docs/vault-enterprise/mfa/mfa-duo.html.md index cc9df23e3b..4cdebfd5a9 100644 --- a/website/source/docs/vault-enterprise/mfa/mfa-duo.html.md +++ b/website/source/docs/vault-enterprise/mfa/mfa-duo.html.md @@ -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. diff --git a/website/source/docs/vault-enterprise/mfa/mfa-okta.html.md b/website/source/docs/vault-enterprise/mfa/mfa-okta.html.md index 7ae8808fba..ac69774dcc 100644 --- a/website/source/docs/vault-enterprise/mfa/mfa-okta.html.md +++ b/website/source/docs/vault-enterprise/mfa/mfa-okta.html.md @@ -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 diff --git a/website/source/docs/vault-enterprise/mfa/mfa-ping.html.md b/website/source/docs/vault-enterprise/mfa/mfa-ping.html.md new file mode 100644 index 0000000000..854d301b11 --- /dev/null +++ b/website/source/docs/vault-enterprise/mfa/mfa-ping.html.md @@ -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 +``` diff --git a/website/source/docs/vault-enterprise/mfa/mfa-totp.html.md b/website/source/docs/vault-enterprise/mfa/mfa-totp.html.md index 19909455a7..9963a9aeb5 100644 --- a/website/source/docs/vault-enterprise/mfa/mfa-totp.html.md +++ b/website/source/docs/vault-enterprise/mfa/mfa-totp.html.md @@ -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. diff --git a/website/source/layouts/api.erb b/website/source/layouts/api.erb index e15c9d0809..f26fd40598 100644 --- a/website/source/layouts/api.erb +++ b/website/source/layouts/api.erb @@ -179,14 +179,17 @@ > /sys/mfa diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index a4ceb0a521..b3b08ed4d1 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -384,14 +384,17 @@
  • > MFA