Setting up the Okta Service as a Hosted Integration

Teleport can import and grant access to resources from an Okta organizations, such as user profiles, groups and applications. Teleport can provision user accounts based Okta users, Okta applications can be accessed through Teleport's application access UI, and access to these applications along with user groups can be managed by Teleport's RBAC along with access requests.

This guide will help you set up the Okta Service as a Teleport hosted integration.

Prerequisites

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

• The Enterprise tctl admin tool and tsh client tool version >= 15.2.4, which you can download from your Teleport account workspace or the Teleport Enterprise Cloud Downloads page.

• 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. tctl is supported on macOS and Linux machines. For example:

  tsh login --proxy=teleport.example.com --user=[email protected]
  tctl status
  Cluster  teleport.example.com
  Version  15.2.4
  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 an Okta API token created.

Enrolling a hosted Okta integration

Hosted integrations run inside a Teleport instance, rather than as an external process. This allows you to run integrations without having to provision and manage a separate Teleport node yourself - Teleport itself manages the setup, configuration and teardown of the integrations internally.

This is both convenient for administrators, and allows for a greater degree of automation than with self-hosted integrations.

In the case of Okta, running the integration in hosted mode allows it to support provisioning users (and other resources) via SCIM. SCIM is a protocol for provisioning resources across systems, and running a SCIM service allows Okta to provision user accounts in Teleport and push changes to user profiles in near real time, rather than waiting for the Okta integration to pull in the changes.

The Enrollment Process

Enrolling the Okta hosted integration will automatically perform the following actions:

1. Create an Okta SAML Application called Teleport $clustername in the upstream Okta organization
2. Assign the Okta Everyone group to the new SAML Application
3. Download the IdP Metadata for the new SAML Application
4. Create a new SAML Authentication Connector called okta-integration in the Teleport cluster
5. Configure the Okta integration to draw its user pool from the Okta users assigned to the new Teleport $clustername Okta SAML application
6. Start the hosted Okta integration, including the synchronization of Okta users, apps and groups into Teleport.

If Teleport Identity is enabled, the enrollment process will also guide you through the process of enabling SCIM provisioning for the Okta SAML application.

How to enroll

Visit the Teleport Web UI and click Access Management on the menu bar at the top of the screen.

On the left sidebar, click Enroll New Integration to visit the "Enroll New Integration" page:

Select the Okta tile, and then Teleport will then ask for

• your Okta organization URL, and
• the OKta API token described above.

Click Connect to continue.

Once the initial enrollment has completed, and if Teleport Identity is enabled, the enrollment workflow will guide you through enabling SCIM provisioning as well.

Configure Access List Synchronization

If Teleport Identity is enabled, the enrollment workflow will also guide you to configure syncing of user groups and direct application assignments as Access Lists. This will ensure that permissions in Okta are modeled properly in Teleport, allowing Teleport users to see the same Okta applications that they would when viewing the Okta dashboard.

Configuring Default Owners

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.

Importing Okta User Groups as Access Lists

After configuring default owners, you can customize which Okta user groups should be imported. By default, all user groups will be imported. If you would like more control, you can disable the "Import All User Groups" option at the top right of the panel and configure multiple filters which will be matched against the group names. For more information on filter syntax, refer to the Import Filters section below.

Importing Okta Application Assignments as Access Lists

In addition to importing Okta User Groups, you can also import direct application assignments within Okta as Access Lists as well. This behaves in exactly the same way as user groups.

Import Filters

Filters are supported as glob syntax and regex syntax. Glob syntax are strings with wildcards in them that represent arbitrary values where the wildcards go. For example, a glob that matches names with a prefix of "app" and a suffix of "salesforce" would look like app*salesforce.

You can also use raw regular expressions so long as the filter string is prefixed with ^ and ends with $. This will support the Google RE2 regular expression syntax.

When filters are added, the results of the user group or application list will update with the results of your filter applied. This allows you to see what will be imported at this particular time.

Configuring SCIM provisioning

If Teleport Identity is enabled, the enrollment workflow will now show you a guide to configuring SCIM. Enabling SCIM allowed Okta to push user (and other resource) updates to Teleport in near real time, without waiting for the Okta integration to run a synchronization.

As a concrete example, when using SCIM a user deactivation in Okta will be reflected in Teleport within seconds, rather than the tens of minutes it might take when waiting for an Okta synchronization pass.

For more information, see the Okta Synchronization and SCIM guide.

To recap the enrollment "Set Up SCIM" guide:

Enable SCIM Provisioning

1. In the Okta Admin Console, go to Applications and select the Teleport- created application, or use the link supplied by the Teleport "Set Up SCIM" guide.
2. Click Edit on the Okta App Settings page, check the box marked Enable SCIM provisioning, and click Save.

Configure Okta SCIM Client

1. Click on the new Provisioning tab and then click Edit.
2. Copy the SCIM connector base URL from the Teleport Set Up SCIM guide and paste it into SCIM connector base URL field in the Okta provisioning page.
3. Set the Okta Unique identifier field for users to userName.
4. Under Supported provisioning actions, check the following boxes:
   1. Import New Users and Profile Updates
   2. Push New Users
   3. Push Profile Updates
5. Set Authentication Mode to HTTP Header
6. Copy the authorization Bearer Token from the Teleport Set Up SCIM guide and paste it into Bearer Token field in the Okta provisioning page.
7. Click Save

Configure Okta-To-App Provisioning

1. Staying on the Provisioning tab, go to the new To App Okta application settings page and click Edit.
2. Check the following checkboxes:
   1. Create Users
   2. Update User Attributes
   3. Deactivate Users
3. Click Save

For more information about how the Okta integration manages Teleport resources, see the Okta Architecture and Synchronization with Okta and SCIM guides.

Deleting a hosted Okta integration

SAML Connector

The SAML connector created during the enrollment process is not deleted when the hosted Okta integration is deleted, and will automatically be re-used if the Okta integration is re-enrolled.

To permanently delete the SAML connector, navigate to the Auth Connectors page in the Teleport UI and delete it from there.

Access Lists

All Access Lists imported by the the hosted integration will remain until they are deleted by a Teleport Administrator. That is, they will not be deleted when the hosted integration is deleted.

The easiest way to clean these up is through the use of tctl. A batch command like this will remove all Okta sourced access lists in a system:

tctl get access_lists --format json | jq '.[] | select(.metadata.labels["teleport.dev/origin"] == "okta") | .metadata.name' -r | xargs -I{} tctl rm "access_list/{}"

Users

All Teleport user accounts created by the hosted integration, either via the synchronization process or via SCIM, will not be deleted when the hosted integration is deleted.

The easiest way to clean up these users when deleting a hosted integration is to un-assign all Okta users from the the Okta SAML Application Teleport uses as its identity provider, and wait for the sync process and/or SCIM provisioning to delete the corresponding Teleport accounts. Once the Teleport accounts have been automatically deleted you can proceed to delete the integration.

Teleport user accounts can also be manually deleted with tctl. For more information, see the Teleport Local Users guide.