diff --git a/docs/pages/enterprise/sso.mdx b/docs/pages/enterprise/sso.mdx index c8d2e84dbef46..de5d88a19cd5b 100644 --- a/docs/pages/enterprise/sso.mdx +++ b/docs/pages/enterprise/sso.mdx @@ -5,7 +5,7 @@ h1: Single Sign-On (SSO) for SSH --- Users of the Enterprise edition of Teleport can log in to servers, Kubernetes -clusters, databases, web applications, and Windows desktops through your +clusters, databases, web applications, and Windows desktops through their organization's Single Sign-On (SSO) provider. @@ -55,30 +55,36 @@ organization's Single Sign-On (SSO) provider. ## How does SSO work? -Users need to execute the following command login in the CLI or login using UI: +Execute the following command to log in to your Teleport cluster using the CLI. -```bsh -# this command will automatically open the default web browser and take a user -# through the login process with an SSO provider: +```code +# This command will automatically open the default web browser and take a user +# through the login process with an SSO provider $ tsh login --proxy=proxy.example.com --auth=github +``` -# output: +The command opens a browser window and shows a URL the user can visit in the +terminal to complete their SSO flow: + +```text If browser window does not open automatically, open it by clicking on the link: http://127.0.0.1:45235/055a310a-1099-43ea-8cf6-ffc41d88ad1f ``` -Teleport will wait for up to 3 minutes for a user to authenticate. If authentication -succeeds, Teleport will retrieve an SSH and X.509 certificates and will store them in -`~/.tsh/keys/proxy.example.com` directory. The tool will also will add SSH cert to an -SSH agent if there's one running. +Teleport will wait for up to 3 minutes for a user to authenticate. If +authentication succeeds, Teleport will retrieve SSH and X.509 certificates and +store them in the `~/.tsh/keys/` directory. The tool will also will +add SSH cert to an SSH agent if there's one running. ## Configuring SSO -Teleport works with SSO providers by relying on a concept called -*"authentication connector"*. An auth connector is a plugin which controls how -a user logs in and which group he or she belongs to. +Teleport works with SSO providers by relying on the concept of an +**authentication connector**. An authentication connector is a plugin that +controls how a user logs in and which group they belong to. + +### Supported connectors -The following connectors are supported: +The following authentication connectors are supported: - `local` connector type uses the built-in user database. This database can be manipulated by the `tctl users` command. @@ -87,21 +93,22 @@ The following connectors are supported: - `oidc` connector type uses the [OpenID Connect protocol](https://en.wikipedia.org/wiki/OpenID_Connect) to authenticate users and query their group membership. -To configure SSO, a Teleport administrator must: +### Creating an authentication connector + +Before you can create an authentication connector, you must enable +authentication via that connector's protocol. -- Update the default authentication type. -- Define the connector [resource](../setup/reference/resources.mdx) and save it into - a YAML file (like `connector.yaml`). -- Create the connector using `tctl create connector.yaml`. +To set the default authentication type as `saml` or `oidc`, either modify your Auth Service configuration file +or create a `cluster_auth_preference` resource. -To set the default authentication type as `saml` or `oidc`, either modify your Auth Service configuration file or create a `cluster_auth_preference` resource. - + Update `/etc/teleport.yaml` in the `auth_service` section and restart the `teleport` daemon. ```yaml auth_service: authentication: -# Set as saml or oidc + # Set as saml or oidc type: saml|oidc ``` @@ -113,62 +120,105 @@ To set the default authentication type as `saml` or `oidc`, + + ```code + # Log in to your cluster with tsh so you can run tctl commands. + # You can also run tctl directly on the Auth Service host. + $ tsh login --proxy=teleport.example.com --user=myuser + $ tctl create -f cap.yaml + ``` + + + + ```code + # Log in to your cluster with tsh so you can run tctl commands. + $ tsh login --proxy=mytenant.teleport.sh --user=myuser $ tctl create -f cap.yaml ``` + + -An example of a connector: +Next, define an authentication connector. Create a file called `connector.yaml` +based on one of the following examples. + + + ```yaml -# connector.yaml -kind: saml -version: v2 -metadata: - name: corporate -spec: - # display allows to set the caption of the "login" button - # in the Web interface - display: "Okta" - - acs: https://teleport-proxy.example.com:3080/v1/webapi/saml/acs - attributes_to_roles: - - {name: "groups", value: "okta-admin", roles: ["access"]} - - {name: "groups", value: "okta-dev", roles: ["dev"]} - - # note that wildcards can also be used. the next line instructs Teleport - # to assign "access" role to any user who has the SAML attribute that begins with "admin": - - { name: "group", value: "admin*", roles: ["access"] } - # regular expressions with capture are also supported. the next line instructs Teleport - # to assign users to roles `admin-1` if his SAML "group" attribute equals 'ssh_admin_1': - - { name: "group", value: "^ssh_admin_(.*)$", roles: ["admin-$1"] } - - entity_descriptor: | - +(!/examples/resources/okta-connector.yaml!) ``` -- See [examples/resources](https://github.com/gravitational/teleport/tree/master/examples/resources) - directory in the Teleport Github repository for examples of possible connectors. -- You may use `entity_descriptor_url`, in lieu of `entity_descriptor`, to fetch the entity descriptor from - your IDP. Though, we recommend "pinning" the entity descriptor by including the XML rather than fetching from a URL. + + + +```yaml +(!/examples/resources/onelogin-connector.yaml!) +``` + + + + +```yaml +(!/examples/resources/oidc-connector.yaml!) +``` + + + + +```yaml +(!/examples/resources/gworkspace-connector-inline.yaml!) +``` + + + + +```yaml +(!/examples/resources/adfs-connector.yaml!) +``` + + + + +```yaml +(!/examples/resources/saml-connector.yaml!) +``` + + + + + +You may use `entity_descriptor_url`, in lieu of `entity_descriptor`, to fetch +the entity descriptor from your IDP. + +We recommend "pinning" the entity descriptor by including the XML rather than +fetching from a URL. + +Create the connector: + +```code +$ tctl create -f connector.yaml +``` ### User Logins Often it is required to restrict SSO users to their unique UNIX logins when they -connect to Teleport nodes. To support this: +connect to Teleport Nodes. To support this: -- Use the SSO provider to create a field called *"unix_login"* (you can use another name). -- Make sure it's exposed as a claim via SAML/OIDC. -- Update a Teleport SSH role to include `{{external.unix_login}}` variable into the list of allowed logins: +- Use the SSO provider to create a field called `unix_login` (you can use another name). +- Make sure the `unix_login` field is exposed as a claim via SAML/OIDC. +- Update a Teleport role to include the `{{external.unix_login}}` variable in the list of allowed logins: ```yaml kind: role @@ -203,10 +253,10 @@ At this time, the `spec.provider` field should not be set for any other identity ## Working with External Email Identity Along with sending groups, an SSO provider will also provide a user's email address. -In many organizations, the username that a person uses to log into a system is the -same as the first part of their email address - the 'local' part. For example, `dave.smith@acme.com` might log in with the username `dave.smith`. Teleport provides an easy way to extract the first part of an email address so it can be used as a username - this is the `{{email.local}}` function. +In many organizations, the username that a person uses to log in to a system is the +same as the first part of their email address, the "local" part. For example, `dave.smith@acme.com` might log in with the username `dave.smith`. Teleport provides an easy way to extract the first part of an email address so it can be used as a username. This is the `{{email.local}}` function. -If the email claim from the identity provider (which can be accessed via `{{external.email}}`) is sent and contains an email address, you can extract the 'local' part of the email address before the @ sign like this: `{{email.local(external.email)}}` +If the email claim from the identity provider (which can be accessed via `{{external.email}}`) is sent and contains an email address, you can extract the "local" part of the email address before the @ sign like this: `{{email.local(external.email)}}` Here's how this looks in a Teleport role: diff --git a/docs/pages/enterprise/sso/adfs.mdx b/docs/pages/enterprise/sso/adfs.mdx index ed90016f43047..c9f283fd5b771 100644 --- a/docs/pages/enterprise/sso/adfs.mdx +++ b/docs/pages/enterprise/sso/adfs.mdx @@ -40,7 +40,9 @@ like: - Teleport role with access to maintaining `saml` resources. This is available in the default `editor` role. -(!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) +(!docs/pages/includes/commercial-prereqs-tabs.mdx!) + +(!docs/pages/includes/tctl.mdx!) (!docs/pages/includes/enterprise/samlauthentication.mdx!) diff --git a/docs/pages/enterprise/sso/azuread.mdx b/docs/pages/enterprise/sso/azuread.mdx index c0e6c989d95fe..62c4871a9735b 100644 --- a/docs/pages/enterprise/sso/azuread.mdx +++ b/docs/pages/enterprise/sso/azuread.mdx @@ -40,8 +40,9 @@ Before you get started you’ll need: - To create at least two security groups in Azure AD and assign one or more users to each group - Teleport role with access to maintaining `saml` resources. This is available in the default `editor` role. +(!docs/pages/includes/commercial-prereqs-tabs.mdx!) -(!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) +(!docs/pages/includes/tctl.mdx!) (!docs/pages/includes/enterprise/samlauthentication.mdx!) diff --git a/docs/pages/enterprise/sso/gitlab.mdx b/docs/pages/enterprise/sso/gitlab.mdx index c5394b5fd227b..4e9826a2250b6 100644 --- a/docs/pages/enterprise/sso/gitlab.mdx +++ b/docs/pages/enterprise/sso/gitlab.mdx @@ -39,10 +39,9 @@ like: - At least two groups in GitLab with users assigned. - Teleport role with access to maintaining `oidc` resources. This is available in the default `editor` role. -(!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) - -(!docs/pages/includes/sso/tctlconnection.mdx!) +(!docs/pages/includes/commercial-prereqs-tabs.mdx!) +(!docs/pages/includes/tctl.mdx!) ## Enable default OIDC authentication diff --git a/docs/pages/enterprise/sso/google-workspace.mdx b/docs/pages/enterprise/sso/google-workspace.mdx index 00ea3880a1704..19b9410aa0c3b 100644 --- a/docs/pages/enterprise/sso/google-workspace.mdx +++ b/docs/pages/enterprise/sso/google-workspace.mdx @@ -42,7 +42,9 @@ Before you get started you’ll need: - Ability to set up Google Workspace groups. - Teleport role with access to maintaining `oidc` resources. This is available in the default `editor` role. -(!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) +(!docs/pages/includes/commercial-prereqs-tabs.mdx!) + +(!docs/pages/includes/tctl.mdx!) ## Step 1/4. Enable default OIDC authentication diff --git a/docs/pages/enterprise/sso/oidc.mdx b/docs/pages/enterprise/sso/oidc.mdx index e7afa0de5f003..1d07f4b1afb9d 100644 --- a/docs/pages/enterprise/sso/oidc.mdx +++ b/docs/pages/enterprise/sso/oidc.mdx @@ -35,9 +35,11 @@ administrators to define policies like: ## Prerequisites - Admin access to the SSO/IdP being integrated with users assigned to groups/roles. -- Teleport role with access to maintaining `oidc` resources. This is available in the default `editor` role. +- Teleport role with access to maintaining `oidc` resources. This is available in the default `editor` role. -(!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) +(!docs/pages/includes/commercial-prereqs-tabs.mdx!) + +(!docs/pages/includes/tctl.mdx!) ## Enable default OIDC authentication diff --git a/docs/pages/enterprise/sso/okta.mdx b/docs/pages/enterprise/sso/okta.mdx index 7c2e964d94a11..cf2f9848ede34 100644 --- a/docs/pages/enterprise/sso/okta.mdx +++ b/docs/pages/enterprise/sso/okta.mdx @@ -39,7 +39,9 @@ like: - Okta account with admin access. Your account must include users and at least two groups. - Teleport role with access to maintaining `saml` resources. This is available in the default `editor` role. -(!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) +(!docs/pages/includes/commercial-prereqs-tabs.mdx!) + +(!docs/pages/includes/tctl.mdx!) (!docs/pages/includes/enterprise/samlauthentication.mdx!) diff --git a/docs/pages/enterprise/sso/one-login.mdx b/docs/pages/enterprise/sso/one-login.mdx index fe270b62ab4bc..9093bd462dc18 100644 --- a/docs/pages/enterprise/sso/one-login.mdx +++ b/docs/pages/enterprise/sso/one-login.mdx @@ -37,7 +37,9 @@ like: - One Login account with admin access and users assigned to at least two groups. - Teleport role with access to maintaining `saml` resources. This is available in the default `editor` role. -(!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) +(!docs/pages/includes/commercial-prereqs-tabs.mdx!) + +(!docs/pages/includes/tctl.mdx!) (!docs/pages/includes/enterprise/samlauthentication.mdx!) diff --git a/docs/pages/includes/edition-prereqs-tabs.mdx b/docs/pages/includes/edition-prereqs-tabs.mdx index 010ac98286210..701d476efcbc0 100644 --- a/docs/pages/includes/edition-prereqs-tabs.mdx +++ b/docs/pages/includes/edition-prereqs-tabs.mdx @@ -9,7 +9,7 @@ files in partials, this partial uses relative URL paths instead. - A running Teleport cluster. For details on how to set this up, see one of our [Getting Started](/docs/getting-started) guides. -- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=) on a Desktop or administrative access on the Teleport Auth Service machine. +- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=). ```code $ tctl version @@ -24,26 +24,39 @@ files in partials, this partial uses relative URL paths instead. -- Installed Enterprise version of Teleport (downloaded via the [Enterprise dashboard](https://dashboard.gravitational.com/web/login)). -- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=) on a Desktop or administrative access on the Teleport Auth Service machine. -You can download these by visiting the + +- A running Teleport cluster. For details on how to set this up, see our Enterprise + [Getting Started](/docs/enterprise/getting-started) guide. + +- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=), + which you can download by visiting the [customer portal](https://dashboard.gravitational.com/web/login). + ```code $ tctl version # Teleport v(=teleport.version=) go(=teleport.golang=) + + $ tsh version + # Teleport v(=teleport.version=) go(=teleport.golang=) ``` + -- Teleport Cloud account (sign up for a [free trial](https://goteleport.com/signup)). -- The `tctl` admin client version >= (=cloud.version=). +- A Teleport Cloud account. If you do not have one, visit the + [sign up page](https://goteleport.com/signup/) to begin your free trial. - You can download this from [Teleport Cloud Downloads](/docs/cloud/downloads). +- The `tctl` admin tool and `tsh` client tool version >= (=cloud.version=). + To download these tools, visit the [Downloads](/docs/cloud/downloads) page. ```code $ tctl version # Teleport v(=cloud.version=) go(=teleport.golang=) + + $ tsh version + # Teleport v(=cloud.version=) go(=teleport.golang=) ``` + - + \ No newline at end of file diff --git a/docs/pages/includes/enterprise/ent-user-prereqs.mdx b/docs/pages/includes/enterprise/ent-user-prereqs.mdx deleted file mode 100644 index 84edfb49fe185..0000000000000 --- a/docs/pages/includes/enterprise/ent-user-prereqs.mdx +++ /dev/null @@ -1,40 +0,0 @@ - - -- Installed Enterprise version of Teleport (downloaded via the [Enterprise dashboard](https://dashboard.gravitational.com/web/login)). -- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=) on a Desktop or administrative access on the Teleport Auth Service machine. You can download these by visiting the [customer portal](https://dashboard.gravitational.com/web/login). - ```code - $ tctl version - # Teleport v(=teleport.version=) go(=teleport.golang=) - ``` -To connect to Teleport, log in to your cluster using `tsh`, then use `tctl` -remotely: - -```code -$ tsh login --proxy=teleport.example.com --user=myuser -$ tctl status -# Cluster tele.example.com -# Version (=teleport.version=) -# CA pin sha256:sha-hash-here -``` - - -- Teleport Cloud account (sign up for a [free trial](https://goteleport.com/signup)). - -- The `tctl` admin client version >= (=cloud.version=). - - You can download this from [Teleport Cloud Downloads](/docs/cloud/downloads). - -To connect to Teleport, log in to your cluster using `tsh`, then use `tctl` -remotely: - -```code -$ tsh login --proxy=myinstance.teleport.sh --user=email@example.com -$ tctl status -# Cluster myinstance.teleport.sh -# Version (=cloud.version=) -# CA pin sha256:sha-hash-here -``` - - diff --git a/docs/pages/includes/enterprise/oidcauthentication.mdx b/docs/pages/includes/enterprise/oidcauthentication.mdx index a609ee7c6d925..a901b50a5f13a 100644 --- a/docs/pages/includes/enterprise/oidcauthentication.mdx +++ b/docs/pages/includes/enterprise/oidcauthentication.mdx @@ -1,18 +1,30 @@ Configure Teleport to use OIDC authentication as the default instead of the local -user database. You can use Dynamic Resources for Teleport Cloud as well as self-hosted deployments. +user database. + + + +You can either edit your Teleport configuration file or create a dynamic +resource. + + - + + Update `/etc/teleport.yaml` in the `auth_service` section and restart the `teleport` daemon. + ```yaml auth_service: authentication: type: oidc ``` + + Create a file called `cap.yaml`: + ```yaml kind: cluster_auth_preference metadata: diff --git a/docs/pages/includes/enterprise/samlauthentication.mdx b/docs/pages/includes/enterprise/samlauthentication.mdx index e553fb34baa93..d515376d0a164 100644 --- a/docs/pages/includes/enterprise/samlauthentication.mdx +++ b/docs/pages/includes/enterprise/samlauthentication.mdx @@ -1,10 +1,17 @@ ## Enable default SAML authentication Configure Teleport to use SAML authentication as the default instead of the local -user database. You can use Dynamic Resources for Teleport Cloud as well as self-hosted deployments. +user database. + + + +You can either edit your Teleport configuration file or create a dynamic +resource. + + - + Update `/etc/teleport.yaml` in the `auth_service` section and restart the `teleport` daemon. ```yaml auth_service: diff --git a/docs/pages/includes/sso/tctlconnection.mdx b/docs/pages/includes/sso/tctlconnection.mdx deleted file mode 100644 index c0d0e298001ff..0000000000000 --- a/docs/pages/includes/sso/tctlconnection.mdx +++ /dev/null @@ -1,40 +0,0 @@ -
- -To connect to Teleport, log in to your cluster using `tsh`, then use `tctl` -remotely: - -```code -$ tsh login --proxy=teleport.example.com --user=myuser -$ tctl status -# Cluster tele.example.com -# Version (=teleport.version=) -# CA pin sha256:sha-hash-here -``` - -
-
- -To connect to Teleport, log in to your cluster using `tsh`, then use `tctl` -remotely: - -```code -$ tsh login --proxy=myinstance.teleport.sh --user=email@example.com -$ tctl status -# Cluster myinstance.teleport.sh -# Version (=cloud.version=) -# CA pin sha256:sha-hash-here -``` - -You must run subsequent `tctl` commands in this guide on your local machine. - -
diff --git a/docs/pages/setup/admin/github-sso.mdx b/docs/pages/setup/admin/github-sso.mdx index f8b44222e54db..17acc90733a4f 100644 --- a/docs/pages/setup/admin/github-sso.mdx +++ b/docs/pages/setup/admin/github-sso.mdx @@ -16,7 +16,7 @@ Teleport. (!docs/pages/includes/edition-prereqs-tabs.mdx!) -(!docs/pages/includes/sso/tctlconnection.mdx!) +(!docs/pages/includes/tctl.mdx!) ## Step 1/3. Create a GitHub OAuth app diff --git a/examples/resources/okta-connector.yaml b/examples/resources/okta-connector.yaml new file mode 100644 index 0000000000000..3ba2582fbb388 --- /dev/null +++ b/examples/resources/okta-connector.yaml @@ -0,0 +1,24 @@ +# connector.yaml +kind: saml +version: v2 +metadata: + name: corporate +spec: + # display allows to set the caption of the "login" button + # in the Web interface + display: "Okta" + + acs: https://teleport-proxy.example.com:3080/v1/webapi/saml/acs + attributes_to_roles: + - {name: "groups", value: "okta-admin", roles: ["access"]} + - {name: "groups", value: "okta-dev", roles: ["dev"]} + + # note that wildcards can also be used. the next line instructs Teleport + # to assign "access" role to any user who has the SAML attribute that begins with "admin": + - { name: "group", value: "admin*", roles: ["access"] } + # regular expressions with capture are also supported. the next line instructs Teleport + # to assign users to roles `admin-1` if his SAML "group" attribute equals 'ssh_admin_1': + - { name: "group", value: "^ssh_admin_(.*)$", roles: ["admin-$1"] } + + entity_descriptor: | + \ No newline at end of file