Getting Started

This integration allows you to manage user memberships with Okta Directory. You can setup access management through Opal to Okta Directory in minutes.

Setup

Create an Okta Directory connection

To get started, head to the Connections page and click on the Okta Directory tile.

Click on the Okta Directory tile to get started

Click on the Okta Directory tile to get started

Opal requires multiple credentials in order to manage your Okta Directory Groups.

Step 1 - Configure a super administrator account and API token for Opal

In order for Opal to manage your Okta Directory on your behalf, we'll need you to create a super administrator account. We suggest using a separate account for this, to ensure the account's permission levels do not change. You can do this by adding the new person to your Okta Directory. Then, perform the following steps:

  • Navigate to Security -> Administrators.

  • Grant the new account super administrator privileges via the Add Administrator button in the top left.

Next, we will generate an API token for the new account.

  • Log in as the new account (with super administrator privileges).

  • Navigate to Security -> API.

  • Click on the Tokens tab.

  • Click Create Token on the top left.

  • Record the generated token.

Step 2 - Create Opal group rule in Okta

Create a group rule in Okta that marks which Okta groups you want to sync with Opal:

  • Navigate to Directory -> Groups.

  • Click on the Rules tab and click Add Rule.

  • Name the rule opal. In the IF condition, enter opal as the login user attribute argument.

  • Add Okta groups you want to tag and automatically import into Opal via the Assign to field of the group rule. Note that you cannot add groups with administrator roles (see this feature: https://support.okta.com/help/s/article/Can-Okta-Administrator-roles-be-added-to-a-Group?language=en_US). If you attempt to do so, you will get an error saying Group membership rules cannot be created for groups with administrator roles.

  • Click Save.

Step 3 - Fill out Opal Connections form

  • Back in the Connections form, fill in details about your Okta organization.

  • For Organization Name, enter the domain name of your Okta organization (e.g. mydomain for mydomain.okta.com).

  • For Super Administrator API token, you should enter the API token of the account created above.

If this step is successful, you have completed setting up the Active Directory server connection.

Step 4 - Manually import Okta groups

  • Click on Groups in the left sidebar.

  • In the top right, click on the + (Plus) button, then Import groups.

  • Select your Okta connection

  • Then select which groups you'd like to import

As mentioned above, if you'd like to automatically import groups into Opal, you can simply add them to the Okta rule created above. This is especially useful if you're using Terraform to configure your Okta directory.


Best Practice: Use Terraform to Manage Okta groups

To manage Okta groups using Terraform, please add the Okta group rule in Terraform. The rule will be automatically updated in Okta as you modify group_assignments.

Example Group Rule in Terraform:

resource "okta_group" "group_example" {
name = "group01"
description = "My Example Group"
}

resource "okta_group_rule" "rule_example" {
name = "opal"
status = "ACTIVE"
group_assignments = [okta_group.group_example.id]
expression_type = "urn:okta:expression:1.0"
expression_value = "user.login==\"opal\""
}

Map Okta Groups to Opal On-Call Managed Groups (PagerDuty Schedules)

Here are some instructions for mapping Okta groups to Opal on-call managed groups (linked with on-call schedules). The following Terraform code will create Opal on-call managed groups, corresponding to the specified schedules. Currently, only PagerDuty schedules are supported.

  1. Add PagerDuty and Okta providers to your Terraform code.

  2. Define PagerDuty schedules you want to link. For example, the below code defines two PagerDuty schedules.

    data "pagerduty_schedule" "customer_support" {
    name = "Customer Support On-Call"
    }

    data "pagerduty_schedule" "test_schedule" {
    name = "Test Schedule"
    }
  3. Here is an example of how to link Okta groups to PagerDuty schedules.

resource "okta_group" "pd_group1" {
name = "pd_group1"
}

resource "okta_group" "pd_group2" {
name = "pd_group2"
}

resource "okta_group_rule" "pd_rule1" {
name = "opal_pagerduty1"
status = "ACTIVE"
group_assignments = [okta_group.pd_group1.id]
expression_type = "urn:okta:expression:1.0"
expression_value = format("user.login==\"%s:%s\"",
data.pagerduty_schedule.customer_support.name, data.pagerduty_schedule.customer_support.id
)
}

resource "okta_group_rule" "pd_rule2" {
name = "opal_pagerduty2"
status = "ACTIVE"
group_assignments = [okta_group.pd_group2.id]
expression_type = "urn:okta:expression:1.0"
expression_value = format("user.login==\"%s:%s,%s:%s\"",
data.pagerduty_schedule.test_schedule.name, data.pagerduty_schedule.test_schedule.id,
data.pagerduty_schedule.customer_support.name, data.pagerduty_schedule.customer_support.id
)
}

Each Okta group rule specifies a mapping from Okta Groups to PagerDuty schedules. In the above, there are two group rules. In total, these rules create two Opal on-call groups (since one Okta group is specified for each rule). The opal_pagerduty1 rule creates an Opal on-call group linked to the Customer Support On-call Schedule. The opal_pagerduty2 rule creates an Opal on-call group linked to two schedules: the Customer Support On-call Schedule and Test Schedule.

More precisely, the Okta group rule must be named with a prefix of opal_pagerduty, in order to be detected by Opal. Then in the group_assignments section, add the group IDs for the Okta groups you want to map to PagerDuty schedules (there could be multiple schedules). Finally, the PagerDuty schedules are defined by the expression_value attribute; specifically,

format("user.login==\"%s:%s\"",
data.pagerduty_schedule.customer_support.name, data.pagerduty_schedule.customer_support.id
)

defines a single PagerDuty schedule for the Customer Support On-Call schedule, whereas a comma-delimited list, such as

format("user.login==\"%s:%s,%s:%s\"",
data.pagerduty_schedule.test_schedule.name, data.pagerduty_schedule.test_schedule.id,
data.pagerduty_schedule.customer_support.name, data.pagerduty_schedule.customer_support.id
)

denotes two schedules---both Customer Support On-Call and Test Schedules. You could add more commas to the expression to specify a larger number of schedules.

For an Okta group rule, you should only change the name, group_assignments, and expression_value attributes---preserve all other properties as in the example above.


❗️Enable Opal for access management

If you want to use Opal to manage access to Okta groups, you will need to enable the Manage resources and groups from Opal in the Admin page. You can read more about how to do that here.


Did this answer your question?