How to use Terraform to manage Okta

What is the Okta Terraform Provider?

Okta handles authentication and authorization for a lot of organizations. If you already manage infrastructure as code (IaC) with Terraform, the Okta provider lets you bring your identity setup into the same workflow. The first part of this post covers the basics: how to use the Terraform Okta provider to manage Okta resources from your configuration files.

The second part looks at what you get by connecting Okta to Scalr. SAML SSO with Okta is available on every Scalr plan, including the free tier; automated user provisioning via SCIM is an Enterprise-plan feature.

Understanding the Okta Terraform Provider

What is the Okta Terraform Provider?

Terraform uses providers to talk to an external API and manage resources there. The Okta provider sits between your infrastructure code and Okta's Identity Cloud. With it, you define and manage Okta resources like users, groups, and applications directly in your Terraform modules. Your identity configuration becomes codified and version-controlled, and you can reproduce it across environments instead of clicking through the Okta console each time.

Prerequisites

Before you start, make sure you have the following in place:

1. Terraform Installed: Make sure you have Terraform or OpenTofu installed on your machine. You can download the latest versions from the Terraform or OpenTofu websites.
2. Okta Account: You'll need an Okta account with the necessary permissions to manage Okta resources. If you don't have an Okta account, sign up for one on the Okta website.
3. Okta API Token: Generate an Okta API token from the Okta Developer Console. Terraform uses this token to authenticate to Okta.
4. Scalr Account: If you want to use Scalr as the remote backend, sign up for a free account here. You can use it as a development environment while you explore Scalr.

Using the Okta Provider: Step-by-Step Guide

Step 1: Define Required Providers and Provider Configuration

Start by configuring the Okta Terraform provider in your Terraform code. Open your Terraform configuration file (commonly named main.tf) and add the following block:

terraform {
  required_providers {
    okta = {
      source = "okta/okta"
      version = "~> 4.6.3"
    }
  }
}
 
provider "okta" {
   org_name    = "your-okta-org-name"
   api_token   = "your-okta-api-token"
}

Replace "your-okta-org-name" with your Okta organization name and "your-okta-api-token" with the Okta API token you generated earlier. The latest version of the official Okta Terraform documentation can be found here.

Step 2: Manage Okta Users

Now, create an Okta user using an Okta Terraform resource. The full resource reference is in the Terraform registry here. Add the following code to your configuration:

resource "okta_user" "example_user" {
   first_name = "John"
   last_name  = "Doe"
   email      = "[email protected]"
   login      = "[email protected]"
}

This Terraform code defines a resource "example_user" with the specified Okta profile details.

Step 3: Manage Okta Groups

Extend your Terraform code to manage Okta groups. Add the following Okta objects into the Terraform resource code:

resource "okta_group" "example_group" {
 name        = "example_group"
 description = "Example Okta Group"
}

This Terraform code defines an Okta group named "example_group" with the specified name and description.

Step 4: Manage Okta Applications

To manage Okta applications using Terraform, add the following Okta objects into the code:

resource "okta_app_saml" "example" {
  label                    = "example_app"
  sso_url                  = "https://example_app.com"
  recipient                = "https://example_app.com"
  destination              = "https://example_app.com"
  audience                 = "https://example_app.com/audience"
  subject_name_id_template = "$${user.userName}"
  subject_name_id_format   = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
  signature_algorithm      = "RSA_SHA256"
  digest_algorithm         = "SHA256"
  authn_context_class_ref  = "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"
 
  attribute_statements {
    type         = "GROUP"
    name         = "groups"
    filter_type  = "REGEX"
    filter_value = ".*"
  }
}

This example creates a SAML application in Okta named "example_app" with the specified settings.

Step 5: Run Terraform Commands

Once you've defined your Okta resources through the Okta Terraform provider, navigate to the directory containing your Terraform configuration file and run the following commands:

terraform init
terraform plan
terraform apply

Terraform will initialize the Okta provider and apply the changes to your Okta environment. After a successful run, Terraform creates the state file.

Best Practices and Advanced Usage

Variables and Dynamic Configurations

Use Terraform variables to make your configurations more dynamic. Instead of hardcoding values, use variables so your scripts stay reusable and flexible.

variable "okta_org_name" {
 description = "The name of your Okta organization"
}
 
provider "okta" {
 org_name    = var.okta_org_name
 api_token   = "your-okta-api-token"
}

Remote State Management

Consider using remote state management to store your Terraform state files securely. Services like Scalr or AWS S3 can be configured as remote backends to store state files. Here is an example of connecting to Scalr:

terraform {
  backend "remote" {
    hostname = "<account-name>.scalr.io"
    organization = "<scalr-environment-name>"
 
    workspaces {
      name = "<workspace-name>"
    }
  }
}

Data Sources

Consider using Okta data sources to pull information from other resources or workspaces into the run.

Provider Summary

The provider supports plenty more than users, groups, and applications: factors, rules, and policies are all worth a look once the basics are in place. The Terraform documentation for the Okta provider goes deeper, with reference material and examples for each resource.

Once Okta lives in your Terraform workflow, identity changes go through the same plan-and-apply review as the rest of your infrastructure.

Scalr's Integration with Okta

Scalr is a Terraform automation and collaboration platform, and it integrates directly with Okta. Scalr is featured in the Okta catalog, so wiring up Okta SAML takes a few clicks rather than a manual setup. Your team then signs into Scalr with the same Okta credentials they already use everywhere else.

Scalr also supports SCIM-based user and group provisioning on top of SAML SSO. SCIM is currently supported for Okta and Microsoft Entra ID.

Key Advantages of SCIM Integration

When you create a user in Okta, SCIM provisions the matching account in Scalr automatically, so onboarding doesn't need manual steps. The reverse happens too. When a user is de-provisioned in Okta, SCIM deactivates the corresponding Scalr account, which revokes access for people who no longer need it.

SCIM also keeps the two systems in sync as things change. If a user's attributes or group memberships change in Okta, those changes show up in Scalr, so access controls stay current.

Steps to getting started with Scalr and Okta

You can visit the detailed documentation on this here, but the following steps are a high level overview to get started:

1. Visit the Okta Catalog: Start the integration process by navigating to the Okta catalog and selecting Scalr as a featured application.
2. Configure SAML Integration: Follow the provided instructions to configure the SAML integration between Okta and Scalr. In a new window, log into Scalr to get the SAML IDP ID, and enter the necessary details into Okta.
3. Enable SCIM Integration (Optional): For automated user management, enable the SCIM protocol integration. It handles user provisioning and de-provisioning and keeps Okta and Scalr in sync in real time.
4. Explore Scalr's Terraform Automation Features: Once the integration is complete, your team can sign in and start using the Terraform automation and collaboration features Scalr offers.

Try it out in Scalr today. SAML SSO with Okta is available on all Scalr plans, including the free tier; SCIM-based user provisioning specifically requires the Enterprise plan. You can also read more here.