Integration detail

Overview

Terraform is a multi-faceted tool for building, changing, and versioning your infrastructure elements safely and efficiently.

Using declarative code configuration files to describe each component, Terraform learns about your infrastructure resources. Terraform can automatically run everything from a single application to your entire datacenter.

Terraform creates a plan that describes what resources are required to reach the desired state, and then uses APIs from various providers to execute the plan to build that infrastructure. As your configurations change, Terraform can determine what has changed and then create and apply incremental execution plans.

Okta can enhance your Terraform deployment in two ways. As an identity provider, you can leverage the SAML capabilities of Okta to provide Single Sign-On (SSO) and Just-in-Time (JIT) provisioning to Terraform Cloud. If you are hosting Terraform outside of Terraform Cloud, Okta Advanced Server Access can provide privileged access management for users.

Secondly, the Okta Provider for Terraform helps integrate Okta resources into existing continuous integration (CI) or continuous delivery (CD) pipelines, while seamlessly handling manual administration conflicts.

• Okta SSO to Terraform Cloud
• Terraform Okta Provider

Okta SSO to Terraform Cloud

If you use Terraform Cloud to manage Terraform deployments, then keeping that privileged hosting environment secure is of paramount importance. The Okta SSO integration currently supports the following SAML features:

• Service Provider (SP)-initiated SSO
• Identity Provider (IdP)-initiated SSO
• Just-in-Time provisioning

Requirements

Configuring SSO from Okta into Terraform Cloud requires:

• A Terraform Cloud account with the Business upgrade package
• An Okta org

Okta configuration

1. From the Okta Admin Console, click Applications > Applications.
2. Click Add Application.
3. Search for "Terraform Cloud".
4. On the app integration page, click Add.
5. Choose a new label for the app integration or keep the default name, "Terraform Cloud".
6. Click Done.
7. On the Assignments tab, assign the app integration to the people or groups who need to have access to Terraform Cloud.
8. Click the Sign On tab, and copy the URL of the "Identity Provider metadata" link.

Terraform Cloud configuration

1. Go to your Terraform Cloud workspace.
2. Click on Settings and click SSO.
3. Click Setup SSO.
4. Select "Okta" and click Next.
5. Paste your Okta metadata URL and click Save settings.
6. Test your SSO configuration. If the test was successful, click Enable.
7. Your Okta SSO configuration is complete and ready for users to sign in.

Team mapping configuration

You can configure Terraform Cloud to automatically add users to teams based on their SAML assertion from Okta. Okta then becomes the source of truth for your Terraform team memberships. Okta specifies a MemberOf SAML attribute, and the AttributeStatement in the SAML response contains a comma-separated list of team names as AttributeValue items.

To enable this automated process, edit your Terraform Cloud app integration in Okta:

1. On the Sign On tab, expand the Attributes section of the application configuration.
2. Add a new "Group Attribute Statements":

• Name: MemberOf
• Name format: Basic
• Filter: Matches regex
• Filter value: .*

After this group attribute statement is set, when a given user signs in to Terraform Cloud, all Okta groups to which they belong get passed as part of the SAML assertion. The user is added automatically to any teams within Terraform Cloud that have a matching group name. Note that the user is also removed from any teams that aren't included in their SAML assertion, overriding any manually set team memberships. Whenever a user signs in using SSO, their Terraform Cloud team membership is adjusted to match their SAML assertion.

Terraform Okta Provider

The Okta Provider is a plugin that allows Terraform to interact with Okta to manage the full resource lifecycle.

Requirements

Configuring SSO into Terraform Cloud from Okta requires:

• A local installation of the Terraform CLI. The instructions in this guide use Terraform Version 0.13 or later
• An Okta org

Configure the Okta Provider

1. Sign in to the Okta Admin Console for the Okta org that you want Terraform to manage, and click on the name in the top right-hand corner. The Okta org has a URL, for example, dev-1234.okta.com. The org name is the portion of the fully qualified domain name that is before the domain, for example, dev-1234.

2. Copy the org name to a text file.

3. Generate a new Okta API token. Select Security > API.

4. On the Tokens tab, click Create Token.

5. Give the token a name and click Create Token. Copy this token as this is the only time that you can view the token value. After this, the token is hidden as a hash value for your protection.

6. Click OK, got it to return to the Tokens tab.

7. Create a new local directory to hold the Terraform configuration files and initialize Terraform. Run the following commands in your local terminal window:

   mkdir okta-user-schema
   cd okta-user-schema
   

