# Guided Okta SSO Integration The Teleport Okta SSO integration allows Teleport users to authenticate using Okta as an identity provider. The guided enrollment flow for the Okta SSO integration is part of the [guided Okta integration](https://goteleport.com/docs/identity-governance/integrations/okta.md). 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](https://goteleport.com/docs/zero-trust-access/sso/integrate-idp/okta.md). ## Prerequisites - A running Teleport Enterprise cluster. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/get-started/deploy-community.md). - 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: **Mac** 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. --- **Windows - Powershell** ``` $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip Unzip the archive and move the `tctl` and `tsh` clients to your %PATH% NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP. Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\) instead. ``` **Linux** All of the Teleport binaries in Linux installations include the `tctl` and `tsh` clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/installation.md). ``` $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ cd teleport $ sudo ./install Teleport binaries have been copied to /usr/local/bin ``` * 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\@example.com to your Teleport username: ``` $ tsh login --proxy=teleport.example.com --user=email@example.com $ 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. ![Enroll an integration](/docs/assets/images/okta-tile-1c91005b7f21c831a7a5d6d7cdcd2ac3.png) 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 ](https://goteleport.com/docs/zero-trust-access/sso/integrate-idp/okta.md). --- 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. **Okta Integration Network** 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. In the *Teleport cluster domain* field, type in your Teleport Proxy Service domain, e.g. `example.teleport.sh` 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. ![Set groups attribute](/docs/assets/images/group-regex-bff3b37cf8dc118360916d3febfe9cc5.png) 7. Scroll down and click **Save**. **Custom SAML 2.0 app (legacy)** --- NOTE Please note this is a legacy way of setting up the Teleport SSO app. The preferred way is to use Okta Integration Network app. --- 1. In Okta Console, go to **Applications**. 2. Click **Create App Integration**. 3. Select "SAML 2.0" and click **Next**. 4. Give your app a name, e.g. "Teleport" and optionally upload a logo and click **Next**. 5. That will bring you to the "Configure SAML" step where you'll have to provide several values: - Single sign on URL: ``` https://example.teleport.sh/v1/webapi/saml/acs/okta ``` - Audience URI (SP Entity ID): ``` https://example.teleport.sh/v1/webapi/saml/acs/okta ``` - Name ID format `EmailAddress` - Application username `Okta username` ![SAML general settings](/docs/assets/images/legacy-general-settings-fe23dfb6475dd3e797fadad601c549d8.png) 6. Click **Next**. That will bring you to the "Feedback" step where you can just click **Finish**. 7. Now you should be in your newly created SAML app configuration screen in the **Sign On** tab. Scroll down to the **Attribute statements** and click **Add expression**. Provide values like below and click **Save**. - Name: `groups` - Expression: `user.getGroups({'group.type': {'OKTA_GROUP', 'APP_GROUP', 'BUILT_IN'}}).![profile.name]` - Name: `username` - Expression: `user.profile.login` ![Set groups attribute](/docs/assets/images/legacy-group-expression-e022c16d1402928525199b7e764d1701.png) ## 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**. ![Assign user groups](/docs/assets/images/assign-groups-fbf3fbc629b2b979f3e78cb3076d6b33.png) ## 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. ![Copy metadata URL](/docs/assets/images/copy-metadata-url-d7ba5644539143e4607a2d452cd3507e.png) 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**. ![Paste metadata URL](/docs/assets/images/paste-metadata-url-23164f66ebe37b2ec43dde929b2787a3.png) 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. To log in using the Okta connector, open the web UI and click the **Okta** button at the bottom of the page. To log in using the `tsh` CLI: ## Supported features By default, the Okta SSO integration supports JIT (Just-In-Time) Provisioning using the SP-initiated flow. To enable the IdP-initiated flow you will have to: 1. Edit the Okta SAML connector with the following command: ``` $ tctl edit saml/okta ``` 2. In your editor, set `spec.allow_idp_initiated` to `true`. ## SAML attributes mapping Attributes send by default: - `username` mapped to `user.login`. - `groups` mapped to a list all user's Okta groups. Extra attributes can be optionally configured using [this Okta guide](https://support.okta.com/help/s/article/pass-extra-attributes-in-saml-oin-apps?language=en_US). All attributes sent with the SAML assertion will be stored as the [user's external traits](https://goteleport.com/docs/reference/access-controls/roles.md#referring-to-external-traits-in-teleport-roles) which then can be used to build RBAC rules. ## Teleport role assignment This section explains how to assign Teleport roles to Okta SSO users. ### Access Lists The preferred way to assign a Teleport role to an Okta SSO user is by adding them as members of [Access Lists](https://goteleport.com/docs/identity-governance/access-lists.md) granting the desired roles. Access List membership can be created before the SSO user is created (i.e. before the user logs in for the first time). ### SAML connector attributes to roles mapping The alternative is to use SAML connector attributes to roles mapping. The mapping is defined in the SAML connector resource and can be edited either in the web UI or `tctl`. In the web UI: 1. Navigate to the left sidebar, hover over **Zero Trust Access** and then click **Auth Connectors**. 2. Find the Okta SAML connector tile, click three dots in the top-right corner of the tile and click **Edit**. Using `tctl`: ``` tctl edit saml/okta ``` In the example below there are 2 mappings: - The `groups` attribute containing the value `Everyone` is mapped to the Teleport `okta-requester` role. - The `groups` attribute containing the value `okta-admin` is mapped to the Teleport `editor` role. At least 1 attribute to role mapping is required however we encourage to use Access Lists for access management instead. ``` kind: saml metadata: name: okta spec: acs: https://teleport.example.com:443/v1/webapi/saml/acs/okta attributes_to_roles: - name: groups roles: - editor value: okta-admin - name: groups roles: - okta-requester value: Everyone audience: https://teleport.example.com:443/v1/webapi/saml/acs/okta cert: "" display: "Okta" entity_descriptor: "" entity_descriptor_url: https://example.okta.com/app/000000/sso/saml/metadata issuer: "" service_provider_issuer: https://teleport.example.com:443/v1/webapi/saml/acs/okta sso: "" version: v2 ``` ## Next steps After completing the guided enrollment flow for the Okta SSO integration, you can proceed to one of two guided enrollment flows: - [Okta SCIM integration](https://goteleport.com/docs/identity-governance/integrations/okta/scim-integration.md) - [Okta user sync integration](https://goteleport.com/docs/identity-governance/integrations/okta/user-sync.md) To learn more about Okta integration and how to manage it see the [Teleport Okta integration](https://goteleport.com/docs/identity-governance/integrations/okta.md) overview page.