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 with the common use cases of using the Okta provider, ensure that you have the following prerequisites in place:

1. Terraform Installed: Make sure you have Terraform or OpenTofu installed on your machine. You can download the latest versions from 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. This token will serve as the authentication mechanism for your Terraform scripts.
4. Scalr Account: If you want to use Scalr as the remote backend, sign up for a free account here. Feel free to use this 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. This can all be viewed in detail 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. Upon a successful Terraform run, the state file will be created.

Best Practices and Advanced Usage

Variables and Dynamic Configurations

Utilize Terraform variables to make your configurations more dynamic. Instead of hardcoding values, use variables to create reusable and flexible scripts.

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

To improve your Terraform code, we encourage you to review the option of using Okta data sources in the code to be able to pull information from other resources or workspaces into the run.

Provider Summary

So far we've configured the Okta provider, created users, groups, and applications, and touched on a few practices for larger setups. The provider supports plenty more than that: 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. That means your team signs into Scalr with the same Okta credentials they already use everywhere else. The rest of this section walks through the integration and what it buys you.

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

Automated User Provisioning: SCIM enables the automatic provisioning of user accounts in Scalr when created in Okta. This automation streamlines user onboarding processes, reducing the need for manual intervention.

Efficient User Deprovisioning: When a user is de-provisioned in Okta, SCIM ensures that the corresponding user account is promptly deactivated in Scalr. This automated process enhances security by revoking access for users who no longer require it.

Real-Time Updates: SCIM facilitates real-time updates, ensuring that changes in user attributes or group memberships in Okta are promptly reflected in Scalr. This synchronization guarantees that access controls are consistently enforced.

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. This initiates the integration and sets the stage for a more streamlined Terraform experience.
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 ensure that the necessary details are entered correctly into Okta, allowing for a secure SSO experience.
3. Enable SCIM Integration (Optional): For advanced user management, consider enabling the SCIM protocol integration. This optional step enhances user provisioning and de-provisioning, ensuring real-time synchronization between Okta and Scalr.
4. Explore Scalr's Terraform Automation Features: Once the integration is complete, explore the full range of Terraform automation and collaboration features offered by Scalr. Use them to streamline infrastructure management and enhance collaboration across your organization.

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.