Synchronization with Okta and SCIM

The Okta integration imports and synchronizes resources from an Okta organization. This guide details how those Okta resources are represented inside a Teleport cluster.

Synchronization & SCIM

Teleport uses two complimentary methods for synchronizing Teleport resources with an upstream Okta Organization:

• the Okta integration synchronization process
• provisioning via SCIM

On the whole, it doesn't matter to the wider Teleport system which method was used to import a user as both processes create identical resources inside Teleport.

To complement user provisioning, Okta is also able to model Okta permissions as Access Lists, which will effectively import Okta's application permissions into Teleport.

Users

Importing users

During synchronization, the Okta integration will create Teleport user accounts for all eligible Okta users, and clean up the Teleport accounts of any Okta users that have been deactivated. The list of "eligible Okta users" depends on the integration configuration.

If the Okta integration is configured to use a specific Okta application, then the Okta integration will consider any Okta user assigned to that Okta application - either directly, or via group membership - as an "eligible user".

If no Okta application is to use is supplied, all enabled Okta organization users are considered "eligible".

Okta Profile to Teleport User

The Teleport users created by the synchronization process or SCIM provisioning all inherit their username from the upstream Okta organization, and are given a default role of okta-requester.

This Role allows the user to log into Teleport, but grants no default access to Teleport resources. The Teleport admin can use Access Requests and Access Lists to grant access to Teleport resources as they see fit, once the user is imported.

Traits

All non-empty values in the Okta User/AppUser profile are converted to Teleport user traits. For example, an imported Okta user might look like this:

kind: user
metadata:
  name: [email protected]
  labels:
    okta/org: https://enzos-pizza.okta.com
    teleport.dev/origin: okta
roles:
  - okta-requester
spec:
  traits:
    okta/email:
      - [email protected]
    okta/firstName:
      - Hiro
    okta/lastName:
      - Protagonist
    okta/login:
      - [email protected]

Teleport administrators can then use these traits as conditions in Access Lists in order to grant (or deny) the Okta-derived Teleport users access to Teleport resources.

Deleting Users

In the case where

1. the synchronization process detects that an Okta user has been deactivated or suspended, or
2. the Okta organization explicitly disables the account via SCIM,

The Okta integration will immediately delete the corresponding Teleport account and create a temporary Teleport user lock. The user lock will

• terminate any active Teleport sessions, and
• prevent the disabled user from accessing any Teleport resources with credentials issued before their Teleport account was deleted.

The user lock will expire after the maximum possible credential lifetime, plus a small safety margin.

Access Lists

Modeling Okta permissions within Teleport

Okta has its own permissions system that doesn't map cleanly 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 new Access List synchronization feature in the Okta service, this work is performed for you. We'll discuss the details of how this works.

Synchronizing Access Lists from Okta groups and applications

The Okta Access List synchronizer will look for any Okta group with members or any Okta application with individual assignments that matches configurable filters that you can optionally supply. Access lists will not be created for groups or applications without any assignments.

The synchronizer will create the following resources for each matched 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.

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.

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 well as 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.