Skip to main content
Version: 17.x (unreleased)

Okta Service Reference Documentation

This guide describes interfaces and options for configuring the Teleport Okta Service, including Okta import rules, Okta assignments, and tctl commands. It also includes troubleshooting instructions.

Okta Import Rule resources​

Full YAML spec of Okta import rule resources managed by tctl resource commands:

kind: okta_import_rule
version: v1
metadata:
  name: test-rule
  description: "Okta import rule for admins"
spec:
  # Okta Import Rules will be applied in the order of the listed priority. Rules
  # with lower numbers will be applied first. In the event of a conflict, labels
  # applied by rules with lower priorities will be overwritten by labels associated
  # with higher priorities.
  priority: 10
  # Mappings describes a list of match directives that describe what labels to
  # apply to specific Okta groups and applications that will be synchronized
  # into Teleport.
  mappings:
  - match:
    # Individual application IDs can be used to create matches. Imported Okta
    # applications will be matched based on the app IDs listed here.
    - app_ids: ["app1", "app2"]
    # These labels will be added to matching applications.
    add_labels:
      app_label: app_label_value
  - match:
    # Similarly, group IDs can be used to create matches.
    - group_ids: ["group1", "group2"]
    # These labels will be added to the groups.
    add_labels:
      label1: value1
  - match:
    # Regexes based on the app name can be used to create matches.
    - app_name_regexes: ["^okta.*$", "app*"]
    # These labels will be added to matching applications.
    add_labels:
      app_label: app_label_value
  - match:
    # Similarly, regexes based on the group name can be used as well.
    - group_name_regexes: ["^okta.*$", "app*"]
    # These labels will be added to the groups.
    add_labels:
      label1: value1

You can create a new okta_import_rule resource by running the following commands, which assume that you have created a YAML file called okta-import-rule.yaml with your configuration:

# Log in to your cluster with tsh so you can use tctl from your local machine.
# You can also run tctl on your Auth Service host without running "tsh login"
# first.
$ tsh login --proxy=teleport.example.com --user=myuser
# Create the resource
$ tctl create -f okta-import-rule.yaml

Okta Assignment resources​

These objects are internally facing and are not intended to be modified by users. However, you can query them for informational or debugging purposes.

Full YAML spec of Okta assignment resources queried by tctl resource commands:

kind: okta_assignment
version: v1
metadata:
  name: test-assignment
spec:
  # The user that the Okta assignment is granting access for.
  user: test-user@test.user
  # The list of targets to grant access to.
  targets:
  # An application target.
  - type: application
    id: "123456"
  # A group target.
  - type: group
    id: "234567"
  # The current status of the Okta assignment.
  status: pending

CLI​

This section shows CLI commands relevant for managing Okta Service behaviors.

tctl get okta_import_rules​

Lists available Okta import rules.

$ tctl get okta_import_rules

tctl get okta_import_rules/NAME​

Gets an individual Okta import rule.

$ tctl get okta_import_rules/my-import-rule

tctl rm okta_import_rules/NAME​

Removes an individual Okta import rule.

$ tctl rm okta_import_rules/my-import-rule

tctl get okta_assignments​

Lists available Okta assignments.

$ tctl get okta_assignments

tctl get okta_assignments/NAME​

Gets an individual Okta assignment.

$ tctl get okta_assignments/my-assignment

Troubleshooting​

No Okta groups or applications seen in the Teleport UI​

If the Teleport applications UI isn't displaying any Okta applications, ensure that the Okta API token and endpoint are correct in the Okta service.

If they are, double check the user permissions and ensure that the user has appropriate resource and label level access to the groups and applications. You may need to tweak the app_labels and group_labels sections of a role in order to see these resources.