open-vault/website/source/docs/auth/okta.html.md

layout	page_title	sidebar_current	description
docs	Auth Backend: Okta	docs-auth-okta	The Okta auth backend allows users to authenticate with Vault using Okta credentials.

Auth Backend: Okta

Name: okta

The Okta auth backend allows authentication using Okta and user/password credentials. This allows Vault to be integrated into environments using Okta.

The mapping of groups in Okta to Vault policies is managed by using the users/ and groups/ paths.

Authentication

Via the CLI

$ vault auth -method=okta username=mitchellh
Password (will be hidden):
Successfully authenticated! The policies that are associated
with this token are listed below:

admins

Via the API

The endpoint for the login is auth/okta/login/<username>.

The password should be sent in the POST body encoded as JSON.

$ curl $VAULT_ADDR/v1/auth/okta/login/mitchellh \
    -d '{ "password": "foo" }'

The response will be in JSON. For example:

{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": null,
  "auth": {
    "client_token": "c4f280f6-fdb2-18eb-89d3-589e2e834cdb",
    "policies": [
      "admins"
    ],
    "metadata": {
      "username": "mitchellh"
    },
    "lease_duration": 0,
    "renewable": false
  }
}

Configuration

First, you must enable the Okta auth backend:

$ vault auth-enable okta
Successfully enabled 'okta' at 'okta'!

Now when you run vault auth -methods, the Okta backend is available:

Path       Type      Description
okta/      okta
token/     token     token based credentials

To use the Okta auth backend, it must first be configured for your Okta account. The configuration options are categorized and detailed below.

Configuration is written to auth/okta/config.

Connection parameters

• organization (string, required) - The Okta organization. This will be the first part of the url https://XXX.okta.com url.
• token (string, optional) - The Okta API token. This is required to query Okta for user group membership. If this is not supplied only locally configured groups will be enabled. This can be generated from http://developer.okta.com/docs/api/getting_started/getting_a_token.html
• base_url (string, optional) - The Okta url. Examples: oktapreview.com, The default is okta.com

Use vault path-help for more details.

Examples:

Scenario 1

• Okta organization XXXTest.
• With no token supplied only locally configured group membership will be available. Groups will not be queried from Okta.

$ vault write auth/okta/config \
    organization="XXXTest"
...

Scenario 2

• Okta organization dev-123456.
• Okta base_url for developer account oktapreview.com
• API token 00KzlTNCqDf0enpQKYSAYUt88KHqXax6dT11xEZz_g. This will allow group membership to be queried.

$ vault write auth/okta/config base_url="oktapreview.com" \
    organization="dev-123456" \
    token="00KzlTNCqDf0enpQKYSAYUt88KHqXax6dT11xEZz_g" 
...

Okta Group -> Policy Mapping

Next we want to create a mapping from an Okta group to a Vault policy:

$ vault write auth/okta/groups/scientists policies=foo,bar

This maps the Okta group "scientists" to the "foo" and "bar" Vault policies.

We can also add specific Okta users to additional (potentially non-Okta) groups:

$ vault write auth/okta/groups/engineers policies=foobar
$ vault write auth/okta/users/tesla groups=engineers

This adds the Okta user "tesla" to the "engineers" group, which maps to the "foobar" Vault policy.

Finally, we can test this by authenticating:

$ vault auth -method=okta username=tesla
Password (will be hidden):
Successfully authenticated! The policies that are associated
with this token are listed below:

bar, foo, foobar

Note on Okta Group's

Groups can only be pulled from Okta if an API token is configured via token

Note on policy mapping

It should be noted that user -> policy mapping (via group membership) happens at token creation time. And changes in group membership in Okta will not affect tokens that have already been provisioned. To see these changes, old tokens should be revoked and the user should be asked to reauthenticate.