From ea34b2c67cdc5faf060dcbb66aa1369dcaf25c17 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Wed, 4 May 2022 00:18:42 -0400 Subject: [PATCH 01/27] Consistent prerequisites and Teleport cloud --- docs/pages/enterprise/sso/adfs.mdx | 9 ++++ docs/pages/enterprise/sso/azuread.mdx | 4 ++ docs/pages/enterprise/sso/gitlab.mdx | 10 +++++ .../pages/enterprise/sso/google-workspace.mdx | 43 ++----------------- docs/pages/enterprise/sso/oidc.mdx | 10 +++++ docs/pages/enterprise/sso/okta.mdx | 9 ++++ docs/pages/enterprise/sso/one-login.mdx | 9 ++++ .../includes/enterprise/ent-user-prereqs.mdx | 31 +++++++++++++ 8 files changed, 86 insertions(+), 39 deletions(-) create mode 100644 docs/pages/includes/enterprise/ent-user-prereqs.mdx diff --git a/docs/pages/enterprise/sso/adfs.mdx b/docs/pages/enterprise/sso/adfs.mdx index 5304ee567f614..c71dbe33ae2aa 100644 --- a/docs/pages/enterprise/sso/adfs.mdx +++ b/docs/pages/enterprise/sso/adfs.mdx @@ -34,6 +34,15 @@ like: +## Prerequisites + +- Either an Enterprise version of Teleport (downloaded via the [Enterprise dashboard](https://dashboard.gravitational.com/web/login)) or a Teleport Cloud account (sign up for a [free trial](https://goteleport.com/signup)). +- ADFS installation with Admin access with users assigned to at least two groups. + +(!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) + +(!docs/pages/includes/tctl.mdx!) + (!docs/pages/includes/enterprise/samlauthentication.mdx!) ## Configure ADFS diff --git a/docs/pages/enterprise/sso/azuread.mdx b/docs/pages/enterprise/sso/azuread.mdx index 8637d2c1df1ad..1f3adc228253e 100644 --- a/docs/pages/enterprise/sso/azuread.mdx +++ b/docs/pages/enterprise/sso/azuread.mdx @@ -40,6 +40,10 @@ Before you get started you’ll need: - To register one or more users in the directory - To create at least two security groups in Azure AD and assign one or more users to each group +(!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) + +(!docs/pages/includes/tctl.mdx!) + (!docs/pages/includes/enterprise/samlauthentication.mdx!) ## Configure Azure AD diff --git a/docs/pages/enterprise/sso/gitlab.mdx b/docs/pages/enterprise/sso/gitlab.mdx index 183028516f10c..c4c75cf6ef4e3 100644 --- a/docs/pages/enterprise/sso/gitlab.mdx +++ b/docs/pages/enterprise/sso/gitlab.mdx @@ -34,6 +34,16 @@ like: +## Prerequisites + +- Either an Enterprise version of Teleport (downloaded via the [Enterprise dashboard](https://dashboard.gravitational.com/web/login)) or a Teleport Cloud account (sign up for a [free trial](https://goteleport.com/signup/)). +- At least two groups in GitLab with users assigned. + +(!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) + +(!docs/pages/includes/tctl.mdx!) + + ## Enable default OIDC authentication (!docs/pages/includes/enterprise/oidcauthentication.mdx!) diff --git a/docs/pages/enterprise/sso/google-workspace.mdx b/docs/pages/enterprise/sso/google-workspace.mdx index 8d60a89c9969a..476748dfef339 100644 --- a/docs/pages/enterprise/sso/google-workspace.mdx +++ b/docs/pages/enterprise/sso/google-workspace.mdx @@ -37,49 +37,14 @@ to define policies like: Before you get started you’ll need: - - - -- 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=) - ``` - - - - -- A Teleport Cloud account. If you do not have one, visit the - [sign up page](https://goteleport.com/signup/) to begin your free trial. - -- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=). - To download these tools, visit the [Downloads](/docs/cloud/downloads) page. - - ```code - $ tctl version - # Teleport v(=teleport.version=) go(=teleport.golang=) - - $ tsh version - # Teleport v(=teleport.version=) go(=teleport.golang=) - ``` - - - - A Google Workspace super administrator account. We recommend setting up a separate super admin account with 2FA as opposed to granting your daily user super admin privileges. - Ability to create a Google Cloud project, which requires signing up for Google Cloud. Note that this guide will not require using any paid Google Cloud services. - Ability to set up Google Workspace groups. +(!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) + +(!docs/pages/includes/tctl.mdx!) + ## Step 1/4. Enable default OIDC authentication (!docs/pages/includes/enterprise/oidcauthentication.mdx!) diff --git a/docs/pages/enterprise/sso/oidc.mdx b/docs/pages/enterprise/sso/oidc.mdx index 1cb4de19d9657..df6f6c2d11e41 100644 --- a/docs/pages/enterprise/sso/oidc.mdx +++ b/docs/pages/enterprise/sso/oidc.mdx @@ -32,6 +32,16 @@ administrators to define policies like: +## Prerequisites + +- Either an Enterprise version of Teleport (downloaded via the [Enterprise dashboard](https://dashboard.gravitational.com/web/login)) or a Teleport Cloud account (sign up for a [free trial](https://goteleport.com/signup)). +- Admin access to the SSO/IdP being integrated. +- Users with groups/roles assigned. + +(!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) + +(!docs/pages/includes/tctl.mdx!) + ## Enable default OIDC authentication (!docs/pages/includes/enterprise/oidcauthentication.mdx!) diff --git a/docs/pages/enterprise/sso/okta.mdx b/docs/pages/enterprise/sso/okta.mdx index ba591907f33bc..a2e8a76e11747 100644 --- a/docs/pages/enterprise/sso/okta.mdx +++ b/docs/pages/enterprise/sso/okta.mdx @@ -34,6 +34,15 @@ like: +## Prerequisites + +- Either an Enterprise version of Teleport (downloaded via the [Enterprise dashboard](https://dashboard.gravitational.com/web/login)) or a Teleport Cloud account (sign up for a [free trial](https://goteleport.com/signup)). +- Okta Account with Admin access with users and 2 groups. + +(!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) + +(!docs/pages/includes/tctl.mdx!) + (!docs/pages/includes/enterprise/samlauthentication.mdx!) ## Configure Okta diff --git a/docs/pages/enterprise/sso/one-login.mdx b/docs/pages/enterprise/sso/one-login.mdx index 16384bd1e605a..78e9e52d3b254 100644 --- a/docs/pages/enterprise/sso/one-login.mdx +++ b/docs/pages/enterprise/sso/one-login.mdx @@ -32,6 +32,15 @@ like: +## Prerequisites + +- Either an Enterprise version of Teleport (downloaded via the [Enterprise dashboard](https://dashboard.gravitational.com/web/login)) or a Teleport Cloud account (sign up for a [free trial](https://goteleport.com/signup)). +- One Login Account with Admin access with users assigned to at least two groups. + +(!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) + +(!docs/pages/includes/tctl.mdx!) + (!docs/pages/includes/enterprise/samlauthentication.mdx!) ## Configure Application diff --git a/docs/pages/includes/enterprise/ent-user-prereqs.mdx b/docs/pages/includes/enterprise/ent-user-prereqs.mdx new file mode 100644 index 0000000000000..c1dbcadd23eae --- /dev/null +++ b/docs/pages/includes/enterprise/ent-user-prereqs.mdx @@ -0,0 +1,31 @@ + + + +- Access to the machine hosting the Auth Service + +- Maintaining SAML/OIDC auth connectors via the desktop CLI requires enterprise `tctl` admin 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=) + ``` + + + + + +- The `tctl` client Admin tool version >= (=cloud.version=). + + You can download these from [Teleport Cloud Downloads](/docs/cloud/downloads). + + ```code + $ tctl version + # Teleport v(=cloud.version=) go(=teleport.golang=) + ``` + + + From ee966ef8a2d0b10b6db8d94443651bc3f9051c01 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Wed, 4 May 2022 00:27:49 -0400 Subject: [PATCH 02/27] Modified to make cloud example --- docs/pages/enterprise/sso.mdx | 40 ++++++++++++++++++++++++++++------- 1 file changed, 32 insertions(+), 8 deletions(-) diff --git a/docs/pages/enterprise/sso.mdx b/docs/pages/enterprise/sso.mdx index 163d703454025..0285fcf474821 100644 --- a/docs/pages/enterprise/sso.mdx +++ b/docs/pages/enterprise/sso.mdx @@ -89,19 +89,43 @@ The following connectors are supported: To configure SSO, a Teleport administrator must: -- Update `/etc/teleport.yaml` on the auth server to set the default - authentication connector. +- Update the deafult 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`. -```yaml -# snippet from /etc/teleport.yaml on the auth server: -auth_service: - # defines the default authentication connector type: +An example setting the default authentication type as `saml` or `oidc`: + + + Update `/etc/teleport.yaml` in the `auth_service` section and restart the `teleport` daemon. + ```yaml + auth_service: authentication: - type: saml -``` +# Set as saml or oidc + type: saml|oidc + ``` + + + Create a file called `cap.yaml`: + ```yaml + kind: cluster_auth_preference + metadata: + name: cluster-auth-preference + spec: + authentication: +# set as saml or oidc + type: saml|oidc + version: v2 + ``` + + Create a resource: + + ```code + $ tctl create -f cap.yaml + ``` + + + An example of a connector: From 935434b0838321a6050720c9385300e197c43cd5 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Thu, 5 May 2022 21:34:21 -0400 Subject: [PATCH 03/27] spelling mistake Co-authored-by: Paul Gottschling --- docs/pages/enterprise/sso.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/enterprise/sso.mdx b/docs/pages/enterprise/sso.mdx index 0285fcf474821..9a8ad87d19d21 100644 --- a/docs/pages/enterprise/sso.mdx +++ b/docs/pages/enterprise/sso.mdx @@ -89,7 +89,7 @@ The following connectors are supported: To configure SSO, a Teleport administrator must: -- Update the deafult authentication type +- 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`. From 19271383bffeb97984a6f9294eb209eabbce868e Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Thu, 5 May 2022 21:34:42 -0400 Subject: [PATCH 04/27] missing period Co-authored-by: Paul Gottschling --- docs/pages/enterprise/sso.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/enterprise/sso.mdx b/docs/pages/enterprise/sso.mdx index 9a8ad87d19d21..5d592816ab9c7 100644 --- a/docs/pages/enterprise/sso.mdx +++ b/docs/pages/enterprise/sso.mdx @@ -91,7 +91,7 @@ To configure SSO, a Teleport administrator must: - Update the default authentication type. - Define the connector [resource](../setup/reference/resources.mdx) and save it into - a YAML file (like `connector.yaml`) + a YAML file (like `connector.yaml`). - Create the connector using `tctl create connector.yaml`. An example setting the default authentication type as `saml` or `oidc`: From 6b25e9d1e7cdca7d2c6252b038346b928984973e Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Thu, 5 May 2022 21:35:04 -0400 Subject: [PATCH 05/27] verbiage Co-authored-by: Paul Gottschling --- docs/pages/enterprise/sso.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/enterprise/sso.mdx b/docs/pages/enterprise/sso.mdx index 5d592816ab9c7..f997a78a6d3a0 100644 --- a/docs/pages/enterprise/sso.mdx +++ b/docs/pages/enterprise/sso.mdx @@ -118,7 +118,7 @@ An example setting the default authentication type as `saml` or `oidc`: version: v2 ``` - Create a resource: + Create the resource: ```code $ tctl create -f cap.yaml From 58c8c3af49a6b0972d8b9c7583e3e3ac70fcea0f Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Fri, 6 May 2022 22:27:21 -0400 Subject: [PATCH 06/27] verbiage Co-authored-by: Paul Gottschling --- docs/pages/includes/enterprise/ent-user-prereqs.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/includes/enterprise/ent-user-prereqs.mdx b/docs/pages/includes/enterprise/ent-user-prereqs.mdx index c1dbcadd23eae..886c54cfb7e19 100644 --- a/docs/pages/includes/enterprise/ent-user-prereqs.mdx +++ b/docs/pages/includes/enterprise/ent-user-prereqs.mdx @@ -20,7 +20,7 @@ - The `tctl` client Admin tool version >= (=cloud.version=). - You can download these from [Teleport Cloud Downloads](/docs/cloud/downloads). + You can download this from [Teleport Cloud Downloads](/docs/cloud/downloads). ```code $ tctl version From 431db968b4db14f5fe75f68a1a7c4423788b2a0a Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Fri, 6 May 2022 22:27:34 -0400 Subject: [PATCH 07/27] verbiage Co-authored-by: Paul Gottschling --- docs/pages/includes/enterprise/ent-user-prereqs.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/includes/enterprise/ent-user-prereqs.mdx b/docs/pages/includes/enterprise/ent-user-prereqs.mdx index 886c54cfb7e19..d4cacb036bf1c 100644 --- a/docs/pages/includes/enterprise/ent-user-prereqs.mdx +++ b/docs/pages/includes/enterprise/ent-user-prereqs.mdx @@ -18,7 +18,7 @@ -- The `tctl` client Admin tool version >= (=cloud.version=). +- The `tctl` admin client version >= (=cloud.version=). You can download this from [Teleport Cloud Downloads](/docs/cloud/downloads). From ee684983459b0296cf83f4e644f9bbc86a0bcaa5 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Fri, 6 May 2022 22:32:23 -0400 Subject: [PATCH 08/27] cloud and self-host default auth example Co-authored-by: Paul Gottschling --- docs/pages/enterprise/sso.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/enterprise/sso.mdx b/docs/pages/enterprise/sso.mdx index f997a78a6d3a0..a92ffe8c69757 100644 --- a/docs/pages/enterprise/sso.mdx +++ b/docs/pages/enterprise/sso.mdx @@ -94,7 +94,7 @@ To configure SSO, a Teleport administrator must: a YAML file (like `connector.yaml`). - Create the connector using `tctl create connector.yaml`. -An example setting the default authentication type as `saml` or `oidc`: +To set the default authentication type as `saml` or `oidc`, either modify your Auth Service configuration file orcreate a `cluster_auth_preference` resource. Update `/etc/teleport.yaml` in the `auth_service` section and restart the `teleport` daemon. From debb64606752769d787c3957bf4da0e680688cab Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Tue, 10 May 2022 10:16:09 -0700 Subject: [PATCH 09/27] Modified pre-req to show required enterprise or cloud installed with scope --- docs/pages/enterprise/sso/adfs.mdx | 1 - docs/pages/enterprise/sso/azuread.mdx | 1 - docs/pages/enterprise/sso/gitlab.mdx | 1 - docs/pages/enterprise/sso/oidc.mdx | 1 - docs/pages/enterprise/sso/okta.mdx | 1 - docs/pages/enterprise/sso/one-login.mdx | 1 - docs/pages/includes/enterprise/ent-user-prereqs.mdx | 3 +++ 7 files changed, 3 insertions(+), 6 deletions(-) diff --git a/docs/pages/enterprise/sso/adfs.mdx b/docs/pages/enterprise/sso/adfs.mdx index c71dbe33ae2aa..26d3236c21208 100644 --- a/docs/pages/enterprise/sso/adfs.mdx +++ b/docs/pages/enterprise/sso/adfs.mdx @@ -36,7 +36,6 @@ like: ## Prerequisites -- Either an Enterprise version of Teleport (downloaded via the [Enterprise dashboard](https://dashboard.gravitational.com/web/login)) or a Teleport Cloud account (sign up for a [free trial](https://goteleport.com/signup)). - ADFS installation with Admin access with users assigned to at least two groups. (!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) diff --git a/docs/pages/enterprise/sso/azuread.mdx b/docs/pages/enterprise/sso/azuread.mdx index 1f3adc228253e..3efdba5dcfae0 100644 --- a/docs/pages/enterprise/sso/azuread.mdx +++ b/docs/pages/enterprise/sso/azuread.mdx @@ -35,7 +35,6 @@ The following steps configure an example SAML authentication connector matching Before you get started you’ll need: -- Either an Enterprise version of Teleport (downloaded via the [Enterprise dashboard](https://dashboard.gravitational.com/web/login)) or a Teleport Cloud account (sign up for a [free trial](https://goteleport.com/signup/)). - An Azure AD admin account with access to creating non-gallery applications (P2 License) - To register one or more users in the directory - To create at least two security groups in Azure AD and assign one or more users to each group diff --git a/docs/pages/enterprise/sso/gitlab.mdx b/docs/pages/enterprise/sso/gitlab.mdx index c4c75cf6ef4e3..fb5570c5ad61e 100644 --- a/docs/pages/enterprise/sso/gitlab.mdx +++ b/docs/pages/enterprise/sso/gitlab.mdx @@ -36,7 +36,6 @@ like: ## Prerequisites -- Either an Enterprise version of Teleport (downloaded via the [Enterprise dashboard](https://dashboard.gravitational.com/web/login)) or a Teleport Cloud account (sign up for a [free trial](https://goteleport.com/signup/)). - At least two groups in GitLab with users assigned. (!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) diff --git a/docs/pages/enterprise/sso/oidc.mdx b/docs/pages/enterprise/sso/oidc.mdx index df6f6c2d11e41..e9276f55ace61 100644 --- a/docs/pages/enterprise/sso/oidc.mdx +++ b/docs/pages/enterprise/sso/oidc.mdx @@ -34,7 +34,6 @@ administrators to define policies like: ## Prerequisites -- Either an Enterprise version of Teleport (downloaded via the [Enterprise dashboard](https://dashboard.gravitational.com/web/login)) or a Teleport Cloud account (sign up for a [free trial](https://goteleport.com/signup)). - Admin access to the SSO/IdP being integrated. - Users with groups/roles assigned. diff --git a/docs/pages/enterprise/sso/okta.mdx b/docs/pages/enterprise/sso/okta.mdx index a2e8a76e11747..5d0404082001b 100644 --- a/docs/pages/enterprise/sso/okta.mdx +++ b/docs/pages/enterprise/sso/okta.mdx @@ -36,7 +36,6 @@ like: ## Prerequisites -- Either an Enterprise version of Teleport (downloaded via the [Enterprise dashboard](https://dashboard.gravitational.com/web/login)) or a Teleport Cloud account (sign up for a [free trial](https://goteleport.com/signup)). - Okta Account with Admin access with users and 2 groups. (!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) diff --git a/docs/pages/enterprise/sso/one-login.mdx b/docs/pages/enterprise/sso/one-login.mdx index 78e9e52d3b254..b9105137cf174 100644 --- a/docs/pages/enterprise/sso/one-login.mdx +++ b/docs/pages/enterprise/sso/one-login.mdx @@ -34,7 +34,6 @@ like: ## Prerequisites -- Either an Enterprise version of Teleport (downloaded via the [Enterprise dashboard](https://dashboard.gravitational.com/web/login)) or a Teleport Cloud account (sign up for a [free trial](https://goteleport.com/signup)). - One Login Account with Admin access with users assigned to at least two groups. (!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) diff --git a/docs/pages/includes/enterprise/ent-user-prereqs.mdx b/docs/pages/includes/enterprise/ent-user-prereqs.mdx index d4cacb036bf1c..ec862bcd06a6f 100644 --- a/docs/pages/includes/enterprise/ent-user-prereqs.mdx +++ b/docs/pages/includes/enterprise/ent-user-prereqs.mdx @@ -2,6 +2,8 @@ +- Installed Enterprise version of Teleport (downloaded via the [Enterprise dashboard](https://dashboard.gravitational.com/web/login)). + - Access to the machine hosting the Auth Service - Maintaining SAML/OIDC auth connectors via the desktop CLI requires enterprise `tctl` admin tool version >= (=teleport.version=), @@ -17,6 +19,7 @@ +- Teleport Cloud account (sign up for a [free trial](https://goteleport.com/signup)). - The `tctl` admin client version >= (=cloud.version=). From 990028d97e313e855d8ad1ebfc3014b3a12ae4e4 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Tue, 10 May 2022 10:18:39 -0700 Subject: [PATCH 10/27] verbiage Co-authored-by: Paul Gottschling --- docs/pages/includes/enterprise/ent-user-prereqs.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/includes/enterprise/ent-user-prereqs.mdx b/docs/pages/includes/enterprise/ent-user-prereqs.mdx index ec862bcd06a6f..6b9c8a40447cc 100644 --- a/docs/pages/includes/enterprise/ent-user-prereqs.mdx +++ b/docs/pages/includes/enterprise/ent-user-prereqs.mdx @@ -6,7 +6,7 @@ - Access to the machine hosting the Auth Service -- Maintaining SAML/OIDC auth connectors via the desktop CLI requires enterprise `tctl` admin tool version >= (=teleport.version=), +- Maintaining SAML/OIDC auth connectors via the desktop CLI requires the enterprise `tctl` admin tool version >= (=teleport.version=), which you can download by visiting the [customer portal](https://dashboard.gravitational.com/web/login). From 7dc70419b2be5c27ab52201bdb29d3cbf439a7ca Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Tue, 10 May 2022 11:15:13 -0700 Subject: [PATCH 11/27] Updated github to match other ssos. tctl desktop connection --- docs/pages/enterprise/sso/adfs.mdx | 2 +- docs/pages/enterprise/sso/azuread.mdx | 2 +- docs/pages/enterprise/sso/gitlab.mdx | 2 +- .../pages/enterprise/sso/google-workspace.mdx | 2 +- docs/pages/enterprise/sso/oidc.mdx | 2 +- docs/pages/enterprise/sso/okta.mdx | 2 +- docs/pages/enterprise/sso/one-login.mdx | 2 +- docs/pages/includes/edition-prereqs-tabs.mdx | 29 ++++++-------- .../includes/enterprise/ent-user-prereqs.mdx | 8 ++-- docs/pages/includes/sso/tctlconnection.mdx | 40 +++++++++++++++++++ docs/pages/setup/admin/github-sso.mdx | 2 +- 11 files changed, 63 insertions(+), 30 deletions(-) create mode 100644 docs/pages/includes/sso/tctlconnection.mdx diff --git a/docs/pages/enterprise/sso/adfs.mdx b/docs/pages/enterprise/sso/adfs.mdx index 26d3236c21208..ea55881ac0878 100644 --- a/docs/pages/enterprise/sso/adfs.mdx +++ b/docs/pages/enterprise/sso/adfs.mdx @@ -40,7 +40,7 @@ like: (!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) -(!docs/pages/includes/tctl.mdx!) +(!docs/pages/includes/sso/tctlconnection.mdx!) (!docs/pages/includes/enterprise/samlauthentication.mdx!) diff --git a/docs/pages/enterprise/sso/azuread.mdx b/docs/pages/enterprise/sso/azuread.mdx index 3efdba5dcfae0..04cd6351a2451 100644 --- a/docs/pages/enterprise/sso/azuread.mdx +++ b/docs/pages/enterprise/sso/azuread.mdx @@ -41,7 +41,7 @@ Before you get started you’ll need: (!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) -(!docs/pages/includes/tctl.mdx!) +(!docs/pages/includes/sso/tctlconnection.mdx!) (!docs/pages/includes/enterprise/samlauthentication.mdx!) diff --git a/docs/pages/enterprise/sso/gitlab.mdx b/docs/pages/enterprise/sso/gitlab.mdx index fb5570c5ad61e..f6a8ff67ac8a6 100644 --- a/docs/pages/enterprise/sso/gitlab.mdx +++ b/docs/pages/enterprise/sso/gitlab.mdx @@ -40,7 +40,7 @@ like: (!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) -(!docs/pages/includes/tctl.mdx!) +(!docs/pages/includes/sso/tctlconnection.mdx!) ## Enable default OIDC authentication diff --git a/docs/pages/enterprise/sso/google-workspace.mdx b/docs/pages/enterprise/sso/google-workspace.mdx index 476748dfef339..0acf55d591c60 100644 --- a/docs/pages/enterprise/sso/google-workspace.mdx +++ b/docs/pages/enterprise/sso/google-workspace.mdx @@ -43,7 +43,7 @@ Before you get started you’ll need: (!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) -(!docs/pages/includes/tctl.mdx!) +(!docs/pages/includes/sso/tctlconnection.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 e9276f55ace61..49e7f73f8ced0 100644 --- a/docs/pages/enterprise/sso/oidc.mdx +++ b/docs/pages/enterprise/sso/oidc.mdx @@ -39,7 +39,7 @@ administrators to define policies like: (!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) -(!docs/pages/includes/tctl.mdx!) +(!docs/pages/includes/sso/tctlconnection.mdx!) ## Enable default OIDC authentication diff --git a/docs/pages/enterprise/sso/okta.mdx b/docs/pages/enterprise/sso/okta.mdx index 5d0404082001b..98abe8bfc9f70 100644 --- a/docs/pages/enterprise/sso/okta.mdx +++ b/docs/pages/enterprise/sso/okta.mdx @@ -40,7 +40,7 @@ like: (!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) -(!docs/pages/includes/tctl.mdx!) +(!docs/pages/includes/sso/tctlconnection.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 b9105137cf174..89af44d9ba04d 100644 --- a/docs/pages/enterprise/sso/one-login.mdx +++ b/docs/pages/enterprise/sso/one-login.mdx @@ -38,7 +38,7 @@ like: (!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) -(!docs/pages/includes/tctl.mdx!) +(!docs/pages/includes/sso/tctlconnection.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 701d476efcbc0..dad7eca410482 100644 --- a/docs/pages/includes/edition-prereqs-tabs.mdx +++ b/docs/pages/includes/edition-prereqs-tabs.mdx @@ -21,42 +21,37 @@ files in partials, this partial uses relative URL paths instead. See [Installation](/docs/installation.mdx) for details. +- Teleport role with access to maintaining `saml` and `oidc` resources. This is available in the default `editor` role. + + scope={["enterprise"]} label="Self-Hosted"> -- A running Teleport cluster. For details on how to set this up, see our Enterprise - [Getting Started](/docs/enterprise/getting-started) guide. +- 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=), - which you can download by visiting the +- Enterprise `tctl` admin tool version >= (=teleport.version=) installed on Desktop 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 role with access to maintaining `saml` and `oidc` resources. This is available in the default `editor` role. + +- Teleport Cloud account (sign up for a [free trial](https://goteleport.com/signup)). -- A Teleport Cloud account. If you do not have one, visit the - [sign up page](https://goteleport.com/signup/) to begin your free trial. +- The `tctl` admin client version >= (=cloud.version=). -- The `tctl` admin tool and `tsh` client tool version >= (=cloud.version=). - To download these tools, visit the [Downloads](/docs/cloud/downloads) page. + You can download this from [Teleport Cloud Downloads](/docs/cloud/downloads). ```code $ tctl version # Teleport v(=cloud.version=) go(=teleport.golang=) - - $ tsh version - # Teleport v(=cloud.version=) go(=teleport.golang=) ``` +- Teleport role with access to maintaining `saml` and `oidc` resources. This is available in the default `editor` role. - \ 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 index 6b9c8a40447cc..4cf856794d568 100644 --- a/docs/pages/includes/enterprise/ent-user-prereqs.mdx +++ b/docs/pages/includes/enterprise/ent-user-prereqs.mdx @@ -4,16 +4,13 @@ - Installed Enterprise version of Teleport (downloaded via the [Enterprise dashboard](https://dashboard.gravitational.com/web/login)). -- Access to the machine hosting the Auth Service - -- Maintaining SAML/OIDC auth connectors via the desktop CLI requires the enterprise `tctl` admin tool version >= (=teleport.version=), - which you can download by visiting the +- Enterprise `tctl` admin tool version >= (=teleport.version=) installed on Desktop 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=) ``` +- Teleport role with access to maintaining `saml` and `oidc` resources. This is available in the default `editor` role. @@ -29,6 +26,7 @@ $ tctl version # Teleport v(=cloud.version=) go(=teleport.golang=) ``` +- Teleport role with access to maintaining `saml` and `oidc` resources. This is available in the default `editor` role. diff --git a/docs/pages/includes/sso/tctlconnection.mdx b/docs/pages/includes/sso/tctlconnection.mdx new file mode 100644 index 0000000000000..c0d0e298001ff --- /dev/null +++ b/docs/pages/includes/sso/tctlconnection.mdx @@ -0,0 +1,40 @@ +
+ +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 cd0b49a0d7dfc..d617e6365be64 100644 --- a/docs/pages/setup/admin/github-sso.mdx +++ b/docs/pages/setup/admin/github-sso.mdx @@ -14,7 +14,7 @@ Teleport. (!docs/pages/includes/edition-prereqs-tabs.mdx!) -(!docs/pages/includes/tctl.mdx!) +(!docs/pages/includes/sso/tctlconnection.mdx!) ## Step 1/3. Create a GitHub OAuth app From 485e0109b94ccf3c8d9b823592171456bd468381 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Tue, 10 May 2022 11:30:06 -0700 Subject: [PATCH 12/27] Makes consistent across github and ent ssos --- docs/pages/includes/edition-prereqs-tabs.mdx | 12 ++++++++---- docs/pages/includes/enterprise/ent-user-prereqs.mdx | 6 ++++-- 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/docs/pages/includes/edition-prereqs-tabs.mdx b/docs/pages/includes/edition-prereqs-tabs.mdx index dad7eca410482..65b991d1f4791 100644 --- a/docs/pages/includes/edition-prereqs-tabs.mdx +++ b/docs/pages/includes/edition-prereqs-tabs.mdx @@ -21,21 +21,25 @@ files in partials, this partial uses relative URL paths instead. See [Installation](/docs/installation.mdx) for details. -- Teleport role with access to maintaining `saml` and `oidc` resources. This is available in the default `editor` role. +- Maintain via the `tctl` enterprise admin tool via the Desktop (recommended) or have administrative access on the Teleport auth service machine. + +- Teleport role with access to maintaining `github` resources for using `tctl` from the Desktop. This is available in the default `editor` role. + scope={["enterprise"]} label="Enterprise"> - Installed Enterprise version of Teleport (downloaded via the [Enterprise dashboard](https://dashboard.gravitational.com/web/login)). -- Enterprise `tctl` admin tool version >= (=teleport.version=) installed on Desktop which you can download by visiting the +- Maintain via the `tctl` enterprise admin tool via the Desktop (recommended) or have administrative access on the Teleport auth service machine. + +- For Desktop `tctl` interactions have the Enterprise `tctl` admin tool version >= (=teleport.version=) installed 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=) ``` -- Teleport role with access to maintaining `saml` and `oidc` resources. This is available in the default `editor` role. + Teleport role with access to maintaining `saml` and `oidc` resources. This is available in the default `editor` role. diff --git a/docs/pages/includes/enterprise/ent-user-prereqs.mdx b/docs/pages/includes/enterprise/ent-user-prereqs.mdx index 4cf856794d568..ba5e4a68b9888 100644 --- a/docs/pages/includes/enterprise/ent-user-prereqs.mdx +++ b/docs/pages/includes/enterprise/ent-user-prereqs.mdx @@ -4,13 +4,15 @@ - Installed Enterprise version of Teleport (downloaded via the [Enterprise dashboard](https://dashboard.gravitational.com/web/login)). -- Enterprise `tctl` admin tool version >= (=teleport.version=) installed on Desktop which you can download by visiting the +- Maintain via the `tctl` enterprise admin tool via the Desktop (recommended) or have administrative access on the Teleport auth service machine. + +- For Desktop `tctl` interactions have the Enterprise `tctl` admin tool version >= (=teleport.version=) installed 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=) ``` -- Teleport role with access to maintaining `saml` and `oidc` resources. This is available in the default `editor` role. + Teleport role with access to maintaining `saml` and `oidc` resources. This is available in the default `editor` role. From dfa0a9966623d86772b9c3a6fb28100dcdd62059 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Tue, 10 May 2022 11:52:04 -0700 Subject: [PATCH 13/27] lint fixes --- docs/pages/includes/edition-prereqs-tabs.mdx | 5 ----- docs/pages/includes/enterprise/ent-user-prereqs.mdx | 4 ---- 2 files changed, 9 deletions(-) diff --git a/docs/pages/includes/edition-prereqs-tabs.mdx b/docs/pages/includes/edition-prereqs-tabs.mdx index 65b991d1f4791..3c7dede05bdd8 100644 --- a/docs/pages/includes/edition-prereqs-tabs.mdx +++ b/docs/pages/includes/edition-prereqs-tabs.mdx @@ -28,11 +28,8 @@ 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)). - - Maintain via the `tctl` enterprise admin tool via the Desktop (recommended) or have administrative access on the Teleport auth service machine. - - For Desktop `tctl` interactions have the Enterprise `tctl` admin tool version >= (=teleport.version=) installed which you can download by visiting the [customer portal](https://dashboard.gravitational.com/web/login). ```code @@ -40,9 +37,7 @@ files in partials, this partial uses relative URL paths instead. # Teleport v(=teleport.version=) go(=teleport.golang=) ``` Teleport role with access to maintaining `saml` and `oidc` resources. This is available in the default `editor` role. - - - Teleport Cloud account (sign up for a [free trial](https://goteleport.com/signup)). diff --git a/docs/pages/includes/enterprise/ent-user-prereqs.mdx b/docs/pages/includes/enterprise/ent-user-prereqs.mdx index ba5e4a68b9888..6981d26d2b9a3 100644 --- a/docs/pages/includes/enterprise/ent-user-prereqs.mdx +++ b/docs/pages/includes/enterprise/ent-user-prereqs.mdx @@ -1,11 +1,8 @@ - - Installed Enterprise version of Teleport (downloaded via the [Enterprise dashboard](https://dashboard.gravitational.com/web/login)). - - Maintain via the `tctl` enterprise admin tool via the Desktop (recommended) or have administrative access on the Teleport auth service machine. - - For Desktop `tctl` interactions have the Enterprise `tctl` admin tool version >= (=teleport.version=) installed which you can download by visiting the [customer portal](https://dashboard.gravitational.com/web/login). ```code @@ -13,7 +10,6 @@ # Teleport v(=teleport.version=) go(=teleport.golang=) ``` Teleport role with access to maintaining `saml` and `oidc` resources. This is available in the default `editor` role. - Date: Thu, 12 May 2022 13:29:14 -0700 Subject: [PATCH 14/27] verbiage update Co-authored-by: Paul Gottschling --- docs/pages/enterprise/sso.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/enterprise/sso.mdx b/docs/pages/enterprise/sso.mdx index a92ffe8c69757..218b9e5e5c612 100644 --- a/docs/pages/enterprise/sso.mdx +++ b/docs/pages/enterprise/sso.mdx @@ -94,7 +94,7 @@ To configure SSO, a Teleport administrator must: 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 orcreate 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. From bd450ec3bc695ea809de725f7874ba2bb98501ca Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Thu, 12 May 2022 13:30:14 -0700 Subject: [PATCH 15/27] verbiage update for adfs prereq Co-authored-by: Paul Gottschling --- docs/pages/enterprise/sso/adfs.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/enterprise/sso/adfs.mdx b/docs/pages/enterprise/sso/adfs.mdx index ea55881ac0878..16eff4a6009b4 100644 --- a/docs/pages/enterprise/sso/adfs.mdx +++ b/docs/pages/enterprise/sso/adfs.mdx @@ -36,7 +36,7 @@ like: ## Prerequisites -- ADFS installation with Admin access with users assigned to at least two groups. +- ADFS installation with Admin access and users assigned to at least two groups. (!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) From f6b581123fb3d93ddb03604667e4ba5ef6959662 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Thu, 12 May 2022 13:31:03 -0700 Subject: [PATCH 16/27] okta prereq verbiage updated Co-authored-by: Paul Gottschling --- docs/pages/enterprise/sso/okta.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/enterprise/sso/okta.mdx b/docs/pages/enterprise/sso/okta.mdx index 98abe8bfc9f70..70992b02fa15e 100644 --- a/docs/pages/enterprise/sso/okta.mdx +++ b/docs/pages/enterprise/sso/okta.mdx @@ -36,7 +36,7 @@ like: ## Prerequisites -- Okta Account with Admin access with users and 2 groups. +- Okta account with admin access. Your account must include users and at least two groups. (!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) From 7da5a6a509490cf1f62c08a3907ccba491e62ab0 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Thu, 12 May 2022 13:35:32 -0700 Subject: [PATCH 17/27] remove spaces Co-authored-by: Paul Gottschling --- docs/pages/includes/enterprise/ent-user-prereqs.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/includes/enterprise/ent-user-prereqs.mdx b/docs/pages/includes/enterprise/ent-user-prereqs.mdx index 6981d26d2b9a3..cf84ddf631e3b 100644 --- a/docs/pages/includes/enterprise/ent-user-prereqs.mdx +++ b/docs/pages/includes/enterprise/ent-user-prereqs.mdx @@ -24,7 +24,7 @@ $ tctl version # Teleport v(=cloud.version=) go(=teleport.golang=) ``` -- Teleport role with access to maintaining `saml` and `oidc` resources. This is available in the default `editor` role. +- Teleport role with access to maintaining `saml` and `oidc` resources. This is available in the default `editor` role. From 20393f56fdb5ee2ed611a21d6f1aae3459a07c88 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Thu, 12 May 2022 13:38:54 -0700 Subject: [PATCH 18/27] verbiage change Co-authored-by: Paul Gottschling --- docs/pages/enterprise/sso/one-login.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/enterprise/sso/one-login.mdx b/docs/pages/enterprise/sso/one-login.mdx index 89af44d9ba04d..9e158eadd5c84 100644 --- a/docs/pages/enterprise/sso/one-login.mdx +++ b/docs/pages/enterprise/sso/one-login.mdx @@ -34,7 +34,7 @@ like: ## Prerequisites -- One Login Account with Admin access with users assigned to at least two groups. +- One Login account with admin access and users assigned to at least two groups. (!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) From d28136fd8d731a149a59cb3131fa1c6393a3a7a9 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Thu, 12 May 2022 13:42:13 -0700 Subject: [PATCH 19/27] Corrected OIDc prereq and fixed bullet in include --- docs/pages/enterprise/sso/oidc.mdx | 3 +-- docs/pages/includes/enterprise/ent-user-prereqs.mdx | 3 +-- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/pages/enterprise/sso/oidc.mdx b/docs/pages/enterprise/sso/oidc.mdx index 49e7f73f8ced0..2a1cb601ce903 100644 --- a/docs/pages/enterprise/sso/oidc.mdx +++ b/docs/pages/enterprise/sso/oidc.mdx @@ -34,8 +34,7 @@ administrators to define policies like: ## Prerequisites -- Admin access to the SSO/IdP being integrated. -- Users with groups/roles assigned. +- Admin access to the SSO/IdP being integrated with users assigned to groups/roles. (!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) diff --git a/docs/pages/includes/enterprise/ent-user-prereqs.mdx b/docs/pages/includes/enterprise/ent-user-prereqs.mdx index cf84ddf631e3b..4db69908cef57 100644 --- a/docs/pages/includes/enterprise/ent-user-prereqs.mdx +++ b/docs/pages/includes/enterprise/ent-user-prereqs.mdx @@ -9,7 +9,7 @@ $ tctl version # Teleport v(=teleport.version=) go(=teleport.golang=) ``` - Teleport role with access to maintaining `saml` and `oidc` resources. This is available in the default `editor` role. +- Teleport role with access to maintaining `saml` and `oidc` resources. This is available in the default `editor` role. From e8de343a85ad5fac980b750ba450a3b315d45975 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Wed, 18 May 2022 08:34:30 -0400 Subject: [PATCH 20/27] Removed specific github content from editition-prereqs-tabs and moved to github-sso --- docs/pages/includes/edition-prereqs-tabs.mdx | 2 -- docs/pages/setup/admin/github-sso.mdx | 2 ++ 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/pages/includes/edition-prereqs-tabs.mdx b/docs/pages/includes/edition-prereqs-tabs.mdx index 3c7dede05bdd8..eb622010481a3 100644 --- a/docs/pages/includes/edition-prereqs-tabs.mdx +++ b/docs/pages/includes/edition-prereqs-tabs.mdx @@ -23,8 +23,6 @@ files in partials, this partial uses relative URL paths instead. - Maintain via the `tctl` enterprise admin tool via the Desktop (recommended) or have administrative access on the Teleport auth service machine. -- Teleport role with access to maintaining `github` resources for using `tctl` from the Desktop. This is available in the default `editor` role. - diff --git a/docs/pages/setup/admin/github-sso.mdx b/docs/pages/setup/admin/github-sso.mdx index d617e6365be64..ef7f9efe173ad 100644 --- a/docs/pages/setup/admin/github-sso.mdx +++ b/docs/pages/setup/admin/github-sso.mdx @@ -12,6 +12,8 @@ Teleport. - A GitHub organization with at least one team. +- Teleport role with access to maintaining `github` resources for using `tctl` from the Desktop. This is available in the default `editor` role. + (!docs/pages/includes/edition-prereqs-tabs.mdx!) (!docs/pages/includes/sso/tctlconnection.mdx!) From d1556f904162c446988c8f22271ad5fdf975b884 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Wed, 18 May 2022 08:38:06 -0400 Subject: [PATCH 21/27] verbiage change Co-authored-by: Paul Gottschling --- docs/pages/includes/edition-prereqs-tabs.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/pages/includes/edition-prereqs-tabs.mdx b/docs/pages/includes/edition-prereqs-tabs.mdx index eb622010481a3..7bc76ce8302c5 100644 --- a/docs/pages/includes/edition-prereqs-tabs.mdx +++ b/docs/pages/includes/edition-prereqs-tabs.mdx @@ -28,7 +28,8 @@ files in partials, this partial uses relative URL paths instead. scope={["enterprise"]} label="Enterprise"> - Installed Enterprise version of Teleport (downloaded via the [Enterprise dashboard](https://dashboard.gravitational.com/web/login)). - Maintain via the `tctl` enterprise admin tool via the Desktop (recommended) or have administrative access on the Teleport auth service machine. -- For Desktop `tctl` interactions have the Enterprise `tctl` admin tool version >= (=teleport.version=) installed which you can download by visiting the +- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=), installed on your local machine. +You can download these by visiting the [customer portal](https://dashboard.gravitational.com/web/login). ```code $ tctl version From 27bb418e760dcec176dfd92ecb83d1a8386cb5fd Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Sun, 22 May 2022 09:46:43 -0400 Subject: [PATCH 22/27] Addressed review items --- docs/pages/enterprise/sso/adfs.mdx | 2 ++ docs/pages/enterprise/sso/azuread.mdx | 2 ++ docs/pages/enterprise/sso/gitlab.mdx | 1 + docs/pages/enterprise/sso/google-workspace.mdx | 1 + docs/pages/enterprise/sso/oidc.mdx | 1 + docs/pages/enterprise/sso/okta.mdx | 1 + docs/pages/enterprise/sso/one-login.mdx | 1 + docs/pages/includes/edition-prereqs-tabs.mdx | 10 ++-------- docs/pages/includes/enterprise/ent-user-prereqs.mdx | 6 +----- 9 files changed, 12 insertions(+), 13 deletions(-) diff --git a/docs/pages/enterprise/sso/adfs.mdx b/docs/pages/enterprise/sso/adfs.mdx index 16eff4a6009b4..d75bbea8fc6ba 100644 --- a/docs/pages/enterprise/sso/adfs.mdx +++ b/docs/pages/enterprise/sso/adfs.mdx @@ -38,6 +38,8 @@ like: - ADFS installation 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/sso/tctlconnection.mdx!) diff --git a/docs/pages/enterprise/sso/azuread.mdx b/docs/pages/enterprise/sso/azuread.mdx index 04cd6351a2451..4f5fe1c53594c 100644 --- a/docs/pages/enterprise/sso/azuread.mdx +++ b/docs/pages/enterprise/sso/azuread.mdx @@ -38,6 +38,8 @@ Before you get started you’ll need: - An Azure AD admin account with access to creating non-gallery applications (P2 License) - To register one or more users in the directory - 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/enterprise/ent-user-prereqs.mdx!) diff --git a/docs/pages/enterprise/sso/gitlab.mdx b/docs/pages/enterprise/sso/gitlab.mdx index f6a8ff67ac8a6..c3e35bfcd3697 100644 --- a/docs/pages/enterprise/sso/gitlab.mdx +++ b/docs/pages/enterprise/sso/gitlab.mdx @@ -37,6 +37,7 @@ like: ## Prerequisites - 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!) diff --git a/docs/pages/enterprise/sso/google-workspace.mdx b/docs/pages/enterprise/sso/google-workspace.mdx index 0acf55d591c60..c15b094585934 100644 --- a/docs/pages/enterprise/sso/google-workspace.mdx +++ b/docs/pages/enterprise/sso/google-workspace.mdx @@ -40,6 +40,7 @@ Before you get started you’ll need: - A Google Workspace super administrator account. We recommend setting up a separate super admin account with 2FA as opposed to granting your daily user super admin privileges. - Ability to create a Google Cloud project, which requires signing up for Google Cloud. Note that this guide will not require using any paid Google Cloud services. - 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!) diff --git a/docs/pages/enterprise/sso/oidc.mdx b/docs/pages/enterprise/sso/oidc.mdx index 2a1cb601ce903..592e4e80f27e6 100644 --- a/docs/pages/enterprise/sso/oidc.mdx +++ b/docs/pages/enterprise/sso/oidc.mdx @@ -35,6 +35,7 @@ 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. (!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) diff --git a/docs/pages/enterprise/sso/okta.mdx b/docs/pages/enterprise/sso/okta.mdx index 70992b02fa15e..09dea5b3708bb 100644 --- a/docs/pages/enterprise/sso/okta.mdx +++ b/docs/pages/enterprise/sso/okta.mdx @@ -37,6 +37,7 @@ like: ## Prerequisites - 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!) diff --git a/docs/pages/enterprise/sso/one-login.mdx b/docs/pages/enterprise/sso/one-login.mdx index 9e158eadd5c84..83fecd96d0cab 100644 --- a/docs/pages/enterprise/sso/one-login.mdx +++ b/docs/pages/enterprise/sso/one-login.mdx @@ -35,6 +35,7 @@ like: ## Prerequisites - 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!) diff --git a/docs/pages/includes/edition-prereqs-tabs.mdx b/docs/pages/includes/edition-prereqs-tabs.mdx index 7bc76ce8302c5..010ac98286210 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=). +- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=) on a Desktop or administrative access on the Teleport Auth Service machine. ```code $ tctl version @@ -21,21 +21,17 @@ files in partials, this partial uses relative URL paths instead. See [Installation](/docs/installation.mdx) for details. -- Maintain via the `tctl` enterprise admin tool via the Desktop (recommended) or have administrative access on the Teleport auth service machine. - - Installed Enterprise version of Teleport (downloaded via the [Enterprise dashboard](https://dashboard.gravitational.com/web/login)). -- Maintain via the `tctl` enterprise admin tool via the Desktop (recommended) or have administrative access on the Teleport auth service machine. -- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=), installed on your local machine. +- 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=) ``` - Teleport role with access to maintaining `saml` and `oidc` resources. This is available in the default `editor` role. @@ -49,7 +45,5 @@ You can download these by visiting the $ tctl version # Teleport v(=cloud.version=) go(=teleport.golang=) ``` -- Teleport role with access to maintaining `saml` and `oidc` resources. This is available in the default `editor` role. - diff --git a/docs/pages/includes/enterprise/ent-user-prereqs.mdx b/docs/pages/includes/enterprise/ent-user-prereqs.mdx index 4db69908cef57..9ef86716ffd4d 100644 --- a/docs/pages/includes/enterprise/ent-user-prereqs.mdx +++ b/docs/pages/includes/enterprise/ent-user-prereqs.mdx @@ -2,14 +2,11 @@ - Installed Enterprise version of Teleport (downloaded via the [Enterprise dashboard](https://dashboard.gravitational.com/web/login)). -- Maintain via the `tctl` enterprise admin tool via the Desktop (recommended) or have administrative access on the Teleport auth service machine. -- For Desktop `tctl` interactions have the Enterprise `tctl` admin tool version >= (=teleport.version=) installed which you can download by visiting the - [customer portal](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=) ``` -- Teleport role with access to maintaining `saml` and `oidc` resources. This is available in the default `editor` role. From 769e0fdde4a71c5691d8f596557bf2087b65e30c Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Sun, 22 May 2022 09:55:55 -0400 Subject: [PATCH 23/27] Combined tctl instructions --- docs/pages/enterprise/sso/adfs.mdx | 2 -- docs/pages/enterprise/sso/azuread.mdx | 2 -- .../pages/enterprise/sso/google-workspace.mdx | 2 -- docs/pages/enterprise/sso/oidc.mdx | 2 -- docs/pages/enterprise/sso/okta.mdx | 2 -- docs/pages/enterprise/sso/one-login.mdx | 2 -- .../includes/enterprise/ent-user-prereqs.mdx | 25 +++++++++++++++---- 7 files changed, 20 insertions(+), 17 deletions(-) diff --git a/docs/pages/enterprise/sso/adfs.mdx b/docs/pages/enterprise/sso/adfs.mdx index d75bbea8fc6ba..69e33c17f26df 100644 --- a/docs/pages/enterprise/sso/adfs.mdx +++ b/docs/pages/enterprise/sso/adfs.mdx @@ -42,8 +42,6 @@ like: (!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) -(!docs/pages/includes/sso/tctlconnection.mdx!) - (!docs/pages/includes/enterprise/samlauthentication.mdx!) ## Configure ADFS diff --git a/docs/pages/enterprise/sso/azuread.mdx b/docs/pages/enterprise/sso/azuread.mdx index 4f5fe1c53594c..c0e6c989d95fe 100644 --- a/docs/pages/enterprise/sso/azuread.mdx +++ b/docs/pages/enterprise/sso/azuread.mdx @@ -43,8 +43,6 @@ Before you get started you’ll need: (!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) -(!docs/pages/includes/sso/tctlconnection.mdx!) - (!docs/pages/includes/enterprise/samlauthentication.mdx!) ## Configure Azure AD diff --git a/docs/pages/enterprise/sso/google-workspace.mdx b/docs/pages/enterprise/sso/google-workspace.mdx index c15b094585934..00ea3880a1704 100644 --- a/docs/pages/enterprise/sso/google-workspace.mdx +++ b/docs/pages/enterprise/sso/google-workspace.mdx @@ -44,8 +44,6 @@ Before you get started you’ll need: (!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) -(!docs/pages/includes/sso/tctlconnection.mdx!) - ## Step 1/4. Enable default OIDC authentication (!docs/pages/includes/enterprise/oidcauthentication.mdx!) diff --git a/docs/pages/enterprise/sso/oidc.mdx b/docs/pages/enterprise/sso/oidc.mdx index 592e4e80f27e6..79c2083e443db 100644 --- a/docs/pages/enterprise/sso/oidc.mdx +++ b/docs/pages/enterprise/sso/oidc.mdx @@ -39,8 +39,6 @@ administrators to define policies like: (!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) -(!docs/pages/includes/sso/tctlconnection.mdx!) - ## Enable default OIDC authentication (!docs/pages/includes/enterprise/oidcauthentication.mdx!) diff --git a/docs/pages/enterprise/sso/okta.mdx b/docs/pages/enterprise/sso/okta.mdx index 09dea5b3708bb..637c46a56b019 100644 --- a/docs/pages/enterprise/sso/okta.mdx +++ b/docs/pages/enterprise/sso/okta.mdx @@ -41,8 +41,6 @@ like: (!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) -(!docs/pages/includes/sso/tctlconnection.mdx!) - (!docs/pages/includes/enterprise/samlauthentication.mdx!) ## Configure Okta diff --git a/docs/pages/enterprise/sso/one-login.mdx b/docs/pages/enterprise/sso/one-login.mdx index 83fecd96d0cab..9c3fa3f46d4c5 100644 --- a/docs/pages/enterprise/sso/one-login.mdx +++ b/docs/pages/enterprise/sso/one-login.mdx @@ -39,8 +39,6 @@ like: (!docs/pages/includes/enterprise/ent-user-prereqs.mdx!) -(!docs/pages/includes/sso/tctlconnection.mdx!) - (!docs/pages/includes/enterprise/samlauthentication.mdx!) ## Configure Application diff --git a/docs/pages/includes/enterprise/ent-user-prereqs.mdx b/docs/pages/includes/enterprise/ent-user-prereqs.mdx index 9ef86716ffd4d..84edfb49fe185 100644 --- a/docs/pages/includes/enterprise/ent-user-prereqs.mdx +++ b/docs/pages/includes/enterprise/ent-user-prereqs.mdx @@ -7,8 +7,17 @@ $ 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)). @@ -17,9 +26,15 @@ You can download this from [Teleport Cloud Downloads](/docs/cloud/downloads). - ```code - $ tctl version - # Teleport v(=cloud.version=) go(=teleport.golang=) - ``` +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 +``` From c0ea4b623cf5dcd0556d3fb963ec9e715a5b7ebe Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Thu, 26 May 2022 18:10:50 -0400 Subject: [PATCH 24/27] Edit SSO guides (#12964) Edit the SSO introduction: - Add examples of all connectors so users don't need to find them in the examples directory - Add subheadings to the "Configuring SSO" section for clarity - Minor grammar/style edits Specific SSO guides: - Use the commercial-prereqs-tabs partial in Prerequisites sections, since this partial already exists, rather than ent-user-prereqs.mdx. This partial is more specific about requiring a running Teleport cluster, and links to the Getting Started guide for the Enterprise edition. - Minor tweaks to the scoped information shown in the samlauthentication.mdx and oidcauthentication.mdx partials - Restored the original wording of edition-prereqs-tabs.mdx, which is more specific about how to get started with a running Teleport cluster on different editions, and includes instructions for tsh. --- docs/pages/enterprise/sso.mdx | 166 ++++++++++++------ docs/pages/enterprise/sso/adfs.mdx | 4 +- docs/pages/enterprise/sso/azuread.mdx | 3 +- docs/pages/enterprise/sso/gitlab.mdx | 5 +- .../pages/enterprise/sso/google-workspace.mdx | 4 +- docs/pages/enterprise/sso/oidc.mdx | 6 +- docs/pages/enterprise/sso/okta.mdx | 4 +- docs/pages/enterprise/sso/one-login.mdx | 4 +- docs/pages/includes/edition-prereqs-tabs.mdx | 29 ++- .../includes/enterprise/ent-user-prereqs.mdx | 40 ----- .../enterprise/oidcauthentication.mdx | 16 +- .../enterprise/samlauthentication.mdx | 11 +- docs/pages/includes/sso/tctlconnection.mdx | 40 ----- docs/pages/setup/admin/github-sso.mdx | 2 +- examples/resources/okta-connector.yaml | 24 +++ 15 files changed, 197 insertions(+), 161 deletions(-) delete mode 100644 docs/pages/includes/enterprise/ent-user-prereqs.mdx delete mode 100644 docs/pages/includes/sso/tctlconnection.mdx create mode 100644 examples/resources/okta-connector.yaml diff --git a/docs/pages/enterprise/sso.mdx b/docs/pages/enterprise/sso.mdx index 218b9e5e5c612..3cdd6ccc1984c 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. ```code -# this command will automatically open the default web browser and take a user -# through the login process with an SSO provider: +# 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 +``` + +The command opens a browser window and shows a URL the user can visit in the +terminal to complete their SSO flow: -# output: +```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 -- 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`. +Before you can create an authentication connector, you must enable +authentication via that connector's protocol. + +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 69e33c17f26df..2fae5553d6d5a 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 c3e35bfcd3697..d0eb57efb2b1b 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 79c2083e443db..ea29a46334946 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 637c46a56b019..d748bab651589 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 9c3fa3f46d4c5..d5deb6fc282a2 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 ef7f9efe173ad..56fa37ba7104c 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 From d5d33818c1c3ae82accefe90c150748af9064cd8 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Wed, 1 Jun 2022 08:58:52 -0400 Subject: [PATCH 25/27] remove extra line --- docs/pages/enterprise/sso/adfs.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/pages/enterprise/sso/adfs.mdx b/docs/pages/enterprise/sso/adfs.mdx index 2fae5553d6d5a..cf941b28de241 100644 --- a/docs/pages/enterprise/sso/adfs.mdx +++ b/docs/pages/enterprise/sso/adfs.mdx @@ -37,7 +37,6 @@ like: ## Prerequisites - ADFS installation 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/commercial-prereqs-tabs.mdx!) From 61fc37ff848e7f0a87932805a7c0d82081b4f22c Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Wed, 1 Jun 2022 08:59:33 -0400 Subject: [PATCH 26/27] Remove extra line --- docs/pages/setup/admin/github-sso.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/pages/setup/admin/github-sso.mdx b/docs/pages/setup/admin/github-sso.mdx index 56fa37ba7104c..75abccaa5d20b 100644 --- a/docs/pages/setup/admin/github-sso.mdx +++ b/docs/pages/setup/admin/github-sso.mdx @@ -11,7 +11,6 @@ Teleport. ## Prerequisites - A GitHub organization with at least one team. - - Teleport role with access to maintaining `github` resources for using `tctl` from the Desktop. This is available in the default `editor` role. (!docs/pages/includes/edition-prereqs-tabs.mdx!) From 29939396790385f1d0f8ecfc3e28940f7634e17a Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Tue, 14 Jun 2022 13:08:49 -0400 Subject: [PATCH 27/27] Move the Okta connector into sso.mdx This was triggering a full build in the CI pipeline, which was causing issues merging this branch --- docs/pages/enterprise/sso.mdx | 26 ++++++++++++++++++++++++-- examples/resources/okta-connector.yaml | 24 ------------------------ 2 files changed, 24 insertions(+), 26 deletions(-) delete mode 100644 examples/resources/okta-connector.yaml diff --git a/docs/pages/enterprise/sso.mdx b/docs/pages/enterprise/sso.mdx index 3cdd6ccc1984c..bd36dd414ddf5 100644 --- a/docs/pages/enterprise/sso.mdx +++ b/docs/pages/enterprise/sso.mdx @@ -157,8 +157,30 @@ based on one of the following examples. ```yaml -(!/examples/resources/okta-connector.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: | + ``` diff --git a/examples/resources/okta-connector.yaml b/examples/resources/okta-connector.yaml deleted file mode 100644 index 3ba2582fbb388..0000000000000 --- a/examples/resources/okta-connector.yaml +++ /dev/null @@ -1,24 +0,0 @@ -# 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