Better together: Using the Okta integration with HashiCorp Terraform

UPDATE: It's official, Okta's Terraform provider has been certified by HashiCorp! To get started, check out the official docs here. Want to contribute or open an issue? Find the project here.

Organisations using Okta as their Identity layer can easily integrate Okta into their continuous integration (CI), continuous delivery (CD), and development pipelines. HashiCorp Terraform is a powerful and extensible tool for defining and creating cloud infrastructure in a repeatable way through code. Terraform is used to create, manage, and update a wide variety of infrastructure resources, including Okta.

Okta gives administrators the flexibility to configure settings through either a friendly Admin UI or an API. However, this means a change made via the API can overwrite a setting made in the Admin UI, and vice versa. This can create conflict between teams who want to take an “Infrastructure as Code” approach—where every setting is managed by code—and the Administrative, Security, and IT teams who want the autonomy to quickly check and modify settings through the Admin UI—without the need to write code.

Rather than choosing one approach over the other, the Terraform integration with Okta supports either option. Any changes made via Terraform are immediately visible in the Okta Admin Dashboard and conversely, if the Okta Admin Dashboard is intentionally (or accidentally) used to change a setting that is managed by Terraform, that change will be caught and flagged by Terraform the next time it’s run, providing an extra layer of protection against unanticipated configuration changes within Okta.

In this post, we’ll explore some of the benefits of using the Okta and Terraform integration, some common use cases where organisations can benefit from “Terraforming” Okta, and how you can configure your Okta org(s) through code using Terraform—greatly enhancing your CI/CD pipelines.

CI, CD, and development pipelines

Continuous Integration (CI) is the practice of team members merging their code changes into a mainline branch multiple times per day. Any failed integration tends to be fixed immediately.

Benefits

• Adapt to changes being made to the codebase in a manageable and incremental manner
• Continuously validate your code against your test suites

Continuous Delivery (CD) is the process of building software in such a way that it can be released to production at any time.

Benefits

• Deploy any version of the software to any environment on demand
• Reduce deployment risk

Development pipeline

With development pipelines, the build is broken into stages, which helps development teams stay organised. Each stage serves as a test to validate the production readiness of the overall system. There are a number of different tests that aim to detect problems across performance, security, and usability. Ideally, earlier stages will detect most problems with faster feedback loops, while later stages will perform deeper, more narrow tests. As the tests are passed, the code will be promoted through the various stages and ultimately, into production.

Continuous integration (CI), continuous delivery (CD), and development pipelines enable organisations to improve the velocity, productivity, and sustainability of their development teams. Teams working together to create large and complex systems can continuously test their individual integrations and detect problems early in the development lifecycle. This ultimately helps avoid what is commonly referred to as “integration hell”, which often happens when waiting until the end of a project or sprint to merge all the work of a team’s developers. Every change goes through the pipeline and automatically gets tested and validated against production-like environments. With the Okta and Terraform integration, teams are able to move quickly and deploy to production as frequently as needed—resulting in an increase in production deployments, per day.

Okta + Terraform Use Cases

Use Case: Using Terraform instead of the Okta Admin UI

You can configure, manage, and update your Okta infrastructure easily with Terraform. Instead of using the Okta Admin UI, you define your Okta infrastructure in Terraform configuration files using the HashiCorp Configuration Language (HCL). HCL is a declarative language that operators use to define the desired resources. Terraform then makes the necessary API calls to Okta to build the requested state, enabling you to automate the provisioning and deployment processes of your Okta org. Some of the key benefits to using Terraform and Okta together include the following:

• It makes your Okta infrastructure more predictable, easier to maintain, and deterministic
• Less time is spent managing Okta when on-boarding new applications
• It lowers your Bus Factor risk: Okta infrastructure is now defined and accessible in source files rather than a sysadmin’s head.

Below is a sample Terraform configuration to programmatically perform common tasks that have historically been done manually inside the Okta Admin UI.

And here is how to add a custom attribute to the Okta profile master, and then add a user with that custom attribute via Terraform:

In addition to managing users, you can also use Terraform to manage the following and much more:

• SAML apps
• OIDC apps
• Bookmark apps
• Groups and group rules
• Trusted sources and origins
• User profile attribute schemas
• Authorisation servers
• Inline Hooks
• OIDC, social, and SAML IdPs
• Sign-on policies
• MFA policies

Use Case: Eliminate configuration drift in your Okta org(s)

Okta policies may be edited by several teams and administrators over time, making it difficult to keep track of all the various configuration changes. With Terraform, there is the concept of a state, meaning any changes to your Okta infrastructure (whether intentional or by accident) are immediately detected rather than living on silently without your knowledge. This allows for

• Reduced need to pour through logs to find if any configurations were changed by administrators
• Improved security should anything become compromised and/or configurations are changed without your knowledge

One other key consideration when using Terraform is that the state file acts as the source of truth for your most recent infrastructure configuration. Operators should ensure that they have access to the necessary state files when making updates or changes. One way to manage this process is to utilise the new Remote State Storage feature from Terraform Cloud. This provides secure storage and access to your organisation’s state files, reducing the risk of misconfigurations or errors.

Below is an example of how Terraform can help catch configuration drift. We start with the output of a tf apply command (this has been edited for clarity.)

Let’s first configure an OIDC app named Example OIDC App.

At this point, among other things, we have configured an OIDC app named Example OIDC App. Now assume that another Okta Admin comes along and decides to change the name of that app via the Okta Admin UI. Traditionally, that sort of change would be hard to catch, but thanks to Terraform, that change is caught the next time the tf plan command is run:

In the output above, you can see that Terraform noticed the app name changed from Example OIDC App to New App Name and is noting that this would be changed back when the tf apply command runs again.

Terraform is an excellent tool for managing your Okta infrastructure. It enables you to define and configure your Okta infrastructure programmatically, so that it is automated, predictable, and repeatable.

Interested in exploring the Provider? To get started, check out the official docs here. Want to contribute or open an issue? Find the project here.