Skip to main content

Identity Governance is available only with Teleport Enterprise. Start your free trial.

Start your free trial
Version: 19.x (unreleased)

Guided Okta SSO Integration

Report an Issue

The Teleport Okta SSO integration allows Teleport users to authenticate using Okta as an identity provider. Teleport. The guided enrollment flow for the Okta SSO integration is part of the guided Okta integration. This guide is a companion to the guided Okta SSO integration, showing you how to perform required actions within Okta.

If you do not plan to enroll additional components of the guided Okta integration, you can set up only the Okta SSO integration - called an authentication connector - by following Authentication With Okta as an SSO Provider.

Prerequisites​

  • A running Teleport Enterprise cluster. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

  • The tctl and tsh clients.

    Installing tctl and tsh clients

    1. Determine the version of your Teleport cluster. The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/find and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service:

      TELEPORT_DOMAIN=teleport.example.com:443
      TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"

    2. Follow the instructions for your platform to install tctl and tsh clients:

      Download the signed macOS .pkg installer for Teleport, which includes the tctl and tsh clients:

      curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg

      In Finder double-click the pkg file to begin installation.

      danger

      Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

  • To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. For example, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and [email protected] to your Teleport username: 
    tsh login --proxy=teleport.example.com --user=[email protected]
    tctl status
    Cluster  teleport.example.com
    Version  19.0.0-dev
    CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
    If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.
  • An Okta organization with admin access.

Step 1/4. Choose an authentication connector​

  1. Visit the Teleport Web UI and from the left sidebar, navigate to Add New -> Integration.

  2. Select the Okta tile.

  3. In the Choose Your Auth Connector view, select an existing connector or create a new one by selecting an option from the dropdown menu.

You can inspect an existing connector with the tctl command. Replace okta with the name of your connector.

tctl get saml/okta

If one of your existing connectors is named okta, you won't have the option to create a new connector. That's because the name of the connector created by the integration is hardcoded as okta. If you have a connector named okta and you'd like to use a different one, you'll have to create your connector manually following Authentication With Okta as an SSO Provider .

note

If you are using already configured Okta connector, you can skip Okta app configuration and go to the Next steps section of this guide.

Step 2/4. Create and configure an Okta app​

Okta Integration Network support is still in beta. If unsure please proceed with the Custom SAML 2.0 app.

Add Teleport app to Okta if it hasn't been added previously:

  1. In Okta Console, go to Applications.

  2. Click Browse App Catalog.

  3. Search for and select Teleport, and then click Add Integration.

  4. Complete the fields on the settings page and click Done.

  5. Go to the Sign On tab and click Edit on the top-right corner of the tab.

  6. Scroll down to the groups attribute, then select Match regex and type in .* in the input field.

  7. Scroll down and click Save.

Step 3/4. Assign user groups​

  1. In the same Okta Teleport app, go to the Assignments tab and click the Assign dropdown.

  2. Select "Assign to Groups" and search for the Okta groups which members will have access to Teleport.

  3. Click Assign next to each selected groups and click Done.

Step 4/4. Provide your Okta app metadata to Teleport​

  1. Go to the Sign On tab and scroll down to "Metadata URL".

  2. Copy the Metadata URL using the Copy button below it.

  3. Go back to the Teleport Web UI, make sure you are in the Step Two view in the Okta SSO connector enrollment flow, paste the metadata URL and click Continue.

At this point, you have completed the guided flow for the Okta SSO integration. All users assigned to the Okta app are now able to log in to Teleport.

Next steps​

After completing the guided enrollment flow for the Okta SSO integration, you can proceed to one of two guided enrollment flows:

To learn more about Okta integration and how to manage it see the Teleport Okta integration overview page.