
Okta application access is currently in Preview mode.
Teleport can import and grant access to Okta applications and user groups. Okta applications can be accessed through Teleport's application access UI, and access to these applications along with user groups can be managed by Teleport's RBAC along with access requests.
This guide will help you set up the Okta Service and provide some basic configurations to enable it.
Prerequisites
-
A running Teleport cluster. For details on how to set this up, see one of our Getting Started guides.
-
The
tctl
admin tool andtsh
client tool version >= 13.0.3.tctl versionTeleport v13.0.3 go1.20
tsh versionTeleport v13.0.3 go1.20
See Installation for details.
-
A running Teleport Enterprise cluster. For details on how to set this up, see our Enterprise Getting Started guide.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 13.0.3, which you can download by visiting your Teleport account.tctl versionTeleport Enterprise v13.0.3 go1.20
tsh versionTeleport v13.0.3 go1.20
Please use the latest version of Teleport Enterprise documentation.
- Make sure you can connect to Teleport. Log in to your cluster using
tsh
, then usetctl
remotely:tsh login --proxy=teleport.example.com [email protected]tctl statusCluster teleport.example.com
Version 13.0.3
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
You can run subsequent
tctl
commands in this guide on your local machine.For full privileges, you can also run
tctl
commands on your Auth Service host. - An Okta organization with an Okta API token provisioned.
- A running Teleport cluster with Okta login configured.
- An instance where you will run the Okta Service. This can live anywhere with outbound access to Okta and must be running Linux.
Step 1/3. Create Okta import rules
Before setting up the Okta Service, you should create Okta import rules in order to ensure that our Okta applications are set up with appropriate labeling before you attempt to synchronize them. First, you'll need to get the group and application IDs from Okta. The easiest way to do this is to use the okta-api-token provisioned earlier.
To get group IDs:
curl -H "Authorization: SSWS okta-api-token" okta-endpoint-url/api/v1/groups | jq '[.[] | {"id": .id, "label": .profile.name}]'...
[
{
"id": "111111",
"label": "Developers"
},
{
"id": "222222",
"label": "Admins"
},
{
"id": "333333",
"label": "Everyone"
},
{
"id": "444444",
"label": "HR"
},
...
]
curl -H "Authorization: SSWS okta-api-token" okta-endpoint-url/api/v1/apps | jq '[.[] | {"id": .id, "label": .label}]'...
[
{
"id": "111111",
"label": "Okta Admin Console"
},
{
"id": "222222",
"label": "Okta Browser Plugin"
},
{
"id": "333333",
"label": "Okta Dashboard"
},
{
"id": "444444",
"label": "SAML test"
},
...
]
From here, you can copy the IDs from the output of the curl
commands and use
these to create the Okta import rule. Put this in a file called okta-import-rule.yaml
:
kind: okta_import_rule
version: v1
metadata:
name: import-rule
description: "Okta import rule for all groups and applications"
spec:
mappings:
- match:
- app_ids: ["111111", "222222", "333333"] # Replace these with your Okta application IDs.
add_labels:
app_label: app-label-value
- match:
- group_ids: ["111111", "222222", "333333"] # Replace these with your Okta group IDs.
add_labels:
group_label: group-label-value
This will ensure that the applications and groups, once synchronized to Teleport, will be given the specified labels.
Step 2/3. Set up the Okta Service
In this step, you'll set up the Okta Service. The Okta Service will interact with Okta's API to import applications and groups, as well as update memberships to those applications and groups. The Okta Service connects back to the Teleport cluster over a reverse tunnel.
Get a join token
Establish trust between your Teleport cluster and the new Okta Service instance by creating a join token:
tctl tokens add --type=okta --ttl=1h --format=textabcd123-insecure-do-not-use-this
On the host where you will install the Teleport Okta Service, create a
file called /tmp/token
that consists only of your token:
echo join-token | sudo tee /tmp/token
Configure the Okta Service
First, on the host where you will run the Okta Service , create a file at okta-api-token-path with the contents of the API token.
Next, on the same host, create a file at /etc/teleport.yaml
with the
following content:
version: v3
teleport:
join_params:
token_name: "/tmp/token"
method: token
proxy_server: "teleport.example.com:443"
auth_service:
enabled: no
proxy_service:
enabled: no
ssh_service:
enabled: no
okta_service:
enabled: yes
api_endpoint: <Var name="okta-endpoint-url" />
api_token_path: <Var name="okta-api-token-path" />
Edit /etc/teleport.yaml
to replace teleport.example.com:443
with the host
and port of your Teleport Proxy Service or Teleport Cloud tenant, e.g.,
mytenant.teleport.sh:443
.
Run the Teleport Application Service
Configure the Teleport Application Service to start automatically when the host boots up by creating a systemd service for it. The instructions depend on how you installed the Teleport Application Service.
On the host where you will run the Teleport Application Service, enable and start Teleport:
sudo systemctl enable teleportsudo systemctl start teleport
On the host where you will run the Teleport Application Service, create a systemd service configuration for Teleport, enable the Teleport service, and start Teleport:
sudo teleport install systemd -o /etc/systemd/system/teleport.servicesudo systemctl enable teleportsudo systemctl start teleport
You can check the status of the Teleport Application Service with systemctl status teleport
and view its logs with journalctl -fu teleport
.
Step 3/3. Connect to the Teleport web UI
Navigate to the application access page within the Teleport web UI to see the list of of synchronized Okta applications. If you're unable to see the applications, please refer to the application Access Controls and update your roles to match the labels given to your applications by the above specified Okta import rules.
You can also try Access Requests by navigating to the Access Requests page and creating a new Access Request. From here, you can navigate to applications and see the Okta applications in the request list:

Or you can navigate to user groups and see the user groups in the request list:

Next steps
- Learn more about accessing APIs with the Teleport Application Service.
- Take a look at application-related Access Controls.