Skip to main content
Version: 16.x

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​

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.

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.

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.