

Setting up Okta SSO with Teleport
Length: 09:16
This guide covers how to configure Okta to provide single sign on (SSO) identities to Teleport Enterprise and Teleport Enterprise Cloud. When used in combination with role-based access control (RBAC), this allows Teleport administrators to define policies like:
- Only members of the "DBA" group can access PostgreSQL databases.
- Developers must never SSH into production servers.
- Members of the HR group can view audit logs but not production environments.
Prerequisites
- An Okta account with admin access. Your account must include users and at least two groups. If you don't already have Okta groups you want to assign to Teleport roles don't worry, we'll create example groups below.
-
A running Teleport Enterprise cluster, including the Auth Service and Proxy Service. For details on how to set this up, see our Enterprise Getting Started guide.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 12.1.1, which you can download by visiting the customer portal.tctl versionTeleport Enterprise v12.1.1 go1.19
tsh versionTeleport v12.1.1 go1.19
Please use the latest version of Teleport Enterprise documentation.
- A Teleport role with access to edit and maintain
saml
resources. This is available in the defaulteditor
role.
To connect to Teleport, log in to your cluster using tsh
, then use tctl
remotely:
tsh login --proxy=teleport.example.com [email protected]tctl statusCluster teleport.example.com
Version 12.1.1
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.
To connect to Teleport, log in to your cluster using tsh
, then use tctl
remotely:
tsh login --proxy=myinstance.teleport.sh [email protected]tctl statusCluster myinstance.teleport.sh
Version 12.1.2
CA pin sha256:sha-hash-here
You must run subsequent tctl
commands in this guide on your local machine.
-
Configure Teleport to use SAML authentication as the default instead of the local user database.
You can either edit the Teleport Auth Service configuration file or create a dynamic resource.
Update
/etc/teleport.yaml
in theauth_service
section and restart theteleport
daemon.auth_service: authentication: type: saml
Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.
Step 1/4. Create & assign groups
Okta indicates a user's group membership as a SAML assertion in the data it provides to Teleport. We will configure Teleport to assign roles (called "dev" and "admin") based on these groups.
If you already have Okta groups you want to assign to "dev" and "admin" roles in Teleport, you can skip to the next step.
Create Groups
Create two groups: "okta-dev" and "okta-admin". In the Okta dashboard go to the navigation bar and click Directory -> Groups, then Add group:

Repeat for the admin group:

Step 2/4. Configure Okta
In this section we will create an application in the Okta dashboard to allow our Teleport cluster to access Okta as an IdP provider. We'll also locate the address that Okta uses to provides their IdP metadata to Teleport.
First, create a SAML 2.0 Web App in Okta:
From the main navigation menu, select Applications -> Applications, and click Create App Integration. Select SAML 2.0, then click Next.

On the next screen (General Settings), provide a name and optional logo for your new app, then click Next. This will bring you to the Configure SAML section.
Configure the App
Provide the following values to their respective fields:
General
- Single sign on URL:
https://<cluster-url>/v1/webapi/saml/acs/new_saml_connector
- Audience URI (SP Entity ID):
https://<cluster-url>/v1/webapi/saml/acs/new_saml_connector
- Name ID format
EmailAddress
- Application username
Okta username
Replace <cluster-url>
with your Teleport Proxy Service address or Enterprise
Cloud tenant (e.g. mytenant.teleport.sh
).
Attribute Statements
- Name:
username
| Name format:Unspecified
| Value:user.login
Group Attribute Statements
We will map our Okta groups to SAML attribute statements (special signed metadata exposed via a SAML XML response), so that Teleport can discover a user's group membership and assign matching roles.
- Name:
groups
| Name format:Unspecified
- Filter:
Matches regex
|.*
The configuration page should now look like this:

The "Matches regex" filter requires the literal string .*
in order to match all
content from the group attribute statement.
Notice that we have set "NameID" to the email format and mapped the groups with a wildcard regex in the Group Attribute statements. We have also set the "Audience" and SSO URLs to the same value. This is so Teleport can read and use Okta users' email addresses to create their usernames in Teleport, instead of relying on additional name fields.
Once you've filled the required fields, click Next, then finish the app creation wizard.
From the Assignments tab of the new application page, click Assign. Assign the newly created groups access to the app.

Save IdP metadata path
Okta provides an IdP metadata block, used by clients to identify and verify it as a trusted source of user identity.
Since Okta serves this content over HTTPS we can configure Teleport to use this path instead of a local copy, which can go stale.
From the app's Sign On tab, scroll down to SAML Signing Certificates. Click Actions for the SHA-2 entry, then "View IdP metadata":

