/terraform-vault-okta

Terraform module to configure Vault to use Okta with OIDC

Primary LanguageHCL

terraform-vault-okta

Terraform configuration to configure Vault with Okta using the OIDC auth plugin

Usage

module "okta" {
  source  = "onetwopunch/okta/vault"
  version = "<version>"

  okta_discovery_url = "<Okta Authorization Server Issuer>"
  okta_client_id     = "<Okta Vault App Client ID>"
  okta_client_secret = "<Okta Vault App Client Secret>"
  vault_addr         = "https://<Vault Domain>:8200"
  okta_bound_audiences = [
    "api://vault",
    "<Okta Vault App Client ID>"
  ]

  roles = {
    okta_admin = {
      token_policies = ["admin"]
      bound_groups   = ["vault_admins"]
    },
    okta_devs = {
      token_policies = ["devs"]
      bound_groups   = ["vault_devs"]
    }
  }
}

Login via the CLI

Login either via the UI or the CLI. If you want to get a local vault token, you'll need to run the following command, which will spin up a listener process by default on port 8250. You can override this with port=xxx in this command but you'll need to also update the redirect URIs in Okta and add the cli_port terraform variable.

vault login -method=oidc -path=okta_oidc role=okta-admin

Setting up Okta OIDC Auth

For this to work, you'll need to be an Okta administrator:

Setting up Groups

Let's create two groups: vault_admins or something similar. These groups will be given permissions to do things within Vault. Within those groups, let's add some users in the Okta Admin console.

Configuring the Authorization Server

Okta has a default authorization server that you can either edit or create another one. You get to this setting by going to Security > API > Authorization Servers. For this, we'll create a new one.

New Authorization Server for Vault

Click Add Authorization Server. For name enter Vault, for audience enter api://vault, and then enter a meaningful description.

Update Groups Claim

Now click into the authz server you just created and go to the Claims tab. We need to add a groups claim so Vault knows what group this user belongs to.

In the Claims tab, click on Add Claim with the following attributes:

  • Name: groups
  • Include in Token Type: ID Token Always
  • Value Type: Groups
  • Filter: Starts with: vault_
  • Include in: The following scopes: profile

Click Create

Access Policy

This policy grants Vault access to read the necessary scopes to the authorization

In the Access Policy tab, click Add Policy and give it the following attributes:

  • Name: Vault Policy
  • Description: Default policy for Vault
  • Assign to: All clients

In that policy, we need to add a rule with the following attributes:

  • Rule Name: default
  • Grant Type: Authorization Code Implicit
  • User is: Any user assigned the app
  • Scopes requested: Any Scopes

The rest of the config is dependent on your standards.

Terraform Variables

Take note of the following fields from this step, which we'll input into Terraform:

  • Issuer URI will be plugged in as oidc_discovery_url and bound_issuer in the OIDC path config
  • Audience will be plugged in as one of the bound_audiences in the role config

Vault Okta Application

We need to actually create a new web application for Vault to pop open the UI for Okta when requested.

Under Applications click, Add Application > Create New App with the following attributes:

  • Platform: Web
  • Sign on method: OpenID Connect

Then in the configuration:

  • Application Name: Vault
  • Application logo: `
  • Login Redirect URIs: https://<vault-domain>:8200/ui/vault/<vault-path>/oidc/callback

Note the <vault-path> denoted in the login URI is whatever value you are planning on using for the mount path for the OIDC plugin. In our case we used okta_oidc

Click Save

Now edit the general settings to ensure:

  • Allowed Grant Types: Implicit (Hybrid) Allow ID Token with implicit grant type
  • Login initiated by: App Only

Click the Sign On tab and edit:

  • OpenID Connect ID Token to include the same groups claim we added in the authorization server with the filter vault\_

Under Assignments add all the users or groups you want assigned to use Vault.

Under Okta API Scopes you'll need to grant the application acess to the following:

  • okta.groups.read
  • okta.users.read.self

Terraform Variables

Take note of the following fields from this step, which we'll input into Terraform:

  • Login Redirect URI will be plugged into the role config as one of allowed_redirect_uris
  • Client ID and Client Secret will be plugged into the path config as oidc_client_id and oidc_client_secret respectively
  • Under Sign On > OpenID Connect ID Token the Audience field which looks like 0oa... is passed in as a second value in the bound_audiences list in the role config.
  • The groups you created that are prefixed by vault\_ can be passed in as the allowed_groups variable in the role config.

Deploy

First export the following variables to point at your Vault cluster

export VAULT_ADDR=https://<vault-domain>:8200
export VAULT_CACERT=<path-to-ca-cert>

Then we use terraform to apply the changes:

terraform apply

Providers

Name Version
vault ~> 2.11

Inputs

Name Description Type Default Required
okta_bound_audiences A list of allowed token audiences list n/a yes
okta_client_id Okta Vault app client ID string n/a yes
okta_client_secret Okta Vault app client secret string n/a yes
okta_discovery_url Okta Authz server Issuer URI: i.e. https://.okta.com/oauth2/ string n/a yes
vault_addr Vault address in the form of https://domain:8200 string n/a yes
cli_port Port to open locally to login with the CLI number 8250 no
okta_allowed_groups Okta group for Vault admins list 
[
  "vault_admins"
]
 no
okta_mount_path Mount path for Okta auth string "okta_oidc" no
roles Map of Vault role names to their bound groups and token policies. Structure looks like this:
roles = {
  okta_admin = {
    token_policies = ["admin"]
    bound_groups = ["vault_admins"]
  },
  okta_devs  = {
    token_policies = ["devs"]
    bound_groups = ["vault_devs"]
  }
}
 map {} no
okta_default_lease_ttl Default lease TTL for Vault tokens string "768h" no
okta_max_lease_ttl Maximum lease TTL for Vault tokens string "768h" no
okta_token_type Token type for Vault tokens string "default-service" no

Outputs

Name Description
path Okta OIDC auth path
roles Role names created by this module