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".

note

All hosted Okta integrations are configured to restrict their pool of users to a specific Okta application.

The integration enrolment process creates an Okta SAML Application to use as the identity provider for a new SAML Authentication Connector. The enrolment process automatically configures the Okta integration to use this same application, giving the Okta administrator a single point of integration to administer and secure.

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: hiro@enzos-pizza.com
  labels:
    okta/org: https://enzos-pizza.okta.com
    teleport.dev/origin: okta
roles:
  - okta-requester
spec:
  traits:
    okta/email:
      - hiro@enzos-pizza.com
    okta/firstName:
      - Hiro
    okta/lastName:
      - Protagonist
    okta/login:
      - hiro@enzos-pizza.com

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

Given a 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.

warning

Suspended Okta users will not be locked by Teleport.

When a user is suspended in Okta, Okta does not communicate the suspension to Teleport and so Teleport will not automatically lock and remove that user.

Be sure to either deactivate the user, or unassign them from the Okta SAML Application in order to make sure their status is updated in Teleport.

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.

Handling nested Access Lists

Synchronization from Teleport to Okta

Teleport supports nested Access Lists, where an Access List can include other Access Lists as members, creating a hierarchical structure. However, Okta does not support nested groups. To accommodate this limitation, the synchronizer flattens nested Access Lists when synchronizing from Teleport to Okta.

Members in Access Lists, from all levels of nesting, are aggregated into a single, flat list of members when synchronized to Okta. This ensures that all users who should have access according to the Teleport hierarchy are included in the corresponding Okta group or application.

Example:

• Teleport Structure:
  • Access List A:
    • Members: User1
    • Nested Members: Access List B
  • Access List B:
    • Members: User2, User3
• Okta Representation:
  • Group/Application for Access List A:
    • Members: User1, User2, User3

By flattening the Teleport hierarchy, all users receive the permissions associated with the root-level Access List in Okta.

Synchronization from Okta to Teleport

When synchronizing from Okta to Teleport, the synchronizer handles the flattened structure from Okta by attempting to map it back to the Teleport hierarchy:

• Comparing with Teleport Hierarchy: The flattened list of members from Okta is compared against the existing Access List hierarchy in Teleport.
• Adding New Members:
  • New Users: If there are new users added in Okta that are not present in the Teleport Access List hierarchy, these users are added as members at the root-level Access List in Teleport.
  • Maintaining Hierarchy: This approach maintains the hierarchical structure within Teleport while ensuring that access changes made in Okta are reflected appropriately.
• Example:
  • Okta Group/Application for Access List A:
    • Members: User1, User2, User3, User4 (User4 is a new member added in Okta)
  • Teleport Update:
    • Access List A:
      • Members: User1, User4
      • Nested Members: Access List B
    • Access List B:
      • Members: User2, User3

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.

warning

It is possible for an administrator to delete Access Lists, but this should only be done once the Okta integration has been removed and Access List synchronization is disabled. This could remove all users from the Okta group or application that's being targeted!

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.

warning

Removing members from an Okta synchronized Access List will remove the user from the Okta group or Okta application in Okta unless there are other assignments that convey the assignment to the user. In this way, Teleport becomes the source of truth for Okta membership. Please keep this in mind when adding other automated workflows or integrations into your Okta environment.