Enable Terraform access for your Okta org

Create an Okta app and credentials that Terraform uses to manage the objects in your org.

Learning outcomes

Authorize Terraform to automate your Okta org.
Create the authorization credentials used by Terraform.
Test that Terraform can access your org.

What you need

Familiarity with Terraform terms: configuration, resources, state, and commands. See Terraform overview.
Okta Developer Edition organization (opens new window)
Super admin permissions (opens new window)
OpenSSL command line program (opens new window). Some operating systems already include openssl or openssl-rsa.
A Terraform installation (opens new window)

Overview

Terraform is a tool that allows admins to automate your Okta org. Terraform requires an appropriate level of access to make changes to your org. You provide that access with an Okta service app, which is the app type required for machine-to-machine communication.

An Okta service app uses the OAuth 2.0 Client Credentials authorization flow (opens new window) to authorize Terraform. You create a public/private key pair as the client credentials for this flow. Okta stores the public key, and Terraform uses the private key in the configuration for access to your org.

In the service app, you specify the Okta objects that Terraform can access using scopes. Every action Terraform makes on an Okta object requires a specific scope. For example, the Terraform configuration in this guide creates a test group in Okta that requires the okta.groups.manage scope.

Note: See Control Terraform access to Okta.

Create an app for Terraform access

Create an Okta service app that authorizes Terraform to make changes to your org:

In the Admin Console, select Applications > Applications.
Click Create App Integration, and then select API Services.
Click Next.
Enter a name for the app, and then click Save.

Grant scopes to the app

Specify the Okta objects that Terraform can access by adding the appropriate scopes to your service app. The Terraform resources that you use in your configuration determine the required scopes.

Note: Only the Super Admin role has permissions to grant scopes to a service app.

Open the service app that you created in the previous section and select Okta API Scopes.
Find the okta.groups.manage scope, and click Grant.
Click Grant Access.

Note: The example Terraform configuration used in this guide requires only the okta.groups.manage scope. If required, you can also grant additional scopes.

Create access credentials

The credentials used are a public/private key pair. Store the public key in the service app, and use the private key later when you create a Terraform configuration.

Note: If you use an external tool to generate a key pair, audit the code beforehand to maintain org security.

This guide uses Okta to generate the public/private key pair:

In the Admin Console, open the service app and select General.
In the Client Credentials section, click Edit to change the client authentication method.
Select Public key / Private key as the Client authentication method.
Click Add key.
In the Add a public key dialog, click Generate new key.
In the Private key section, click PEM.
Copy the PEM private key and save it as a .key file.

Note: The private key only appears in this dialog once. Losing the private key requires generating a new pair of keys.
Click Done, Save, and then Save again.

Note: Set the status of any public key currently used by Terraform to Active, and set the status of the other public keys to Inactive.

Check that the generated private key is in PKCS#1 format, which is the format required by the Okta Terraform Provider. In that format, the file that contains the private key begins with -----BEGIN RSA PRIVATE KEY-----.

If the key isn't in the right format, convert it to the correct format using the OpenSSL command line program:

In a terminal, go to the file path where you saved the original private key.
Run OpenSSL to convert the key. One of the following command lines should work depending on your operating system and version of OpenSSL: openssl rsa -in {ORIGINAL_PRIVATE_KEY} -out {CONVERTED_PRIVATE_KEY} -traditional openssl rsa -in {ORIGINAL_PRIVATE_KEY} -out {CONVERTED_PRIVATE_KEY} openssl-rsa -in {ORIGINAL_PRIVATE_KEY} -out {CONVERTED_PRIVATE_KEY}
- ORIGINAL_PRIVATE_KEY: The file that contains the key generated earlier.
- CONVERTED_PRIVATE_KEY: The file that contains the converted key.

Note: The file that contains the converted private key must begin with -----BEGIN RSA PRIVATE KEY-----. If not, try step two again.

Assign admin roles

Limit the access of the service app to your org by assigning it one or more admin roles. This increases the security of your org by defining which resources are accessible.

In the Admin Console, open the service app and select Admin roles.
Click Edit assignments.
In the Complete the assignment section, for Role select Group Administrator.
Click Save Changes.

Note: The example Terraform configuration in this guide requires only the Group Administrator role. Create an appropriate custom role your own service app.

For more information on admin roles, see Assign admin roles to the OAuth 2.0 service app.

Add credentials to Terraform

Create a Terraform configuration that uses the credentials that you created earlier:

In an empty directory on your computer, create a Terraform configuration file called main.tf.

In the main.tf file, list Okta as a required Provider:

terraform {
  required_providers {
    okta = {
      source = "okta/okta"
    }
  }
}

Add the Okta provider to the main.tf file:
```
provider "okta" {
  org_name = "${yourOktaOrg}"
  base_url = "okta.com"
  client_id   = "${yourClientID}"
  scopes = ["okta.groups.manage"]
  private_key = ${privateKey}
}
```
In the previous code sample, add your values to the following fields:
- org_name: Your Okta org name. For example, exampleOrgName from the full domain https://exampleOrgName.okta.com.
- base_url: Your Okta org domain
- client_id: The client ID of the service app that you created in an earlier step.
- private_key: Either the path to the private key file or the private key itself. Okta recommends storing the key in a separate location and using a secrets and encryption management system, such as HashiCorp Vault.
- scopes: A list of scopes required by the Terraform configuration. This example uses the okta.groups.manage scope.

For more information on declaring the Okta Provider in your Terraform configuration, see the Okta Provider documentation (opens new window).

Test Terraform access

Check whether Terraform can manage Okta objects by running a configuration. This example creates a group in your org:

Add the okta_group resource in the main.tf file:

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

In a terminal, go to the directory that contains main.tf.
Run terraform init to initialize the Terraform configuration.
Run terraform plan to preview the changes to your Okta org.
Run terraform apply to apply the changes to your org. Enter "yes" when prompted to confirm.
In your Okta org, check Directory > Groups to view the group created by Terraform. If the group exists, you successfully authorized Terraform to access your org.

The terraform.tfstate file in the Terraform configuration directory stores the group information. Terraform uses this information when you modify and apply your configurations:

"resources": [
  {
    "mode": "managed",
    "type": "okta_group",
    "name": "example_group",
    "provider": "provider[\"registry.terraform.io/okta/okta\"]",
    "instances": [
      {
        "schema_version": 0,
        "attributes": {
          "custom_profile_attributes": "{}",
          "description": "",
          "id": "{groupID}",
          "name": "Example Group",
          "skip_users": false,
          "users": null
        },
        "sensitive_attributes": [],
        "private": "bnVsbA=="
      }
    ]
  }
]

After testing Terraform access, clean up your org by deleting the test group that you created:

In a terminal, go to the directory that contains main.tf.
Run terraform destroy to delete the group and the other resources in your configuration. Enter yes when prompted to confirm.
Delete the example_group resource from your main.tf configuration file.

Edit This Page On GitHub

On this page