160 lines
4.1 KiB
Markdown
160 lines
4.1 KiB
Markdown
---
|
|
layout: "docs"
|
|
page_title: "Auth Backend: Okta"
|
|
sidebar_current: "docs-auth-okta"
|
|
description: |-
|
|
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.
|
|
|
|
```shell
|
|
$ curl $VAULT_ADDR/v1/auth/okta/login/mitchellh \
|
|
-d '{ "password": "foo" }'
|
|
```
|
|
|
|
The response will be in JSON. For example:
|
|
|
|
```javascript
|
|
{
|
|
"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.
|