# Okta SCIM 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. The Teleport SCIM integration allows admins to immediately lock 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. --- NOTE Currently none of the SCIM user profile traits are stored in the Teleport user, although this may change in the future. --- 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. --- WARNING Okta does not send SCIM updates to Teleport when a user is suspended. Even though Okta will prevent a suspended user from logging back into the cluster, any existing sessions will not be terminated, and any pre-issued credentials will be valid for their normal lifetimes. --- ## Prerequisites - A running Teleport Enterprise cluster. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/get-started/deploy-community.md). - The `tctl` and `tsh` clients. Installing `tctl` and `tsh` clients 1. Determine the version of your Teleport cluster. The `tctl` and `tsh` clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at `/v1/webapi/find` and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service: ``` $ TELEPORT_DOMAIN=teleport.example.com:443 $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')" ``` 2. Follow the instructions for your platform to install `tctl` and `tsh` clients: **Mac** Download the signed macOS .pkg installer for Teleport, which includes the `tctl` and `tsh` clients: ``` $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg ``` In Finder double-click the `pkg` file to begin installation. --- DANGER Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security. --- **Windows - Powershell** ``` $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip Unzip the archive and move the `tctl` and `tsh` clients to your %PATH% NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP. Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\) instead. ``` **Linux** All of the Teleport binaries in Linux installations include the `tctl` and `tsh` clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/installation.md). ``` $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ cd teleport $ sudo ./install Teleport binaries have been copied to /usr/local/bin ``` * Teleport Identity Governance enabled on your account. * An Okta authentication connector. --- IMPORTANT Before following the guided SCIM integration flow, you must have completed the [guided Okta single sign-on flow](https://goteleport.com/docs/identity-governance/integrations/okta/guided-sso.md). --- * 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 18.7.3 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. --- NOTE You can skip the guided SCIM integration flow if you want to set up the [guided user sync integration](https://goteleport.com/docs/identity-governance/integrations/okta/user-sync.md) without SCIM. You can enable SCIM later in the [integration status page](https://goteleport.com/docs/identity-governance/integrations/okta.md#managing-integration-components). --- ## Step 1/3. Enable SCIM in Okta 1. In the **Configure SCIM in Okta’s Admin Console** view of the Teleport Web UI, follow the instructions in **Step 1**. In Okta, you should see that SCIM has been enabled for your application: ![Enable SCIM](/docs/assets/images/scim-enable-32e44f6b2cc285bb322226c1d42738cf.png) 2. In Okta, viewing the SAML application configuration menu, click **Save**. ## Step 2/3. Configure SCIM details in Okta 1. In Okta, viewing the SAML application configuration menu, navigate to the **Provisioning** tab. 2. Navigate to the Teleport Web UI. In the **Configure SCIM in Okta’s Admin Console** view, copy the values provided in **Step 2** to the **SCIM Connection** menu in Okta: ![Okta Enrollment: SCIM - configure](/docs/assets/images/scim-configure-b4e2064bd72a54fdb49733d24f55eb7c.png) 3. Navigate to the Teleport Web UI. In the **Configure SCIM in Okta’s Admin Console** view, click **Save SCIM Configuration**. 4. In Okta, click **Test Connector Configuration** to confirm all of the details are set up correctly, and then click **Save**. ## Step 3/3. Configure SCIM provisioning permissions in Okta 1. In Okta, viewing the SAML application configuration menu, ensure that you are viewing the **Provisioning** tab. On the left sidebar, navigate to **To App**. 2. Ensure that the following items have **Enable** checked: - **Create Users** - **Update User Attributes** - **Deactivate Users** You should see the following settings selected in Okta: ![Configure SCIM Provisioning](/docs/assets/images/scim-provisioning-67c0318edd2cfde3905d621d3d3e2ab4.png) 3. Return to the Teleport Web UI. You should see the **Configure SCIM in Okta’s Admin Console** view. Click **Continue** to finish setting up the SCIM integration. ## Retrospective user provisioning If your Okta app has assigned users in Teleport 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. ![Provision Existing Users](/docs/assets/images/scim-provision-existing-users-28a0dc11b595ae895346b180e7e03cb5.png) If your Okta instance is missing the **Provision Users** button, you can force user provisioning by removing and re-adding users to the app. ## 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. ## Next steps After completing the guided enrollment flow for the Okta SCIM integration, you can proceed to the [Okta user sync integration](https://goteleport.com/docs/identity-governance/integrations/okta/user-sync.md).