---
layout: docs
page_title: Okta - Auth Methods
description: |-
  The Okta auth method allows users to authenticate with Vault using Okta
  credentials.
---

# Okta Auth Method

The `okta` auth method 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](/api-docs/auth/okta#register-user) and [groups](/api-docs/auth/okta#register-group)
APIs.

## Authentication

### Via the CLI

The default path is `/okta`. If this auth method was enabled at a different
path, specify `-path=/my-path` in the CLI.

```shell-session
$ vault login -method=okta username=my-username
```

### Via the API

The default endpoint is `auth/okta/login`. If this auth method was enabled
at a different path, use that value instead of `okta`.

```shell-session
$ curl \
    --request POST \
    --data '{"password": "MY_PASSWORD"}' \
    http://127.0.0.1:8200/v1/auth/okta/login/my-username
```

The response will contain a token at `auth.client_token`:

```json
{
  "auth": {
    "client_token": "abcd1234-7890...",
    "policies": ["admins"],
    "metadata": {
      "username": "mitchellh"
    }
  }
}
```

### MFA

Okta Verify Push and TOTP MFA methods, and Google TOTP are supported during login. For TOTP, the current
passcode may be provided via the `totp` parameter:

```shell-session
$ vault login -method=okta username=my-username totp=123456
```

If both Okta TOTP and Google TOTP are enabled in your Okta account, make sure to pass in
the `provider` name to which the `totp` code belong.

```shell-session
$ vault login -method=okta username=my-username totp=123456 provider=GOOGLE
```

If `totp` is not set and MFA Push is configured in Okta, a Push will be sent during login.

The auth method uses the Okta [Authentication API](https://developer.okta.com/docs/reference/api/authn/).
It does not manage Okta [sessions](https://developer.okta.com/docs/reference/api/sessions/) for authenticated
users. This means that if MFA Push is configured, it will be required during both login and token renewal.

Note that this MFA support is integrated with Okta Auth and is limited strictly to login
operations. It is not related to [Enterprise MFA](https://www.vaultproject.io/docs/enterprise/mfa).

## Configuration

Auth methods must be configured in advance before users or machines can
authenticate. These steps are usually completed by an operator or configuration
management tool.

### Via the CLI

1. Enable the Okta auth method:

  ```shell-session
  $ vault auth enable okta
  ```

1. Configure Vault to communicate with your Okta account:

  ```shell-session
  $ vault write auth/okta/config \
     base_url="okta.com" \
     org_name="dev-123456" \
     api_token="00abcxyz..."
  ```

  -> **Note**: Support for okta auth with no API token is deprecated in Vault 1.4.
  If no token is supplied, Vault will function, but only locally configured
  group membership will be available. Without a token, groups will not be
  queried.

  For the complete list of configuration options, please see the
  [API documentation](/api-docs/auth/okta).

1. Map an Okta group to a Vault policy:

  ```shell-session
  $ vault write auth/okta/groups/scientists policies=nuclear-reactor
  ```

  In this example, anyone who successfully authenticates via Okta who is a
  member of the "scientists" group will receive a Vault token with the
  "nuclear-reactor" policy attached.

1. It is also possible to add users directly:

  ```shell-session
  $ vault write auth/okta/groups/engineers policies=autopilot
  $ vault write auth/okta/users/tesla groups=engineers
  ```

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

  -> **Note**: The user-policy mapping via group membership happens at token _creation
  time_. Any changes in group membership in Okta will not affect existing
  tokens that have already been provisioned. To see these changes, users
  will need to re-authenticate. You can force this by revoking the
  existing tokens.

### Okta API Token Permissions

The `okta` auth method uses the [Authentication](https://developer.okta.com/docs/reference/api/authn/)
and [User Groups](https://developer.okta.com/docs/reference/api/users/#get-user-s-groups)
APIs to authenticate users and obtain their group membership. The [`api_token`](/api-docs/auth/okta#api_token)
provided to the auth method's configuration must have sufficient privileges to exercise
these Okta APIs.

It is recommended to configure the auth method with a minimally permissive API token.
To do so, create the API token using an administrator with the standard
[Read-only Admin](https://help.okta.com/en/prod/Content/Topics/Security/administrators-read-only-admin.htm)
role. Custom roles may also be used to grant minimal permissions to the Okta API token.

## API

The Okta auth method has a full HTTP API. Please see the
[Okta Auth API](/api-docs/auth/okta) for more details.