Okta App and Group Sync

Okta has its own permissions system that doesn't directly map into Teleport. This includes permissions granted by Okta groups along with the assignment of users to individual applications within Okta. To model this within Teleport, an administrator would typically need to carefully craft a labeling system to attach to various Okta apps and groups and a set of roles to go along with them.

With the synchronization of Okta apps and groups as Teleport Access List feature in the Okta integration, this work is performed for you. This guide explains how to set up Okta app and the sync.

How it works

In Teleport, the Okta Access List synchronizer looks for any Okta group with members or any Okta application with individual assignments that matches filters that you can optionally supply during Okta integration enrollment. The synchronizer creates the following resources for each matched Okta group or application:

• A role for members that grants access to the group/application.
• A role for owners that grants the ability to review access to the group/application.
• An Access List representing membership to the group/application.
• Members for the Access List.

It should be noted that the Access List sync waits until the Okta groups and Okta applications has finished syncing as Teleport resources, so it may not start synchronizing immediately on startup.

Only Okta user groups with assignments will be imported as Teleport Access Lists. If an Okta User Group has no assignments, it will not be imported until it has assignments. If the last user is removed from the Access List, the Access List will be removed from Teleport on the next sync.

Prerequisites

• A running Teleport Enterprise cluster version 17.4.6 or above. If you want to get started with Teleport, sign up for a free trial.

• The tctl admin tool and tsh client tool.

  Visit Installation for instructions on downloading tctl and tsh.

• Teleport Identity enabled on your account.

• An Okta authentication connector.

  info

  Before following the guided app and group sync integration flow, you must have completed the following:

  • Guided Okta single sign-on flow.
  • Guided Okta user sync flow.

• (Optional) The Okta SCIM integration. You can follow the guided integration flow.

• To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials.

  For example, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email@example.com to your Teleport username:

  tsh login --proxy=teleport.example.com --user=email@example.com
  tctl status
  Cluster  teleport.example.com
  Version  17.4.6
  CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

  If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

• An Okta organization with admin access.

Enabling the Okta integration with bidirectional sync enabled will make Teleport take ownership over app and group assignments in Okta and can make changes within Okta based on your Teleport RBAC configuration. To limit the scope of the integration, ensure that:

• (Optional) You have organized your Okta applications and groups into Okta resource sets, which allow you to limit the scope your Okta access token.

Step 1/2. Set default list owner(s)

The first step of setting up Okta Access List synchronization is defining default Access List owners. You can select any number of default owners or manually enter the owners if they do not yet exist in the system. These owners can be later changed and will not be overwritten by the Okta Access List synchronization process.

1. Make sure you are on the Sync User Groups and App Assignments page. If you are not, visit the integration status page by navigating to Access -> Integrations and clicking anywhere on the Okta integration row. Then visit the Sync User Groups and App Assignments page.
2. Under Add Default List Owner(s), enter the names of Teleport users to the dropdown menu.

Step 2/2. Configure user group and application imports

After configuring default owners, you can customize which Okta user groups and applications should be imported. By default, all user groups and applications will be imported. This section shows you how to configure the Okta integration to import certain user groups and applications as Access Lists.

If you would like to import all user groups and applications, click Submit Configuration at the bottom of the menu.

To configure user group and application imports:

1. In the Teleport Web UI, make sure you are on the Sync User Groups and App Assignments page.

2. In Step 2, deselect the Sync All User Groups switch.

3. In the box labeled Filter by Group Name(s), enter names of Okta user groups to import.

   When specifying a user group, you can use globs (* characters) or regular expressions. Globs represent arbitrary values. Regular expressions must begin with ^ and end with $, and use the Google RE2 regular expression syntax.

   When filters are added, the list of user groups will update with the results of your filter applied. If no filters are provided, Teleport treats the value as the wildcard *, even if the Sync All User Groups switch is unchecked.

4. In Step 3, repeat these steps for applications. As with user groups, you can optionally deselect Sync All Applications and enter application names, including any globs and regular expressions.

Only Okta user groups and applications with assignments will be imported as an Access List. If an Okta user group or application has no assignments, it will not be imported until it has assignments. If the last user is removed from the Access List, the Access List will be removed from Teleport on the next sync.

note

You can also filter Okta apps and user groups using Okta resource sets, but this doesn't support globbing and regular expressions.

Handling nested Access Lists

Teleport supports nested Access Lists, where an Access List can include other Access Lists as members, creating a hierarchical structure. However, Okta does not support nested groups. This section describes the logic the Teleport Okta integration uses to support Access Lists.

Synchronization from Teleport to Okta

When synchronizing nested Access Lists from Teleport to Okta, the synchronizer flattens nested Access Lists.

Members in Access Lists, from all levels of nesting, are aggregated into a single, flat list of members when synchronized to Okta. This ensures that all users who should have access according to the Teleport hierarchy are included in the corresponding Okta group or application.

For example, consider the following Teleport Access List structure:

• Access List A:
  • Members: User1
  • Nested Members: Access List B
• Access List B:
  • Members: User2, User3

This structure will have the following representation in Okta:

• Group/Application for Access List A:
  • Members: User1, User2, User3

By flattening the Teleport hierarchy, all users receive the permissions associated with the root-level Access List in Okta.

Synchronization from Okta to Teleport

When synchronizing from Okta to Teleport, the synchronizer handles the flattened structure from Okta by attempting to map it back to the Teleport hierarchy. It compares the flattened list of members from Okta against the existing Access List hierarchy in Teleport.

If there are new users added in Okta that are not present in the Teleport Access List hierarchy, these users are added as members at the root-level Access List in Teleport. This approach maintains the hierarchical structure within Teleport while ensuring that access changes made in Okta are reflected appropriately.

For example, considering the following Okta group/application for Access List A in the previous section:

• Okta Group/Application for Access List A:
  • Members: User1, User2, User3, User4 (User4 is a new member added in Okta)

The synchronizer applies the following update:

• Access List A:
  • Members: User1, User4
  • Nested Members: Access List B
• Access List B:
  • Members: User2, User3

Deletion of Access Lists

Access Lists synchronized from Okta will automatically be deleted when there are no members assigned to them in Okta or when they are deleted in Okta.

warning

It is possible for an administrator to delete Access Lists, but this should only be done once the Okta integration has been removed and/or Access List synchronization is disabled. This could remove all users from the Okta group or application that's being targeted!

Working with synchronized Access Lists

When first synchronizing an Access List, the owners of the Access List will be set to the default owners configured during the initial Okta integration enrollment, and the initial review date will be set 6 months from the configured date. These fields are modifiable, as are the owner and membership requirements. However, you will not be able to change grants, as these belong to the Okta Access List synchronizer.

The owners of an Okta synchronized Access List will be preserved between runs.

warning

Removing members from an Okta synchronized Access List will remove the user from the Okta group or Okta application in Okta unless there are other assignments that convey the assignment to the user. In this way, Teleport becomes the source of truth for Okta membership. Keep this in mind when adding other automated workflows or integrations into your Okta environment.