Installing the SCIM-Only Okta Integration

The SCIM (System for Cross-domain Identity Management) integration enables automated user management, ensuring that user accounts in Teleport are synchronized with the corresponding Okta user profiles. This integration streamlines the onboarding and offboarding process by automatically creating, updating, and deleting Teleport user accounts in response to changes within the Okta organization. SCIM Teleport integration allows immediate locking of users in Teleport when they are deprovisioned in Okta, stopping all ongoing user Teleport sessions to maintain security and compliance.

How it works

User provisioning (and de-provisioning) with SCIM requires two Teleport components working together:

• A SAML Connector that provides SSO login to Teleport for upstream Okta users
• A Teleport SCIM plugin integration that provisions and de-provisions Teleport user accounts in response to changes in the upstream Okta organization

Both of these Teleport components rely on an Okta SAML application to act as the interface between Teleport and Okta. For consistency, both of the Teleport components must use the same Okta application.

When a user is assigned to the Okta app, either directly or via group membership, a corresponding Teleport user account will be created. If the Okta user already has a valid temporary Teleport SAML user account (i.e. they have logged into the cluster via SAML SSO before SCIM provisioning was enabled), the temporary account will automatically be adopted by the SAML integration and promoted to a long-lived SCIM-managed account.

When a user is unassigned from the Okta app, or is deactivated by the Okta admin, Teleport will immediately delete the user in question, and create a lock that will both immediately terminate any existing sessions and prevent that user from re-using any credentials that have already been issued. This lock will be automatically revoked if the user is subsequently re-provisioned via SCIM, otherwise the lock is permanent and will have to be explicitly deleted to remove.

Prerequisites

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

• The tctl admin tool and tsh client tool version >= 16.0.4.

  Visit Installation for instructions on downloading tctl and tsh.

• Authentication With Okta as an SSO Provider

Step 1/2. Installing the Teleport SCIM integration

Teleport supports two SCIM integration modes:

• Without API token - User traits to role mapping will be propagated when the user logs in to Teleport. As a side effect, user roles will be visible and updated when users log in to Teleport.
• With API token - User traits to role mapping will be propagated immediately during SCIM user provisioning.

Run the following tctl command to install the SCIM integration.

$ tctl plugins install okta  \
  --org https://trial-12356.okta.com \
  --saml-connector "${SAML_CONNECTOR_NAME}" \
  --no-users-sync \
  --no-accesslist-sync \
  --no-appgroup-sync \
  --scim
Successfully created Okta plugin "okta"

SCIM Base URL: https://teleport.example.com:443/v1/webapi/scim/okta
SCIM Identifier field for users: userName
SCIM Bearer Token: 1234567891234567891234567890

$ tctl plugins install okta  \
  --org https://trial-12356.okta.com \
  --saml-connector "${SAML_CONNECTOR_NAME}" \
  --no-users-sync \
  --no-accesslist-sync \
  --no-appgroup-sync \
  --scim
  --api-token="${OKTA_API_TOKEN}"
Successfully created Okta plugin "okta"

SCIM Base URL: https://teleport.example.com:443/v1/webapi/scim/okta
SCIM Identifier field for users: userName
SCIM Bearer Token: 1234567891234567891234567890

Step 2/2. Configuring the Okta app

To leverage the Teleport SCIM integration, you need to enable SCIM provisioning in your Okta app, which will propagate user management changes to Teleport. For detailed instructions on configuring SCIM provisioning in the Okta app, see the Okta Integration Configuring SCIM provisioning guide.

If your Okta app has assigned users before SCIM provisioning is enabled, you will need to trigger their provisioning explicitly. This can be done by selecting the Provision Users button on the Okta app Assignments page.

Hiding profile data from Teleport

If you have data in your Okta user profile that you don’t wish to share with your Teleport cluster, you can edit the Okta application User profile to present Teleport with a subset and/or mapped version of the full User profile.

Deleting the SCIM integration

You can delete the SCIM integration via the Integrations page in the Teleport UI, or with tctl like so:

$ tctl plugins delete okta

You can semi-manually delete all SCIM-provisioned users using a combination of tctl and jq.

For example:

tctl get users --format=json \
 |  jq '.[] | select(.metadata.labels["teleport.dev/origin"] == "okta") | .metadata.name' -r \
 | xargs -L 1 tctl users rm