- Home
- Single Sign-On
- Terraform Cloud
Overview
Terraform Cloud is an application that helps teams use Terraform together. Through Okta's Terraform Cloud integration, Business customers can enable SAML single-sign on for their users, which authenticates them for an organization, supports Just In Time (JIT) provisioning and helps to manage team memberships.
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
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
- From the Okta Admin Console, click Applications > Applications.
- Click Add Application.
- Search for "Terraform Cloud".
- On the app integration page, click Add.
- Choose a new label for the app integration or keep the default name, "Terraform Cloud".
- Click Done.
- On the Assignments tab, assign the app integration to the people or groups who need to have access to Terraform Cloud.
- Click the Sign On tab, and copy the URL of the "Identity Provider metadata" link.
Terraform Cloud configuration
- Go to your Terraform Cloud workspace.
- Click on Settings and click SSO.
- Click Setup SSO.
- Select "Okta" and click Next.
- Paste your Okta metadata URL and click Save settings.
- Test your SSO configuration. If the test was successful, click Enable.
- 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:
- On the Sign On tab, expand the Attributes section of the application configuration.
- 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
-
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
. -
Copy the org name to a text file.
-
Generate a new Okta API token. Select Security > API.
-
On the Tokens tab, click Create Token.
-
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.
-
Click OK, got it to return to the Tokens tab.
-
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
-
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. Leavebase_url
as "okta.com" unless your Okta org contains.oktapreview.com
,okta-emea.com
,okta-gov.com
,okta-miltest.com
orokta-mil.com
. Theapi_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.
-
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. -
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" }
-
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 runterraform plan
on the command line to print a list of the changes that Terraform will make to the Okta org. -
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. -
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.
-
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.
-
Sign in to your Terraform Cloud account and create a new workspace. Workspaces describe a set of environments. For example,
production
,staging
, ordevelopment
. -
Choose a workflow for your workspace.
-
Select the VCS used to store the Terraform configuration. Grant permission for Terraform Cloud to access this Terraform project.
-
Select the repository that holds your Terraform configuration files.
-
Give the new workspace a descriptive name defining the environment type. For example,
my-sample-TFrepo-production
. -
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 theokta.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. -
Select the Queue plan drop-down box in the top right-hand corner.
-
Enter a reason, and then click Queue plan.
-
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.
Functionality
Add this integration to enable authentication and provisioning capabilities.
Authentication (SSO)
- API
- Event Hooks
- Inbound Federation
- Outbound Federation
- RADIUS
- SAML Security Assertion Markup Language is an open standard for exchanging authentication and authorization data between an identity provider (IdP) and a service provider (SP) that does not require credentials to be passed to the service provider.
- Workflow Templates
- Workflows Connectors
- SWA Secure Web Authentication is a Single Sign On (SSO) system developed by Okta to provide SSO for apps that don't support proprietary federated sign-on methods, SAML or OIDC.
- OIDC OpenID Connect is an extension to the OAuth standard that provides for exchanging Authentication data between an identity provider (IdP) and a service provider (SP) and does not require credentials to be passed from the Identity Provider to the application.
- WS-Federation
Provisioning
- Create Creates or links a user in the application when assigning the app to a user in Okta.
- Update Okta updates a user's attributes in the app when the app is assigned. Future attribute changes made to the Okta user profile will automatically overwrite the corresponding attribute value in the app.
- Attribute Sourcing The application can be defined as the source of truth for a full user profile or as the source of truth for specific attributes on a user profile.
- Deactivate Deactivates a user's account in the app when it is unassigned in Okta or their Okta account is deactivated. Accounts can be reactivated if the app is reassigned to a user in Okta.
- Sync Password Push either the users Okta password or a randomly generated password to the app. This feature is not required for all federated applications as user authentication takes place in Okta, however some apps still require a password.
- Group Push Push existing Okta groups and their memberships to the application. Groups can then be managed in Okta and changes are reflected in the application.
- Group Linking Link Okta groups to existing groups in the application. Simplifies onboarding an app for Okta provisioning where the app already has groups configured.
- Schema Discovery Import the user attribute schema from the application and reflect it in the Okta app user profile. Allows Okta to use custom attributes you have configured in the application that were not included in the basic app schema.
- Attribute Writeback When the application is used as a profile master it is possible to define specific attributes to be sourced from another location and written back to the app. For example the user profile may come from Active Directory with phone number sourced from another app and written back to Active Directory.