Skip to main content

Okta Service Reference Documentation

Configuration​

Warning

Backing up production instances, environments, and/or settings before making permanent modifications is encouraged as a best practice. Doing so allows you to roll back to an existing state if needed.

The following snippet shows the full YAML configuration of the Okta Service as it would appear in the teleport.yaml configuration file:

# This section configures the Okta service.
okta_service:
  # Enables the Okta service. Default is 'no'
  enabled: yes

  # API endpoint is the API endpoint that the Okta service should use.
  # This is your org URL.
  api_endpoint: https://example.okta.com/

  # Points to a file with the API token as its contents on the local filesystem.
  api_token_path: /path/to/api/token

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.