Copy the URL to the metadata file for use in our Teleport configuration.
You can also right click on the "View IdP metadata" link and select "Copy Link" or "Copy Link Address".
Step 3/4. Create a SAML connector
Define a SAML connector resource in a local file named okta-connector.yaml
:
#
# Example resource for a SAML connector
# This connector can be used for SAML endpoints like Okta
#
kind: saml
version: v2
metadata:
# the name of the connector
name: okta
spec:
# connector display name that will be appended to the title of "Login with"
# button on the cluster login screen so it will say "Login with Okta"
display: Okta
# SAML provider will make a callback to this URL after successful authentication
# cluster-url is the address the cluster UI is reachable at.
# The last segment of the URL must be identical to the connector metadata name.
acs: https://<cluster-url>/v1/webapi/saml/acs/new_saml_connector
# Controls whether IdP-initiated SSO is allowed. If false, all such requests will be rejected with an error.
allow_idp_initiated: false
attributes_to_roles:
- name: groups
value: okta-admin
roles:
- editor
- name: groups
value: okta-dev
roles:
- access
# Provides a path to the IdP metadata.
entity_descriptor_url: https://example.okta.com/app/your-app-id/sso/saml/metadata
Update the value of acs
with your Teleport Proxy address or Enterprise Cloud tenant
(e.g. mytenant.teleport.sh
), and replace the value of entity_descriptor_url
with the path you copied in the previous step.
The attributes_to_roles
field in the connector resource maps key/value-like attributes of
the assertion from Okta into a list of Teleport roles to apply to the session.
Enabling the allow_idp_initiated
flag in SAML connectors allows users to
log in to Teleport with one click from the dashboard provided by the IdP.
This feature is potentially unsafe and should be used with caution.
Enabling IdP-initiated login comes with notable security risks such as:
- Possibility of replay attacks on the SAML payload giving an attacker a secret web session
- Increased risk of session hijacking and impersonation attacks based on intercepting SAML communications
Create the connector using tctl
tool:
tctl create okta-connector.yaml
Step 4/4. Create a developer Teleport role
Now let's create a new role to pull in external information from Okta.
Create the local file dev.yaml
with the content below.
kind: role
version: v5
metadata:
name: dev
spec:
options:
max_session_ttl: 24h
allow:
logins: [ "{{email.local(external.username)}}", ubuntu ]
node_labels:
access: relaxed
Members of this role have are assigned several attributes:
- they are only allowed to login to nodes labelled with
access: relaxed
label. - they can log in as
ubuntu
user or a user matching their email prefix. - they do not have any "allow rules" i.e. they will not be able to see/replay past sessions or re-configure the Teleport cluster.
Notice the {{external.username}}
login. It configures Teleport to look at the
"username" Okta claim and use that field as an allowed login for each user. This
example uses email as the username format. The email.local(external.username)
function call will remove the @domain
and leave the username prefix.
Use tctl to create this role in the Teleport Auth Service:
tctl create dev.yaml
Testing
The Web UI now contains a new "Okta" button at the login screen. The CLI behaves the same as before, but now you provide the email associated with an Okta account:
tsh login --proxy=proxy.example.com [email protected]
This command prints the SSO login URL (and will try to open it automatically in a browser).
Teleport can use multiple SAML connectors. In this case a connector name
can be passed via the --auth
flag. For the connector we created above:
tsh login --proxy=proxy.example.com [email protected] --auth=okta
Troubleshooting
Troubleshooting SSO configuration can be challenging. Usually a Teleport administrator must be able to:
- Ensure that HTTP/TLS certificates are configured properly for both Teleport proxy and the SSO provider.
- Be able to see what SAML/OIDC claims and values are getting exported and passed by the SSO provider to Teleport.
- Be able to see how Teleport maps the received claims to role mappings as defined in the connector.
If something is not working, we recommend to:
- Double-check the host names, tokens and TCP ports in a connector definition.
Using the Web UI
If you get "access denied" or other login errors, the number one place to check is the Audit Log. You can access it in the Activity tab of the Teleport Web UI.

Example of a user being denied because the role clusteradmin
wasn't set up:
{
"code": "T1001W",
"error": "role clusteradmin is not found",
"event": "user.login",
"method": "oidc",
"success": false,
"time": "2019-06-15T19:38:07Z",
"uid": "cd9e45d0-b68c-43c3-87cf-73c4e0ec37e9"
}
Teleport does not show the expected Nodes
When Teleport's Auth Service receives a request to list Teleport Nodes (e.g., to
display Nodes in the Web UI or via tsh ls
), it only returns the Nodes that the
current user is authorized to view.
For each Node in the user's Teleport cluster, the Auth Service applies the following checks in order and, if one check fails, hides the Node from the user:
- None of the user's roles contain a
deny
rule that matches the Node's labels. - At least one of the user's roles contains an
allow
rule that matches the Node's labels.
If you are not seeing Nodes when expected, make sure that your user's roles
include the appropriate allow
and deny
rules as documented in the
Teleport Access Controls Reference.
When configuring SSO, ensure that the identity provider is populating each user's
traits correctly. For a user to see a Node in Teleport, the result of populating a
template variable in a role's allow.logins
must match at least one of a user's
traits.logins
.
In this example a user will have usernames ubuntu
, debian
and usernames from the SSO trait logins
for Nodes that have a env: dev
label. If the SSO trait username is bob
then the usernames would include ubuntu
, debian
, and bob
.
kind: role
metadata:
name: example-role
spec:
allow:
logins: ['{{external.logins}}', ubuntu, debian]
node_labels:
'env': 'dev'
version: v5