![Fork me on GitHub](/docs/_next/image/?url=%2Fdocs%2F_next%2Fstatic%2Fmedia%2Fforkme.b9234619.webp&w=256&q=75)
Teleport
Setting up the Okta Service as a Hosted Integration
- Version 17.x
- Version 16.x
- Version 15.x
- Version 14.x
- Older Versions
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.
Enabling the Okta integration will make Teleport take ownership over app and group assignments in Okta and can make changes within Okta based on Teleport RBAC configuration.
Specifically, access to Okta apps is governed by Teleport roles' app_labels so before enabling the integration make sure that your users do not have roles with wildcard app labels, which otherwise will result into those users being assigned to all Okta applications.
To limit the scope of the integration, you can constrain Okta access token to a subset of apps and groups by using an Okta resource set.
Teleport manages Okta application group assignments using a declarative state approach. If an assignment is created via Teleport and subsequently removed via the Okta UI, Teleport will re-evaluate and potentially overwrite Okta UI changes to align with the state defined by Teleport's RBAC configuration.
Prerequisites
-
A running Teleport cluster. If you want to get started with Teleport, sign up for a free trial.
-
The
tctl
admin tool andtsh
client tool version >= 16.2.1.Visit Installation for instructions on downloading
tctl
andtsh
.
- To check that you can connect to your Teleport cluster, sign in with
tsh login
, then verify that you can runtctl
commands using your current credentials. For example:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 16.2.1
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
commands on the computer that hosts the Teleport Auth Service for full permissions. - An Okta organization with an Okta API token created.
Okta API tokens inherit the permissions of the user who created them. These can be controlled by using custom admin roles and assigning them to a user who will then create the API token. We recommend creating a user dedicated to the Teleport Okta API service to manage this token.
The permissions required are:
User permissions
- View users and their details
- Edit users' group membership
- Edit users' application assignments
Group permissions
- View groups and their details
- Manage group membership
Application permissions
- Add and configure applications (only required for installation)
- View applications and their details
- Edit application's user assignments
Additionally, the resource set associated with the target user must have unconstrained access to Users, Applications, and Groups.
One caveat here is that it's impossible to assign API token creation permissions to a custom role. However, the Okta built in role "Group Membership Admin" has permissions to create an API token. See more information about built in roles here.
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:
- Create an Okta SAML Application called
Teleport $clustername
in the upstream Okta organization - Assign the Okta
Everyone
group to the new SAML Application - Download the IdP Metadata for the new SAML Application
- Create a new SAML Authentication Connector called
okta-integration
in the Teleport cluster - Configure the Okta integration to draw its user pool from the Okta users
assigned to the new
Teleport $clustername
Okta SAML application - 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.
If a SAML connector called okta-integration
already exists, the enrollment
process will attempt to adopt this connector and use the Okta SAML Application
it points to, rather than create a new one.
This adoption process will fail if the SAML connector was created with Teleport versions prior to 15.0.0, or was created manually. In this case, the best course of action is to either delete or rename the existing SAML Connector and let the integration enrollment create a new one.
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.
Only Okta User Groups with assignments will be imported as an Access List. 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.
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.
Only Okta Applications with assignments will be imported as an Access List. If an Okta 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.
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
- 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.
- Click Edit on the Okta App Settings page, check the box marked Enable SCIM provisioning, and click Save.
Configure Okta SCIM Client
- Click on the new Provisioning tab and then click Edit.
- 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.
- Set the Okta Unique identifier field for users to
userName
. - Under Supported provisioning actions, check the following boxes:
- Import New Users and Profile Updates
- Push New Users
- Push Profile Updates
- Set Authentication Mode to
HTTP Header
- Copy the authorization Bearer Token from the Teleport Set Up SCIM guide and paste it into Bearer Token field in the Okta provisioning page.
- Click Save
Configure Okta-To-App Provisioning
- Staying on the Provisioning tab, go to the new To App Okta application settings page and click Edit.
- Check the following checkboxes:
- Create Users
- Update User Attributes
- Deactivate Users
- Click Save
For more information about how the Okta integration manages Teleport resources, see the Synchronization with Okta and SCIM guide.
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
If the hosted integration is still active, removing Okta sourced Access Lists could revoke Okta access from users in your organization. Please exercise caution when cleaning up Access Lists!
All Access Lists imported by 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 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.
Any Teleport accounts deleted with tctl
will be recreated on the next
synchronization pass unless they are also unassigned and/or disabled in the
upstream Okta organization.