8. Create a file named okta.auto.tfvars and add the following lines:

   # Configure the Okta Provider
     org_name  = "org_name"
     base_url  = "okta.com"
     api_token = "some_api_token"
   

   The org_name value is the Okta org name you copied earlier from your Admin Console. Leave base_url as "okta.com" unless your Okta org contains .oktapreview.com, okta-emea.com, okta-gov.com, okta-miltest.com or okta-mil.com. The api_token value is the API token you created in Okta and copied down.

   This file holds the Okta configuration values that Terraform uses to interact with Okta.

The following example uses the Okta Provider for Terraform to customize the Okta Universal Directory schema by adding a field to store a user's date of birth.

1. Create a new configuration file named identity.tf. Add the following lines to the file:

   variable "org_name" {}
   variable "api_token" {}
   variable "base_url" {}
   
   terraform {
     required_providers {
       okta = {
         source  = "oktadeveloper/okta"
         version = "~> 3.6"
       }
     }
   }
   
   provider "okta" {
     org_name  = var.org_name
     base_url  = var.base_url
     api_token = var.api_token
   }
   

   The three variables are brought in from the okta.auto.tfvars file to customize the provider block.

2. Now, add the following resource block to identity.tf:

   resource "okta_user_schema" "dob_extension" {
     index  = "date_of_birth"
     title  = "Date of Birth"
     type   = "string"
     master = "PROFILE_MASTER"
   }
   

3. To test this script, run terraform init to initialize the Terraform state file which tracks the configurations Terraform has applied to the Okta resources. Then run terraform plan on the command line to print a list of the changes that Terraform will make to the Okta org.

4. Apply these changes to the Okta org by running terraform apply on the command line. Terraform modifies the user schema as defined above by interacting directly with the Okta platform. It also updates the state file on your local machine and keeps track of the resources it creates.

5. In your Okta Admin Console, verify the changes to the Okta user schema by clicking Directory > Profile Editor. A newly added date of birth attribute should be present, created by Terraform.

You can extend the user schema further by adding more resource blocks to the identity.tf file, or you can create new .tf files for other configuration needs within your Okta org.

You can find a full list of resources available to the provider in the Resources section of the Okta Provider documentation. Usage examples are available at the Okta Provider GitHub repository.

Version control

Terraform is more powerful when connected to a Version Control System (VCS) such as GitHub. A complete list of the VCS supported by Terraform is on Terraform.io. Using GitHub, for example, you can commit the configuration file:

git init
git add identity.tf
git commit -m "Initial commit. Adding the date of birth extension"

Don't push the okta.auto.tfvars file to your VCS, as it contains sensitive secrets such as the Okta API credentials. To avoid this issue, add *.tfvars to your .gitignore file.

Deploy on Terraform Cloud

The Terraform Okta Provider is also available for Terraform Cloud and uses identical Terraform configuration files.

1. Create a Terraform Cloud Account where you can deploy a copy of your local configuration. Make sure your local configuration is available through a VCS, so Terraform Cloud can use it.

2. Sign in to your Terraform Cloud account and create a new workspace. Workspaces describe a set of environments. For example, production, staging, or development.

3. Choose a workflow for your workspace.

4. Select the VCS used to store the Terraform configuration. Grant permission for Terraform Cloud to access this Terraform project.

5. Select the repository that holds your Terraform configuration files.

6. Give the new workspace a descriptive name defining the environment type. For example, my-sample-TFrepo-production.

7. When you deployed locally, you defined the variables in the okta.auto.tfvars file. Since your source control doesn't store that file, you must explicitly define these variables in Terraform Cloud. In your new workspace, click the Variables tab, and define the same three variables from the okta.auto.tfvars file.

   Mark the API token value as Sensitive when you define it so that the value isn’t exposed to anyone with access to the Terraform console. The workspace is now configured.

8. Select the Queue plan drop-down box in the top right-hand corner.

9. Enter a reason, and then click Queue plan.

10. Confirm the plan to apply it and leave a comment.

Related content

• Terraform - Okta SSO to Terraform Cloud
• Terraform - Okta Provider GitHub code repository
• Okta - Better together: Using the Okta integration with HashiCorp Terraform blog post
• Okta - Managing multiple Okta instances with Terraform Cloud blog post

Support

If you need help or have an issue, post a question in our Developer Forum.