From 373924706164acd04292182acb2902f18cdda367 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Wed, 4 May 2022 00:18:42 -0400 Subject: [PATCH 01/40] 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 b8fb272616152..96f8d499edf9d 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 c895f2a4bb1b1..0af9d8663ad61 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 bef81adb58881..2ce4d2dca5634 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 cbf272cdce3e1..08eba279f28fb 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 1f1c904316766..a26e2dad5bb0d 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 e5bee261f5afea2664bec0fdb0c34bec3dd4a96a Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Wed, 4 May 2022 00:27:49 -0400 Subject: [PATCH 02/40] 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 717c15c4465f5..8a0a25a6834c9 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 09327f225c3f78988355c6d45a2fe94a46f13848 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Thu, 5 May 2022 21:34:21 -0400 Subject: [PATCH 03/40] 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 8a0a25a6834c9..25b8a718b7465 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 036284eff9c082c06af5faa47350953979937a9f Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Thu, 5 May 2022 21:34:42 -0400 Subject: [PATCH 04/40] 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 25b8a718b7465..6c1636c35f9c8 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 71066cadf8857deffe91e9b0602a5adadf9962f7 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Thu, 5 May 2022 21:35:04 -0400 Subject: [PATCH 05/40] 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 6c1636c35f9c8..326f7cfa9b66a 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 5169ea5ba771505f918d51b7aeb68aa125ea5eb3 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Fri, 6 May 2022 22:27:21 -0400 Subject: [PATCH 06/40] 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 3dd5109d356ae54b037c0986b51f5db0e60e2096 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Fri, 6 May 2022 22:27:34 -0400 Subject: [PATCH 07/40] 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 88f451214db62eb9f66727a2d94798d1b83230d3 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Fri, 6 May 2022 22:32:23 -0400 Subject: [PATCH 08/40] 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 326f7cfa9b66a..f1687654e5f19 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 18ece4a7e8cc8c614b48791fdbc474b03c51dc4a Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Tue, 10 May 2022 10:16:09 -0700 Subject: [PATCH 09/40] 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 96f8d499edf9d..0910f6f96fca6 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 0af9d8663ad61..e1f5455b6aceb 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 2ce4d2dca5634..e38504ce83a0e 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 08eba279f28fb..bcbcf9841d224 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 a26e2dad5bb0d..3eafff4d8a94c 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 6c578d08a32faaa578c9366269654445e42ef243 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Tue, 10 May 2022 10:18:39 -0700 Subject: [PATCH 10/40] 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 b81d5999993916cc994231f0c8c8596cd6673b74 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Tue, 10 May 2022 11:15:13 -0700 Subject: [PATCH 11/40] Updated github to match other ssos. tctl desktop connection --- docs/config.json | 2 +- 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 +- 12 files changed, 64 insertions(+), 31 deletions(-) create mode 100644 docs/pages/includes/sso/tctlconnection.mdx diff --git a/docs/config.json b/docs/config.json index 8c6c568d67b3a..eb189027f4542 100644 --- a/docs/config.json +++ b/docs/config.json @@ -55,7 +55,7 @@ "slug": "/setup/admin/", "entries": [ { - "title": "Github SSO", + "title": "GitHub SSO", "slug": "/setup/admin/github-sso/" }, { diff --git a/docs/pages/enterprise/sso/adfs.mdx b/docs/pages/enterprise/sso/adfs.mdx index 0910f6f96fca6..957cfc7931726 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 e1f5455b6aceb..77d3ee6f1d2ab 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 e38504ce83a0e..48f6d7e89a7e9 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 bcbcf9841d224..f940110366f45 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 3eafff4d8a94c..ef4d343da4ede 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 6f48598e5a1f9..57552c54e4dc7 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 1c9db654e598b29ca16ed44162f6ddf64ac2f042 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Tue, 10 May 2022 11:30:06 -0700 Subject: [PATCH 12/40] 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 49849f0053b5db3e1db3684ff83a437997fc8b3f Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Tue, 10 May 2022 11:52:04 -0700 Subject: [PATCH 13/40] 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/40] 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 f1687654e5f19..c8d2e84dbef46 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 4e488469ffdaa055379f6b614ca4f45c72bb84fa Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Thu, 12 May 2022 13:30:14 -0700 Subject: [PATCH 15/40] 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 957cfc7931726..560c061a0cffc 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 0a2f895d3fe19aa0cb866af4f015a75c2d6fbcec Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Thu, 12 May 2022 13:31:03 -0700 Subject: [PATCH 16/40] 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 f940110366f45..26f58c97a5b56 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 672a8edce39274745b6ea778b5d76f9240e2ae24 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Thu, 12 May 2022 13:35:32 -0700 Subject: [PATCH 17/40] 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 ba548c7f46c1370e7419aa6d89fb9e1f8df45475 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Thu, 12 May 2022 13:38:54 -0700 Subject: [PATCH 18/40] 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 ef4d343da4ede..487a870215922 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 89f42dffd35203537cd845fd94361003848bea35 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Thu, 12 May 2022 13:42:13 -0700 Subject: [PATCH 19/40] 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 48f6d7e89a7e9..11d621ed9fa61 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 249999d33d24ea3c4a382281107809f46df3efdf Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Wed, 18 May 2022 08:34:30 -0400 Subject: [PATCH 20/40] 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 | 6 ++++-- 2 files changed, 4 insertions(+), 4 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 57552c54e4dc7..f8b44222e54db 100644 --- a/docs/pages/setup/admin/github-sso.mdx +++ b/docs/pages/setup/admin/github-sso.mdx @@ -1,6 +1,6 @@ --- title: Set up Single Sign-On with GitHub -description: Setting up Github SSO +description: Setting up GitHub SSO videoBanner: XjgN2WWFCX8 --- @@ -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!) @@ -67,7 +69,7 @@ GitHub OAuth App you created earlier. Teleport will request only the `read:org` OAuth scope. Read more about OAuth scopes in GitHub's documentation: -[Github OAuth scopes](https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/) +[GitHub OAuth scopes](https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/) Finally, create the connector using `tctl`: From 02175e6a55ff3cbba3bf8f09e9404752bc5d7b65 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Wed, 18 May 2022 08:38:06 -0400 Subject: [PATCH 21/40] 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 dcfdd353f85f7eb7790a4d1fcabe2cb7471843a0 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Sun, 22 May 2022 09:46:43 -0400 Subject: [PATCH 22/40] 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 560c061a0cffc..53ce0e5763b49 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 77d3ee6f1d2ab..c5394b5fd227b 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 11d621ed9fa61..99f0b6b02723c 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 26f58c97a5b56..26999d1409d0e 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 487a870215922..94ec1413520ec 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 a536603d071bc57d2f106a218ce7525fcc6d0a8d Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Sun, 22 May 2022 09:55:55 -0400 Subject: [PATCH 23/40] 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 53ce0e5763b49..ed90016f43047 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 99f0b6b02723c..e7afa0de5f003 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 26999d1409d0e..7c2e964d94a11 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 94ec1413520ec..fe270b62ab4bc 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 c407227f27201093ade3d2dac6b9c43dab15c656 Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Thu, 26 May 2022 18:10:50 -0400 Subject: [PATCH 24/40] 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 | 168 ++++++++++++------ 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, 198 insertions(+), 162 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 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 From 740ff490be5fe1adc3a057493c844548be4907dc Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Wed, 1 Jun 2022 08:58:52 -0400 Subject: [PATCH 25/40] 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 c9f283fd5b771..cc0651c03fd86 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 19ba95bf8f17bef7ea071187d313e0e8e05e0a3e Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Wed, 1 Jun 2022 08:59:33 -0400 Subject: [PATCH 26/40] 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 17acc90733a4f..51f606049639e 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 6ff9dfe24ef1fd2d0cce700074ca2befd52ea31e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Krzysztof=20Skrz=C4=99tnicki?= Date: Fri, 27 May 2022 08:23:20 +0200 Subject: [PATCH 27/40] CLI reference for `tctl sso test`, `tctl sso configure`. --- docs/pages/setup/reference/cli.mdx | 304 +++++++++++++++++++++++++++++ 1 file changed, 304 insertions(+) diff --git a/docs/pages/setup/reference/cli.mdx b/docs/pages/setup/reference/cli.mdx index dd460ea557b7d..c1ddb900f6326 100644 --- a/docs/pages/setup/reference/cli.mdx +++ b/docs/pages/setup/reference/cli.mdx @@ -1305,6 +1305,310 @@ $ tctl auth rotate --type=user --grace-period=200h $ tctl auth rotate --type=host --grace-period=8h ``` +### tctl sso test + +Perform end-to-end test of SSO flow using provided auth connector definition. + +The command supports all auth connector types: `github`, `oidc`, `saml`. The latter two require Teleport Enterprise. + +The testing consists of running a single end-to-end authentication request against provided auth connector definition. +Once the request is finished, the results will be printed to console along with context-specific diagnostic informations. +The test process will modify the list of configured auth connectors or result in certificates being issued. + +```code +$ tctl [] sso test [] +``` + +#### Arguments + +- `[]` Connector resource definition file. Optional. Empty for stdin. + +#### Flags + +This command defines no flags. + +#### Global flags + +These flags are available for all commands `--debug, --config`. Run +`tctl help ` or see the [Global Flags section](#tctl-global-flags). + +#### Examples + +Test the auth connector from `connector.yaml`: + +```code +$ tctl sso test connector.yaml +``` + +The command is designed to be used in conjunction with `tctl sso configure` family of commands: + +```code +$ tctl sso configure ... | tctl sso test +``` + +The pipeline may also utilise `tee` to capture the connector generated with `tctl sso configure`. This will save the connector in `connector.yaml`: + +```code +$ tctl sso configure ... | tee connector.yaml | tctl sso test +``` + +### tctl sso configure github + +Configure Github auth connector. + +Required params `--id` and `--secret` come from the [Github OAuth app](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app). + +The flag `--teams-to-logins` can be provided multiple times to specify which Github Teams are assigned which roles. + +```code +$ tctl sso test --id=GITHUB_CLIENT_ID --secret=GITHUB_SECRET --teams-to-logins=... [] +``` + +#### Arguments + +This command accepts no arguments. + +#### Flags + +Mandatory flags: `--id`, `--secret`, `--teams-to-logins`. + +| Name | Default Value(s) | Allowed Value(s) | Description | +|---------------------------|------------------|----------------------------|---------------------------------------------------------| +| `-n`, `--name` | `github` | resource name | Connector name. | +| `-r`, `--teams-to-logins` | none | `org,team,role1,role2,...` | Sets teams-to-logins mapping. Repeatable. | +| `--display` | none | display name | Controls how this connector is displayed. | +| `--id` | none | Github OAuth2 client id | Github app client ID. | +| `--secret` | none | Github OAuth2 secret | Github app client secret. | +| `--redirect-url` | none | Valid callback URL. | Authorization callback URL. | +| `--ignore-missing-roles` | | | Ignore missing roles referenced in `--teams-to-logins.` | + +#### Global flags + +These flags are available for all commands `--debug, --config`. Run +`tctl help ` or see the [Global Flags section](#tctl-global-flags). + +#### Examples + +Generate Github auth connector. Two role mappings are defined: + - members of `admin` team in `octocats` org will receive `access`, `editor` and `auditor` roles. + - members of `dev` team in `octocats` org will receive `access` role. + +The values for `--secret` and `--id` are provided by GitHub on [OAuth app](https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps) configuration page. + +```code +$ tctl sso configure gh -r octocats,admin,access,editor,auditor -r octocats,dev,access --secret GH_SECRET --id CLIENT_ID +INFO [CLIENT] RedirectURL empty, resolving automatically. +INFO [CLIENT] RedirectURL set to "https://teleport.example.com:3080/v1/webapi/github/callback" +kind: github +metadata: + name: github +spec: + client_id: CLIENT_ID + client_secret: GH_SECRET + display: "" + redirect_url: https://teleport.example.com:3080/v1/webapi/github/callback + teams_to_logins: + - logins: + - access + - editor + - auditor + organization: octocats + team: admin + - logins: + - access + organization: octocats + team: dev +version: v3 +``` + +Generate the configuration and immediately test it using `tctl sso test` command. + +```code +$ tctl sso configure gh ... | tctl sso test +``` + +### tctl sso configure oidc + +Configure OIDC auth connector, optionally using a preset. + +The flag `--claims-to-roles` can be provided multiple times. + +```code +$ tctl sso configure oidc --id=CLIENT_ID --secret=SECRET --claims-to-roles=... [] +``` + +#### Arguments + +This command accepts no arguments. + +#### Flags + +Mandatory flags: `--id`, `--secret`, `--claims-to-roles`. Other flags may be required depending on chosen preset. + +General flags: + +| Name | Description | +|---------------------------|-------------------------------------------------------------------------------------------------------------------------------------------| +| `-p`, `--preset` | Preset. One of: `google`, `gitlab`, `okta`. | +| `-n`, `--name` | Connector name. Required, unless implied from preset. | +| `-r`, `--claims-to-roles` | Sets claim-to-roles mapping using format `claim_name,claim_value,role1,role2,...`. Repeatable. | +| `--display` | Display controls how this connector is displayed. | +| `--id` | OIDC app client ID. | +| `--secret` | OIDC app client secret. | +| `--issuer-url` | Issuer URL. | +| `--redirect-url` | Authorization callback URL. | +| `--prompt` | Optional OIDC prompt. Example values: `none`, `select_account`, `login`, `consent`. | +| `--scope` | Scope specifies additional scopes set by provider. Each repetition of the flag declares one scope. Examples: `email`, `groups`, `openid`. | +| `--acr` | Authentication Context Class Reference values. | +| `--provider` | Sets the external identity provider type to enable IdP specific workarounds. Examples: `ping`, `adfs`, `netiq`, `okta``. | +| `--ignore-missing-roles` | Ignore missing roles referenced in `--claims-to-roles`. | + +Supported presets: + +| Name | Description | Display | Issuer URL | +|----------|------------------|---------|-------------------------------| +| `google` | Google Workspace | Google | `https://accounts.google.com` | +| `gitlab` | Gitlab | Gitlab | `https://gitlab.com` | +| `okta` | Okta | Okta | `https://oktaice.okta.com` | + +The above values for `--issuer-url` are defaults which may need to be updated depending on IdP configuration. + +The following flags are specific to Google Workspace: + +| Name | Description | +|--------------------|--------------------------------------------------------------------------------------------------------| +| `--google-acc-uri` | URI pointing at service account credentials. Example: `file:///var/lib/teleport/gworkspace-creds.json`.| +| `--google-acc` | String containing Google service account credentials. | +| `--google-admin` | Email of a Google admin to impersonate. | +| `--google-legacy` | Flag to select groups with direct membership filtered by domain (legacy behavior).
Disabled by default. [More info](https://goteleport.com/docs/enterprise/sso/google-workspace/#how-teleport-uses-google-workspace-apis) | +| `--google-id` | Shorthand for setting the `--id` flag to `.apps.googleusercontent.com` | + + +#### Global flags + +These flags are available for all commands `--debug, --config`. Run +`tctl help ` or see the [Global Flags section](#tctl-global-flags). + +#### Examples + +1. Generate OIDC auth connector configuration called `myauth`. Two mappings from OIDC claims to roles are defined: + - members of `admin` group will receive `access`, `editor` and `auditor` roles. + - members of `developer` group will receive `access` role. + +The values for `--secret`, `--id` and `--issuer-url` are provided by IdP. + +```code +$ tctl sso configure oidc -n myauth -r groups,admin,access,editor,auditor -r group,developer,access \ + --secret IDP_SECRET --id CLIENT_ID \ + --issuer-url https://idp.example.com +``` + +2. Generate OIDC auth connector with Okta preset, enabled `groups` scope, mapping group `okta-admin` to roles `access`, `editor`, `auditor`. +Issuer URL is set to match custom Okta domain. + +```code +$ tctl sso configure oidc --preset okta --scope groups -r groups,okta-admin,access,editor,auditor \ + --secret IDP_SECRET --id CLIENT_ID \ + --issuer-url dev-123456.oktapreview.com +``` + +3. Generate OIDC auth connector with Google preset. Service account credentials are set to be loaded from /var/lib/teleport/gacc.json with --google-acc-uri. + +```code +$ tctl sso configure oidc --preset google -r groups,mygroup@mydomain.example.com,access \ + --secret SECRET --google-id GOOGLE_ID --google-acc-uri /var/lib/teleport/gacc.json \ + --google-admin admin@mydomain.example.com +``` + +4. Generate the configuration and immediately test it using `tctl sso test`` command. + +```code +$ tctl sso configure oidc ... | tctl sso test +``` + + +### tctl sso configure saml + +Configure SAML auth connector, optionally using a preset. + +The flag `--attributes-to-roles/-r` can be provided multiple times. + +To avoid errors when pasting XML to YAML file, we encourage the usage of flag `--entity-descriptor`/`-e`. + +```code +$ tctl sso configure saml -e entity_desc.xml -r attr,value,role1 [] +``` + +#### Arguments + +This command accepts no arguments. + +#### Flags + +Mandatory flags: +- `--attributes-to-roles`; may be given multiple times. +- `--entity-descriptor`, unless `--sso`, `--acs`, `--cert` and `--issuer` are also given. +- `-n/--name`, unless `-p/--preset` is present. + +| Name | Description | +|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------| +| `-p/--preset` | Preset. One of: `okta`, `onelogin`, `ad`, `adfs`. | +| `-n/--name` | Connector name. Required, unless implied from preset. | +| `-e/--entity-descriptor` | Set the Entity Descriptor. Valid values: file, URL, XML content. Supplies configuration parameters as single XML instead of individual elements. | +| `-r/--attributes-to-roles` | Sets attribute-to-role mapping using format `attr_name,attr_value,role1,role2,...`. Repeatable. | +| `--display` | Sets the connector display name. | +| `--issuer` | Sets identity provider issuer. | +| `--sso` | SSO is the URL of the identity provider's SSO service. | +| `--cert` | Cert file with with the IdP certificate PEM. IdP signs responses using this certificate. | +| `--acs` | AssertionConsumerService is a URL for assertion consumer service on the service provider (Teleport's side). | +| `--audience` | Audience uniquely identifies our service provider. | +| `--service-provider-issuer` | ServiceProviderIssuer is the issuer of the service provider (Teleport). | +| `--signing-key-file` | A file with request signing key. Must be used together with `--signing-cert-file`. | +| `--signing-cert-file` | A file with request certificate. Must be used together with `--signing-key-file`. | +| `--assertion-key-file` | A file with key used for securing SAML assertions. Must be used together with `--assertion-cert-file`. | +| `--assertion-cert-file` | A file with cert used for securing SAML assertions. Must be used together with `--assertion-key-file`. | +| `--provider` | Sets the external identity provider type, enabling workarounds. Examples: ping, adfs. | +| `--ignore-missing-roles` | Ignore missing roles referenced in `--attributes-to-roles`. | + +Supported presets: + +| Name | Description | Display | +|------------|--------------------------------------|-----------| +| `okta` | Okta | Okta | +| `onelogin` | OneLogin | OneLogin | +| `ad` | Azure Active Directory | Microsoft | +| `adfs` | Active Directory Federation Services | ADFS | + + +#### Global flags + +These flags are available for all commands `--debug, --config`. Run +`tctl help ` or see the [Global Flags section](#tctl-global-flags). + +#### Examples + +1. Generate SAML auth connector configuration called `myauth`. Two mappings from SAML attributes to roles are defined: + - members of `admin` group will receive `access`, `editor` and `auditor` roles. + - members of `developer` group will receive `access` role. +The IdP metadata will be read from `entity-desc.xml` file. + +```code +$ tctl sso configure saml -n myauth -r group,admin,access,editor,auditor -r group,developer,access -e entity-desc.xml +``` + +2. Generate SAML auth connector configuration using `okta` preset. The choice of preset affects default name, display attribute and may apply IdP-specific tweaks. +Instead of XML file, a URL was provided to -e flag, which will be fetched by Teleport during runtime. + +```code +$ tctl sso configure saml -p okta -r group,dev,access -e https://dev-123456.oktapreview.com/app/ex30h8/sso/saml/metadata +``` + +3. Generate the configuration and immediately test it using `tctl sso test` command. + +```code +$ tctl sso configure saml -p okta -r group,developer,access -e entity-desc.xml | tctl sso test +``` + ### tctl create Create or update a Teleport resource from a YAML file. From df3931398d86ec88676ad9dfaa7ba6fcfae8e858 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Krzysztof=20Skrz=C4=99tnicki?= Date: Fri, 27 May 2022 11:43:42 +0200 Subject: [PATCH 28/40] Update GitHub SSO guide. --- docs/pages/setup/admin/github-sso.mdx | 86 +++++++++++++++++++++++---- 1 file changed, 75 insertions(+), 11 deletions(-) diff --git a/docs/pages/setup/admin/github-sso.mdx b/docs/pages/setup/admin/github-sso.mdx index 51f606049639e..ebaa2afaeb8ad 100644 --- a/docs/pages/setup/admin/github-sso.mdx +++ b/docs/pages/setup/admin/github-sso.mdx @@ -17,7 +17,7 @@ Teleport. (!docs/pages/includes/tctl.mdx!) -## Step 1/3. Create a GitHub OAuth app +## Step 1/5. Create a GitHub OAuth app Create and register a GitHub OAuth App. When you do so, ensure that your OAuth App's "Authentication callback URL" is the following: @@ -34,10 +34,17 @@ Instructions for creating a GitHub OAuth app are available here: [Creating an OAuth App](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) -## Step 2/3. Create a GitHub authentication connector +## Step 2/5. Define the GitHub authentication connector -Define a GitHub authentication connector by creating a file called `github.yaml` -with the following content: +Define a GitHub authentication connector by creating a file called `github.yaml`. + +You can do it with the following command: + +```code +$ tctl sso configure github --id --secret -r octocats,admins,access | tee github.yaml +``` + +The resulting file should look like this: ```yaml kind: github @@ -63,18 +70,66 @@ spec: - access ``` -The values of `client_id`, `client_secret`, and `redirect_url` come from the -GitHub OAuth App you created earlier. +The values of `client_id`, `client_secret` come from the GitHub OAuth App you created earlier. `redirect_url` is automatically configured by [`tctl sso configure github`](../reference/cli.mdx#tctl-sso-configure-github) based on the settings of Teleport cluster. -Teleport will request only the `read:org` OAuth scope. Read more about OAuth scopes in GitHub's documentation: + + The flag `--teams-to-logins` (`-r` for short) can be repeated multiple times with each repetition creating additional mapping entry. + + If multiple roles are desired, they can be listed separated by commas: `-r org,team,role1,role2,role3,...`. + + +Teleport will request only the `read:org` OAuth scope. Read more about OAuth scopes in [GitHub's documentation](https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/). [GitHub OAuth scopes](https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/) -Finally, create the connector using `tctl`: +To ensure the connector is working as intended: SSO flow is passing, roles are assigned as intended etc., you can now test it using [`tctl sso test`](../reference/cli.mdx#tctl-sso-test) command. ```code -$ tctl create github.yaml -# authentication connector "github" has been created +$ tctl sso test github.yaml +If browser window does not open automatically, open it by clicking on the link: + http://127.0.0.1:62482/e1fadd3f-dc6a-420b-9791-94fd29dfc2db +Success! Logged in as: ExampleGithubUser +-------------------------------------------------------------------------------- +Authentication details: + logins: + - access + roles: + - access + traits: + github_teams: + - admins + kubernetes_groups: null + kubernetes_users: null + logins: + - ExampleGithubUser + username: ExampleGithubUser +-------------------------------------------------------------------------------- +[GitHub] Received claims: +organization_to_teams: + octocats: + - admins +teams: +- admins +username: ExampleGithubUser + +-------------------------------------------------------------------------------- +[GitHub] Connector team to logins mapping: +- logins: + - access + organization: octocats + team: admins + +-------------------------------------------------------------------------------- +For more details repeat the command with --debug flag. +``` + +The test command can accept the auth connector from standard input. The pipeline may also utilise `tee` to save the connector to file: + +```code +$ tctl sso configure github ... | tee github.yaml | tctl sso test ``` @@ -84,7 +139,16 @@ $ tctl create github.yaml able to determine team memberships for these organizations. -## Step 3/3. Configure authentication preference +## Step 4/5. Create the connector + +Once you are satisfied with the connector, you can finally create it using `tctl`: + +```code +$ tctl create github.yaml +# authentication connector "github" has been created +``` + +## Step 5/5. Configure authentication preference Configure the Teleport Auth Service to enable the GitHub authentication connector. From ce97db4a40e61a4fc2593ff1202f0a42b0f23589 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Krzysztof=20Skrz=C4=99tnicki?= Date: Fri, 27 May 2022 16:02:05 +0200 Subject: [PATCH 29/40] Comment out command output. --- docs/pages/setup/admin/github-sso.mdx | 70 +++++++++++++-------------- 1 file changed, 35 insertions(+), 35 deletions(-) diff --git a/docs/pages/setup/admin/github-sso.mdx b/docs/pages/setup/admin/github-sso.mdx index ebaa2afaeb8ad..06b630639225c 100644 --- a/docs/pages/setup/admin/github-sso.mdx +++ b/docs/pages/setup/admin/github-sso.mdx @@ -89,41 +89,41 @@ To ensure the connector is working as intended: SSO flow is passing, roles are a ```code $ tctl sso test github.yaml -If browser window does not open automatically, open it by clicking on the link: - http://127.0.0.1:62482/e1fadd3f-dc6a-420b-9791-94fd29dfc2db -Success! Logged in as: ExampleGithubUser --------------------------------------------------------------------------------- -Authentication details: - logins: - - access - roles: - - access - traits: - github_teams: - - admins - kubernetes_groups: null - kubernetes_users: null - logins: - - ExampleGithubUser - username: ExampleGithubUser --------------------------------------------------------------------------------- -[GitHub] Received claims: -organization_to_teams: - octocats: - - admins -teams: -- admins -username: ExampleGithubUser - --------------------------------------------------------------------------------- -[GitHub] Connector team to logins mapping: -- logins: - - access - organization: octocats - team: admins - --------------------------------------------------------------------------------- -For more details repeat the command with --debug flag. +# If browser window does not open automatically, open it by clicking on the link: +# http://127.0.0.1:62482/e1fadd3f-dc6a-420b-9791-94fd29dfc2db +# Success! Logged in as: ExampleGithubUser +# -------------------------------------------------------------------------------- +# Authentication details: +# logins: +# - access +# roles: +# - access +# traits: +# github_teams: +# - admins +# kubernetes_groups: null +# kubernetes_users: null +# logins: +# - ExampleGithubUser +# username: ExampleGithubUser +# -------------------------------------------------------------------------------- +# [GitHub] Received claims: +# organization_to_teams: +# octocats: +# - admins +# teams: +# - admins +# username: ExampleGithubUser +# +# -------------------------------------------------------------------------------- +# [GitHub] Connector team to logins mapping: +# - logins: +# - access +# organization: octocats +# team: admins +# +# -------------------------------------------------------------------------------- +# For more details repeat the command with --debug flag. ``` The test command can accept the auth connector from standard input. The pipeline may also utilise `tee` to save the connector to file: From 699596360fb7aee0696fb30ea060effa7cc38060 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Krzysztof=20Skrz=C4=99tnicki?= Date: Fri, 27 May 2022 16:04:02 +0200 Subject: [PATCH 30/40] Adjust SSO troubleshooting, OIDC includes, minor fixes. --- docs/pages/enterprise/sso.mdx | 34 ++++++++++++------- docs/pages/enterprise/sso/gitlab.mdx | 2 -- .../pages/enterprise/sso/google-workspace.mdx | 8 ++--- docs/pages/enterprise/sso/oidc.mdx | 2 -- .../enterprise/oidcauthentication.mdx | 2 ++ .../sso/loginerrortroubleshooting.mdx | 3 ++ 6 files changed, 30 insertions(+), 21 deletions(-) diff --git a/docs/pages/enterprise/sso.mdx b/docs/pages/enterprise/sso.mdx index de5d88a19cd5b..f39a4dd231a8f 100644 --- a/docs/pages/enterprise/sso.mdx +++ b/docs/pages/enterprise/sso.mdx @@ -150,8 +150,11 @@ or create a `cluster_auth_preference` resource. -Next, define an authentication connector. Create a file called `connector.yaml` -based on one of the following examples. +Next, define an authentication connector. We recommend the usage of helper +commands to achieve this for [SAML](../setup/reference/cli.mdx#tctl-sso-configure-saml), + [OIDC](../setup/reference/cli.mdx#tctl-sso-configure-oidc) and + [GitHub](../setup/reference/cli.mdx#tctl-sso-configure-github) connectors. + The resulting file `connector.yaml` should be similar to one of the following examples. @@ -198,12 +201,16 @@ based on one of the following examples. +Note: +- Manually pasting the XML to `entity_descriptor` field is error prone. We recommend using `tctl sso configure saml -e entity_descriptor.xml ...` command instead. +- 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. -You may use `entity_descriptor_url`, in lieu of `entity_descriptor`, to fetch -the entity descriptor from your IDP. +Test the connector with [`tctl sso test`](../setup/reference/cli.mdx#tctl-sso-test) command: -We recommend "pinning" the entity descriptor by including the XML rather than -fetching from a URL. +```bsh +$ tctl sso test connector.yaml +``` Create the connector: @@ -310,13 +317,14 @@ SAML and OIDC types: ## SSO Customization -| Provider | YAML | Example | -| - | - | - | -| Github | `display: Github` | ![github](../../img/teleport-sso/github@2x.png) | +| Provider | YAML | Example | +|-----------|----------------------|-------------------------------------------------------| +| Github | `display: Github` | ![github](../../img/teleport-sso/github@2x.png) | | Microsoft | `display: Microsoft` | ![microsoft](../../img/teleport-sso/microsoft@2x.png) | -| Google | `display: Google` | ![google](../../img/teleport-sso/google@2x.png) | +| Google | `display: Google` | ![google](../../img/teleport-sso/google@2x.png) | | BitBucket | `display: Bitbucket` | ![bitbucket](../../img/teleport-sso/bitbucket@2x.png) | -| OpenID | `display: Okta` | ![Okta](../../img/teleport-sso/openId@2x.png) | +| OpenID | `display: Okta` | ![Okta](../../img/teleport-sso/openId@2x.png) | + ## Troubleshooting @@ -334,8 +342,10 @@ must be able to: If something is not working, we recommend to: +- Run the connector definition through [`tctl sso test`](../setup/reference/cli.mdx#tctl-sso-test) command. - Double-check the host names, tokens and TCP ports in a connector definition. - +- Double-check the role mapping in connector definition for possible typos. +- Verify the configuration on IdP side (callback URLs, claim names, scopes, ...). ### Using the Web UI diff --git a/docs/pages/enterprise/sso/gitlab.mdx b/docs/pages/enterprise/sso/gitlab.mdx index 4e9826a2250b6..e604c01593d3f 100644 --- a/docs/pages/enterprise/sso/gitlab.mdx +++ b/docs/pages/enterprise/sso/gitlab.mdx @@ -43,8 +43,6 @@ like: (!docs/pages/includes/tctl.mdx!) -## Enable default OIDC authentication - (!docs/pages/includes/enterprise/oidcauthentication.mdx!) ## Configure GitLab diff --git a/docs/pages/enterprise/sso/google-workspace.mdx b/docs/pages/enterprise/sso/google-workspace.mdx index 19b9410aa0c3b..63287a06af37f 100644 --- a/docs/pages/enterprise/sso/google-workspace.mdx +++ b/docs/pages/enterprise/sso/google-workspace.mdx @@ -46,11 +46,9 @@ Before you get started you’ll need: (!docs/pages/includes/tctl.mdx!) -## Step 1/4. Enable default OIDC authentication - (!docs/pages/includes/enterprise/oidcauthentication.mdx!) -## Step 2/4. Configure Google Workspace +## Configure Google Workspace The setup will consist of: @@ -233,7 +231,7 @@ Configure [domain-wide fetch both direct and indirect groups or just direct groups, respectively. -## Step 3/4. Create an OIDC connector +## Create an OIDC connector Create the following OIDC connector [resource spec](../../setup/reference/resources.mdx) as `gworkspace-connector.yaml`. We will explain how to choose values for fields within the resource spec below. @@ -291,7 +289,7 @@ While a `v3` connector is configured, you can no longer downgrade Teleport to a version before 8.1.2. Before such a downgrade, follow the above instructions and change the version number back to `v2`. -## Step 4/4. Test your Google Workspace OIDC connector +## Test your Google Workspace OIDC connector The Web UI will now contain a new button: "Login with Google". The CLI is the same as before: diff --git a/docs/pages/enterprise/sso/oidc.mdx b/docs/pages/enterprise/sso/oidc.mdx index 1d07f4b1afb9d..ced0cd4a6bbb0 100644 --- a/docs/pages/enterprise/sso/oidc.mdx +++ b/docs/pages/enterprise/sso/oidc.mdx @@ -41,8 +41,6 @@ administrators to define policies like: (!docs/pages/includes/tctl.mdx!) -## Enable default OIDC authentication - (!docs/pages/includes/enterprise/oidcauthentication.mdx!) ## Identity Providers diff --git a/docs/pages/includes/enterprise/oidcauthentication.mdx b/docs/pages/includes/enterprise/oidcauthentication.mdx index a901b50a5f13a..260fb24e72455 100644 --- a/docs/pages/includes/enterprise/oidcauthentication.mdx +++ b/docs/pages/includes/enterprise/oidcauthentication.mdx @@ -1,3 +1,5 @@ +## Enable default OIDC authentication + Configure Teleport to use OIDC authentication as the default instead of the local user database. diff --git a/docs/pages/includes/sso/loginerrortroubleshooting.mdx b/docs/pages/includes/sso/loginerrortroubleshooting.mdx index c7744f79347a2..ac5cf57772856 100644 --- a/docs/pages/includes/sso/loginerrortroubleshooting.mdx +++ b/docs/pages/includes/sso/loginerrortroubleshooting.mdx @@ -12,7 +12,10 @@ must be able to: If something is not working, we recommend to: +- Run the connector definition through [`tctl sso test`](../../setup/reference/cli.mdx#tctl-sso-test) command. - Double-check the host names, tokens and TCP ports in a connector definition. +- Double-check the role mapping in connector definition for possible typos. +- Verify the configuration on IdP side (callback URLs, claim names, scopes, ...). ### Using the Web UI From bdcc8f90558d06583ad0f36983e7841c61f4168f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Krzysztof=20Skrz=C4=99tnicki?= Date: Fri, 27 May 2022 16:04:44 +0200 Subject: [PATCH 31/40] Okta SSO guide changes, including adding `tctl sso` command usage. --- docs/pages/enterprise/sso/okta.mdx | 164 ++++++++++++++++++++++------- 1 file changed, 124 insertions(+), 40 deletions(-) diff --git a/docs/pages/enterprise/sso/okta.mdx b/docs/pages/enterprise/sso/okta.mdx index cf2f9848ede34..34255fb77b209 100644 --- a/docs/pages/enterprise/sso/okta.mdx +++ b/docs/pages/enterprise/sso/okta.mdx @@ -49,9 +49,9 @@ like: First, create a SAML 2.0 Web App in Okta configuration section -### 1. Select Create New App +- Select "Create New App" +- Select "Web Platform" and "SAML 2.0 Sign On Method". -Select Web Platform and SAML 2.0 Sign On Method. ![Create APP](../../../img/sso/okta/okta-saml-1.png) ## Configure the App @@ -59,37 +59,44 @@ Select Web Platform and SAML 2.0 Sign On Method. We are going to map the Okta groups we've created above to the SAML Attribute statements (special signed metadata exposed via a SAML XML response). -GENERAL +### Section: _"General"_ -- Single sign on URL `https://teleport-proxy.example.com:443/v1/webapi/saml/acs` -- Audience URI (SP Entity ID)`https://teleport-proxy.example.com:443/v1/webapi/saml/acs` -- Name ID format `EmailAddress` -- Application username `Okta username` +Configure general settings section. Make sure there are no typos in the callback URL. -SINGLE ATTRIBUTE STATEMENTS +| Field | Value | +|-----------------------------|-------------------------------------------------------------| +| Single sign on URL | `https://teleport-proxy.example.com:443/v1/webapi/saml/acs` | +| Audience URI (SP Entity ID) | `https://teleport-proxy.example.com:443/v1/webapi/saml/acs` | +| Name ID format | `EmailAddress` | +| Application username | `Okta username` | -- Name: `username` | Name format: `Unspecified` | Value: `user.login` +### Section: _"Single Attribute Statements"_ -GROUP ATTRIBUTE STATEMENTS +Configure single-value attributes to be passed to Teleport on login. -- Name: `groups` | Name format: `Unspecified` -- Filter: `Matches regex` | `.*` +| Name | Name format | Value | +|------------|---------------|--------------| +| `username` | `Unspecified` | `user.login` | +| `email` | `Basic` | `user.email` | -![Configure APP](../../../img/sso/okta/setup-redirection.png) +### Section: _"Group Attribute Statements"_ -### Note: RegEx requires `.*` +Configure which group information to be passed to Teleport on login. To pass all groups via the claim named `groups`: -![Configure APP](../../../img/sso/okta/regex.png) +| Name | Name format | Filter type | Filter definition | +|----------|---------------|-----------------|-------------------| +| `groups` | `Unspecified` | `Matches regex` | `.*` | - - Notice that we have set "NameID" to the email format and mapped the groups with - a wildcard regex in the Group Attribute statements. We have also set the "Audience" - and SSO URL to the same value. + + The regular expression matching all groups is `.*`. If you leave the filter definition empty it will match no groups. +### Review + +Afterwards the app configuration should look similar to this: + +![Configure APP](../../../img/sso/okta/setup-redirection.png) + ## Create & Assign Groups **Create Groups** @@ -106,25 +113,11 @@ Assign groups and people to your SAML app: ![Configure APP](../../../img/sso/okta/okta-saml-3.1.png) -Make sure to download the metadata in the form of an XML document. It will be used it to +Make sure to download the metadata in the form of an XML document and save it (e.g. as `entity_desc.xml`). It will be used it to configure a Teleport connector: ![Download metadata](../../../img/sso/okta/okta-saml-4.png) -## Create a SAML Connector - -Now, create a SAML connector [resource](../../setup/reference/resources.mdx): - -```yaml -(!examples/resources/saml-connector.yaml!) -``` - -Create the connector using `tctl` tool: - -```bsh -$ tctl create okta-connector.yaml -``` - ## Create a Developer Teleport Role We are going to create a new role that'll pull in external information from Okta. Notice @@ -158,10 +151,101 @@ We'll use tctl to create this role on the auth server: $ tctl create dev.yaml ``` -## Testing +## Create & Test SAML Connector + +Now, create a SAML connector [resource](../../setup/reference/resources.mdx). + +Use the [`tctl sso configure saml`](../../setup/reference/cli.mdx#tctl-sso-configure-saml) command like so: + +```code +$ tctl sso configure saml -p okta -e entity_desc.xml -r groups,okta-admin,editor -r groups,okta-dev,dev \ + | tee okta-connector.yaml +``` + +The resulting file should be similar to this: + +```yaml +(!examples/resources/saml-connector.yaml!) +``` + +Before creating the connector, you should test it using [`tctl sso test`](../../setup/reference/cli.mdx#tctl-sso-test) command: + +```code +$ tctl sso test okta-connector.yaml +``` + +You can also run both commands as a pipeline: + +```code +$ tctl sso configure saml -p okta -e entity_desc.xml -r groups,okta-admin,editor -r groups,okta-dev,dev \ + | tee okta-connector.yaml | tctl sso test +# INFO [CLIENT] ACS empty, resolving automatically. +# INFO [CLIENT] ACS set to "https://teleport-proxy.example.com:443/v1/webapi/saml/acs" +# INFO [CLIENT] Cannot parse entity descriptor as URL, missing scheme: "entity_desc.xml". +# INFO [CLIENT] Entity descriptor read from file "entity_desc.xml". +# If browser window does not open automatically, open it by clicking on the link: +# http://127.0.0.1:64847/9d140755-1a1e-4b21-b9d7-11ce0aa1eb6c +# Success! Logged in as: oktauser@example.com +# -------------------------------------------------------------------------------- +# Authentication details: +# roles: +# - editor +# - dev +# traits: +# email: +# - oktauser@example.com +# groups: +# - Everyone +# - okta-admin +# - okta-dev +# username: +# - oktauser@example.com +# username: oktauser@example.com +# -------------------------------------------------------------------------------- +# [SAML] Attributes to roles: +# - name: groups +# roles: +# - editor +# value: okta-admin +# - name: groups +# roles: +# - dev +# value: okta-dev +# +# -------------------------------------------------------------------------------- +# [SAML] Attributes statements: +# email: +# - oktauser@example.com +# groups: +# - Everyone +# - okta-admin +# - okta-dev +# username: +# - oktauser@example.com +# +# -------------------------------------------------------------------------------- +# For more details repeat the command with --debug flag. +``` + +In the example above, we: +1. Configure the SAML connector using `okta` preset. +2. Save the connector to `okta-connector.yaml`. +3. Run end-to-end SSO flow test with `tctl sso test`. +4. When prompted, authenticate as `oktauser@example.com` on Okta login page. +5. Review the diagnostic information, observing that: + - the login was successful + - `oktauser@example.com` is member of both `okta-dev` and `okta-admin` Okta groups. + - there are `email`, `username` and `groups` attribute statements present, matching our configuration of Okta App. + +Once happy with the test results, create the connector using `tctl` tool: + +```bsh +$ tctl create okta-connector.yaml +``` + +## Validation -The Web UI will now contain a new button: "Login with Okta". The CLI is -the same as before: +The Web UI will now contain a new button: "Login with Okta". You can also login with `tsh`: ```bsh $ tsh login --proxy=proxy.example.com --auth=okta From 48e14717eadaed03aef1ee28bea5bd9a33a45d7e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Krzysztof=20Skrz=C4=99tnicki?= Date: Tue, 31 May 2022 13:35:39 +0200 Subject: [PATCH 32/40] Lint fixes in Okta guide. --- docs/pages/enterprise/sso/okta.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/pages/enterprise/sso/okta.mdx b/docs/pages/enterprise/sso/okta.mdx index 34255fb77b209..64633da30c4f4 100644 --- a/docs/pages/enterprise/sso/okta.mdx +++ b/docs/pages/enterprise/sso/okta.mdx @@ -59,7 +59,7 @@ First, create a SAML 2.0 Web App in Okta configuration section We are going to map the Okta groups we've created above to the SAML Attribute statements (special signed metadata exposed via a SAML XML response). -### Section: _"General"_ +### Section: *"General"* Configure general settings section. Make sure there are no typos in the callback URL. @@ -70,7 +70,7 @@ Configure general settings section. Make sure there are no typos in the callback | Name ID format | `EmailAddress` | | Application username | `Okta username` | -### Section: _"Single Attribute Statements"_ +### Section: *"Single Attribute Statements"* Configure single-value attributes to be passed to Teleport on login. @@ -79,7 +79,7 @@ Configure single-value attributes to be passed to Teleport on login. | `username` | `Unspecified` | `user.login` | | `email` | `Basic` | `user.email` | -### Section: _"Group Attribute Statements"_ +### Section: *"Group Attribute Statements"* Configure which group information to be passed to Teleport on login. To pass all groups via the claim named `groups`: From 351612f71870e0dcc75e76b4b68a179bbaba612a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Krzysztof=20Skrz=C4=99tnicki?= Date: Tue, 31 May 2022 13:35:50 +0200 Subject: [PATCH 33/40] Azure, ADFS guides. --- docs/pages/enterprise/sso/adfs.mdx | 96 ++++++++--- docs/pages/enterprise/sso/azuread.mdx | 226 +++++++++++++++----------- 2 files changed, 203 insertions(+), 119 deletions(-) diff --git a/docs/pages/enterprise/sso/adfs.mdx b/docs/pages/enterprise/sso/adfs.mdx index cc0651c03fd86..35a2265d40130 100644 --- a/docs/pages/enterprise/sso/adfs.mdx +++ b/docs/pages/enterprise/sso/adfs.mdx @@ -6,10 +6,9 @@ h1: Single Sign-On with Active Directory Federation Services This guide will explain how to configure Active Directory Federation Services ([ADFS](https://en.wikipedia.org/wiki/Active_Directory_Federation_Services)) to be -a single sign-on (SSO) provider to issue -SSH credentials to specific groups of users. When used in combination with role -based access control (RBAC), it allows SSH administrators to define policies -like: +a single sign-on (SSO) provider to issue SSH credentials to specific groups of users. +When used in combination with role based access control (RBAC), it allows SSH administrators to +define policies like: - Only members of "DBA" group can SSH into machines running PostgreSQL. - Developers must never SSH into production servers. @@ -60,7 +59,7 @@ separate normal users and admins). ![Name ID Configuration](../../../img/adfs-1.png) ![Group Configuration](../../../img/adfs-2.png) -In addition, if you are using dynamic roles (see below), it may be useful to map +In addition, if you are using templated roles (see below), it may be useful to map the LDAP Attribute `SAM-Account-Name` to `Windows account name` and create another mapping of `E-Mail-Addresses` to `UPN`. @@ -68,22 +67,21 @@ another mapping of `E-Mail-Addresses` to `UPN`. ![UPN Configuration](../../../img/adfs-4.png) You'll also need to create a Relying Party Trust. Use the below information to -help guide you through the Wizard. Note that for development purposes we recommend -using `https://localhost:3080/v1/webapi/saml/acs` as the Assertion Consumer -Service (ACS) URL, but for production you'll want to change this to a domain -that can be accessed by other users as well. +help guide you through the Wizard. - Create a claims aware trust. - Enter data about the relying party manually. - Set the display name to something along the lines of `Teleport`. - Skip the token encryption certificate. -- Select *"Enable support for SAML 2.0 Web SSO protocol"* and set the URL to `https://localhost:3080/v1/webapi/saml/acs`. -- Set the relying party trust identifier to `https://localhost:3080/v1/webapi/saml/acs` as well. +- The value for Assertion Consumer Service (ACS) URL should be `https://teleport.example.com:3080/v1/webapi/saml/acs`, +where `teleport.example.com:3080` is a public facing Teleport proxy URL. +- Select *"Enable support for SAML 2.0 Web SSO protocol"* and set the URL to `https://teleport.example.com:3080/v1/webapi/saml/acs`. +- Set the relying party trust identifier to `https://teleport.example.com:3080/v1/webapi/saml/acs` as well. - For access control policy select *"Permit everyone"*. Once the Relying Party Trust has been created, update the Claim Issuance Policy for it. Like before, make sure you send at least `Name ID` and `Group` claims to the -relying party (Teleport). If you are using dynamic roles, it may be useful to +relying party (Teleport). If you are using templated roles, it may be useful to map the LDAP Attribute `SAM-Account-Name` to *"Windows account name"* and create another mapping of `E-Mail-Addresses` to *"UPN"*. @@ -130,7 +128,7 @@ spec: # only allow login as either ubuntu or the 'windowsaccountname' claim logins: [ '{{external["http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]}}', ubuntu ] node_labels: - "access": "relaxed" + access: relaxed ``` This role declares: @@ -145,17 +143,75 @@ The login configures Teleport to look at the `http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname` ADFS claim and use that field as an allowed login for each user. Note the -double quotes (`"`) and square brackets (`[]`) around the claim name—these are -important. +double quotes (`"`) and square brackets (`[]`) around the claim name; these need to be present +for correct processing of the claim. -Next, create a SAML connector [resource](../../setup/reference/resources.mdx): +## Create & Test SAML Connector + +Next, create a SAML connector [resource](../../setup/reference/resources.mdx). + +### Entity descriptor + +In ADFS, copy the URL from under *"ADFS -> Service -> Endpoints -> Metadata"*. You can either: +- download the XML file pointed to by the URL (for example as `entity_desc.xml`), which will populate `entity_descriptor` field in SAML connector definition. +- use the URL itself to make Teleport download the file at runtime, which in turn will go to the `entity_descriptor_url` field. + +### `tctl sso configure saml` + +Use the [`tctl sso configure saml`](../../setup/reference/cli.mdx#tctl-sso-configure-saml) command like so: + +```bsh +$ tctl sso configure saml -p adfs -e entity_desc.xml -r http://schemas.xmlsoap.org/claims/Group,Administrators,editor \ + -r http://schemas.xmlsoap.org/claims/Group,Users,access \ + | tee adfs-connector.yaml +``` + +If you want use `entity_descriptor_url` field instead, simply use the URL instead of the file path: + +```bsh +$ tctl sso configure saml -p adfs -e -r http://schemas.xmlsoap.org/claims/Group,Administrators,editor \ + -r http://schemas.xmlsoap.org/claims/Group,Users,access \ + | tee adfs-connector.yaml +``` + + +The resulting file should be similar to this: ```yaml -(!examples/resources/adfs-connector.yaml!) +kind: saml +version: v2 +metadata: + name: adfs +spec: + # display allows to set the caption of the "login" button in the Web interface. + # Using the work 'Microsoft' will show the Windows symbol in the UI. + display: Microsoft + + # "adfs" provider setting tells Teleport that this SAML connector + # uses ADFS as a provider + provider: adfs + + # entity_descriptor XML can either be copied into connector or fetched from a URL + entity_descriptor: | + + ... + + + acs: "https://teleport.example.com:3080/v1/webapi/saml/acs" + audience: "https://teleport.example.com:3080/v1/webapi/saml/acs" + service_provider_issuer: "https://teleport.example.com:3080/v1/webapi/saml/acs" + + # map AD groups to Teleport roles + attributes_to_roles: + - name: "http://schemas.xmlsoap.org/claims/Group" + value: "Administrators" + roles: ["editor"] + - name: "http://schemas.xmlsoap.org/claims/Group" + value: "Users" + roles: ["access"] ``` -The `acs` field should match the value you set in ADFS earlier and you can -obtain the `entity_descriptor_url` from ADFS under *"ADFS -> Service -> Endpoints -> Metadata"*. +The `acs` field should match the value you set in ADFS earlier. The `attributes_to_roles` is used to map attributes to the Teleport roles you just created. In our situation, we are mapping the *"Group"* attribute whose full @@ -181,7 +237,7 @@ The Web UI will now contain a new button: "Login with MS Active Directory". The the same as before: ```bsh -$ tsh --proxy=proxy.example.com login +$ tsh --proxy=teleport.example.com login ``` This command will print the SSO login URL and try to open it diff --git a/docs/pages/enterprise/sso/azuread.mdx b/docs/pages/enterprise/sso/azuread.mdx index 62c4871a9735b..70cca72f72974 100644 --- a/docs/pages/enterprise/sso/azuread.mdx +++ b/docs/pages/enterprise/sso/azuread.mdx @@ -33,7 +33,7 @@ The following steps configure an example SAML authentication connector matching ## Prerequisites -Before you get started you’ll need: +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 @@ -107,35 +107,104 @@ Before you get started you’ll need: type="warning" title="Important" > - This is a important document. Treat the Federation Metadata XML file as you would a password. + This is an important document. Treat the Federation Metadata XML file as you would a password. -## Create a SAML Connector +## Create a new Teleport role + +Create a Teleport role resource that will use external username data from the Azure AD connector to determine which Linux logins to allow on a host. -Now, create a SAML connector resource. Write the following to `azure-connector.yaml`: +Users with the following `dev` role are only allowed to log in to nodes with the `access: relaxed` Teleport label. They can log in as either `ubuntu` or a username that +arrives via the Azure AD connector. Users with this role cannot obtain admin access to Teleport. + +```yaml +kind: role +version: v5 +metadata: + name: dev +spec: + options: + max_session_ttl: 24h + allow: + logins: [ "{{external.username}}", ubuntu ] + node_labels: + access: relaxed +``` + +Replace `ubuntu` with the Linux login available on your servers. Create the role: + + +```code +$ tctl create dev.yaml +``` + +## Create & Test SAML Connector + +Use the [`tctl sso configure saml`](../../setup/reference/cli.mdx#tctl-sso-configure-saml) command to create SAML connector [resource](../../setup/reference/resources.mdx): + +```code +$ tctl sso configure saml -p azuread -e federationmedata.xml \ + -r http://schemas.microsoft.com/ws/2008/06/identity/claims/groups,,editor \ + -r http://schemas.microsoft.com/ws/2008/06/identity/claims/groups,,dev \ + | tee azure-connector.yaml +``` + +The resulting file should be similar to this: ```yaml kind: saml version: v2 metadata: # the name of the connector - name: azure-saml + name: azure spec: display: "Microsoft" # acs is the Assertion Consumer Service URL. This should be the address of # the Teleport proxy that your identity provider will communicate with. acs: https://teleport.example.com:3080/v1/webapi/saml/acs + audience: https://teleport.example.com:3080/v1/webapi/saml/acs + service_provider_issuer: https://teleport.example.com:3080/v1/webapi/saml/acs attributes_to_roles: - - {name: "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups", value: "", roles: ["editor"]} - - {name: "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups", value: "", roles: ["dev"]} + - name: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups + value: "" + roles: + - access + - name: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups + value: "" + roles: + - dev entity_descriptor: | ``` -Replace the `acs` field with your Teleport address, update the group IDs in the `attributes_to_roles` field with the actual Azure AD group ID values, and insert the downloaded Federation Metadata XML into the `entity_descriptor` field. +Note: +- The `acs` field will be automatically populated by `tctl sso configure saml` command by querying your Teleport cluster settings. If you have multiple Teleport proxies available, you can modify that field to point to a different one. +- Remember to update the group IDs in the `attributes_to_roles` field with the actual Azure AD group ID values. This can be done either by editing the file, or by modifying the command line and regenerating the file. +- The downloaded Federation Metadata XML will be automatically inserted into the `entity_descriptor` field. + +Before creating the connector, you should test it using [`tctl sso test`](../../setup/reference/cli.mdx#tctl-sso-test) command. This will run the SSO flow end-to-end: + +```code +$ tctl sso test azure-connector.yaml +``` + +Once the test is finished, a wealth of diagnostic information will be printed, including: +- SAML attributes; +- role mappings; +- effective roles of logged in user; +- encountered errors. + +You can also combine the commands into a pipeline: +```code +$ tctl sso configure saml -p azuread -e federationmedata.xml \ + -r http://schemas.microsoft.com/ws/2008/06/identity/claims/groups,,editor \ + -r http://schemas.microsoft.com/ws/2008/06/identity/claims/groups,,dev \ + | tee azure-connector.yaml \ + | tctl sso test +``` -Create the connector using `tctl`: +Once happy with the test results, create the connector using `tctl` tool: ```code $ tctl create azure-connector.yaml @@ -157,40 +226,15 @@ $ tctl create azure-connector.yaml ``` -## Create a new Teleport role - -Create a Teleport role resource that will use external username data from the Azure AD connector to determine which Linux logins to allow on a host. - -Users with the following `dev` role are only allowed to log in to nodes with the `access: relaxed` Teleport label. They can log in as either `ubuntu` or a username that -arrives via the Azure AD connector. Users with this role cannot obtain admin access to Teleport. - -```yaml -kind: role -version: v5 -metadata: - name: dev -spec: - options: - max_session_ttl: 24h - allow: - logins: [ "{{external.username}}", ubuntu ] - node_labels: - access: relaxed -``` - -Replace `ubuntu` with the Linux login available on your servers. -```code -$ tctl create dev.yaml -``` +## Validation -## Testing +The Web UI will now contain a new button: ![Login with Microsoft](../../../img/azuread/azure-11-loginwithmsft.png) - -The CLI is the same as before: +The CLI is the same as before, because we have [changed the defaults](#enable-default-saml-authentication): ```code $ tsh --proxy=proxy.example.com login ``` @@ -233,30 +277,30 @@ If you are modifying the existing connector, write the YAML to a file first: $ tctl get saml --with-secrets > azure-out.yaml ``` -You will notice that Teleport has generated a `signing_key_pair`. This key pair +Upon creation of SAML auth connector, Teleport will automatically fill in `signing_key_pair` if it is missing. This key pair is used to sign responses. ```yaml kind: saml +version: v2 metadata: name: azure-saml spec: + display: Microsoft acs: https://teleport.example.com/v1/webapi/saml/acs + audience: https://teleport.example.com/v1/webapi/saml/acs + service_provider_issuer: https://teleport.example.com/v1/webapi/saml/acs attributes_to_roles: - name: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups + value: "" roles: - - editor - access - - auditor - value: '*' - audience: https://teleport.example.com/v1/webapi/saml/acs - cert: "" - display: Microsoft + - name: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups + value: "" + roles: + - dev entity_descriptor: | Make sure to have the same indentation for all lines of the certificate and key, otherwise - Teleport will not parse the YAML file. + Teleport will not parse the YAML file. Alternatively, consider using `tctl sso configure saml` which handles this automatically. After your edits, the file will look like this: ```yaml kind: saml +version: v2 metadata: name: azure-saml spec: + display: Microsoft acs: https://teleport.example.com/v1/webapi/saml/acs + audience: https://teleport.example.com/v1/webapi/saml/acs + service_provider_issuer: https://teleport.example.com/v1/webapi/saml/acs attributes_to_roles: - name: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups + value: "" roles: - - editor - access - - auditor - value: '*' - audience: https://teleport.example.com/v1/webapi/saml/acs - cert: "" - display: Microsoft + - name: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups + value: "" + roles: + - dev entity_descriptor: | \ No newline at end of file From 104728b4c5146216689eabce07ea11b9361ed185 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Krzysztof=20Skrz=C4=99tnicki?= Date: Tue, 31 May 2022 13:46:18 +0200 Subject: [PATCH 34/40] Uniform titles for SSO guides. --- docs/pages/enterprise/sso.mdx | 6 +++--- docs/pages/enterprise/sso/adfs.mdx | 2 +- docs/pages/enterprise/sso/azuread.mdx | 6 +++--- docs/pages/enterprise/sso/gitlab.mdx | 6 +++--- docs/pages/enterprise/sso/google-workspace.mdx | 6 +++--- docs/pages/enterprise/sso/oidc.mdx | 6 +++--- docs/pages/enterprise/sso/okta.mdx | 6 +++--- docs/pages/enterprise/sso/one-login.mdx | 6 +++--- 8 files changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/pages/enterprise/sso.mdx b/docs/pages/enterprise/sso.mdx index f39a4dd231a8f..af98b66aeb38d 100644 --- a/docs/pages/enterprise/sso.mdx +++ b/docs/pages/enterprise/sso.mdx @@ -1,7 +1,7 @@ --- -title: SSO for SSH -description: How to set up single sign-on (SSO) for SSH using Teleport -h1: Single Sign-On (SSO) for SSH +title: SSO in Teleport +description: How to configure Teleport Single Sign-On +h1: Single Sign-On in Teleport --- Users of the Enterprise edition of Teleport can log in to servers, Kubernetes diff --git a/docs/pages/enterprise/sso/adfs.mdx b/docs/pages/enterprise/sso/adfs.mdx index 35a2265d40130..87d1ee6ebb8d7 100644 --- a/docs/pages/enterprise/sso/adfs.mdx +++ b/docs/pages/enterprise/sso/adfs.mdx @@ -1,6 +1,6 @@ --- title: SSO with Active Directory Federation Services -description: How to configure SSH access with Active Directory Federation Services using Teleport +description: How to configure Teleport Single Sign-On with Active Directory Federation Services h1: Single Sign-On with Active Directory Federation Services --- diff --git a/docs/pages/enterprise/sso/azuread.mdx b/docs/pages/enterprise/sso/azuread.mdx index 70cca72f72974..2af91dcd8aa74 100644 --- a/docs/pages/enterprise/sso/azuread.mdx +++ b/docs/pages/enterprise/sso/azuread.mdx @@ -1,7 +1,7 @@ --- -title: SSH Authentication with Active Directory (AD) on Azure -description: How to configure SSH access with Active Directory (AD) on Azure using Teleport -h1: SSH Authentication with Azure Active Directory (AD) +title: SSO with Active Directory (AD) on Azure +description: How to configure Teleport Single Sign-On with Active Directory (AD) on Azure +h1: Single Sign-On with Active Directory (AD) on Azure --- This guide will cover how to configure Microsoft Azure Active Directory to issue diff --git a/docs/pages/enterprise/sso/gitlab.mdx b/docs/pages/enterprise/sso/gitlab.mdx index e604c01593d3f..da1ea6c0b5c0b 100644 --- a/docs/pages/enterprise/sso/gitlab.mdx +++ b/docs/pages/enterprise/sso/gitlab.mdx @@ -1,7 +1,7 @@ --- -title: Authentication With GitLab as an SSO provider -description: How to configure Teleport access using GitLab for SSO -h1: Teleport SSO Authentication with GitLab +title: SSO with GitLab +description: How to configure Teleport Single Sign-On with GitLab +h1: Single Sign-On with GitLab --- ## How to use GitLab as a single sign-on (SSO) provider with Teleport diff --git a/docs/pages/enterprise/sso/google-workspace.mdx b/docs/pages/enterprise/sso/google-workspace.mdx index 63287a06af37f..ae2a666cbb854 100644 --- a/docs/pages/enterprise/sso/google-workspace.mdx +++ b/docs/pages/enterprise/sso/google-workspace.mdx @@ -1,7 +1,7 @@ --- -title: SSH Authentication With Google Workspace (G Suite) -description: How to configure SSH access with Google Workspace (formerly known as G Suite) using Teleport -h1: SSH Authentication with Google Workspace (G Suite) +title: SSO with Google Workspace (G Suite) +description: How to configure Teleport Single Sign-On with Google Workspace (G Suite) +h1: Single Sign-On with Google Workspace (G Suite) videoBanner: WTLWc6nnPfk --- diff --git a/docs/pages/enterprise/sso/oidc.mdx b/docs/pages/enterprise/sso/oidc.mdx index ced0cd4a6bbb0..f0ed092565917 100644 --- a/docs/pages/enterprise/sso/oidc.mdx +++ b/docs/pages/enterprise/sso/oidc.mdx @@ -1,7 +1,7 @@ --- -title: OAuth2 and OIDC authentication for SSH -description: How to configure SSH access with OAuth2 or OIDC (OpenID connect) using Teleport -h1: OAuth2 / OIDC Authentication for SSH +title: SSO with OAuth2 and OIDC +description: How to configure Teleport Single Sign-On with OAuth2 and OIDC +h1: Single Sign-On with OAuth2 and OIDC --- This guide will explain how to configure an SSO provider using [OpenID Connect](http://openid.net/connect/) diff --git a/docs/pages/enterprise/sso/okta.mdx b/docs/pages/enterprise/sso/okta.mdx index 64633da30c4f4..f5da81a2abf49 100644 --- a/docs/pages/enterprise/sso/okta.mdx +++ b/docs/pages/enterprise/sso/okta.mdx @@ -1,7 +1,7 @@ --- -title: SSH Authentication With Okta as an SSO provider -description: How to configure SSH access using Okta for SSO -h1: SSH Authentication with Okta +title: SSO with Okta +description: How to configure Teleport Single Sign-On with Okta +h1: Single Sign-On with Okta videoBanner: SM4Am-i8cj4 --- diff --git a/docs/pages/enterprise/sso/one-login.mdx b/docs/pages/enterprise/sso/one-login.mdx index 9093bd462dc18..ad56100f33cfe 100644 --- a/docs/pages/enterprise/sso/one-login.mdx +++ b/docs/pages/enterprise/sso/one-login.mdx @@ -1,7 +1,7 @@ --- -title: SSH Authentication with One Login as an SSO provider -description: How to configure SSH access using One Login as an SSO provider -h1: SSH Authentication with OneLogin +title: SSO with One Login +description: How to configure Teleport Single Sign-On with One Login +h1: Single Sign-On with One Login --- This guide will explain how to configure [OneLogin](https://www.onelogin.com/) to issue From a74a3bfc0e1af52220a3e3ec0d1a0257e61d762d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Krzysztof=20Skrz=C4=99tnicki?= Date: Tue, 31 May 2022 14:27:01 +0200 Subject: [PATCH 35/40] Reflect increased Teleport product scope. --- docs/pages/enterprise/sso/adfs.mdx | 2 +- docs/pages/enterprise/sso/azuread.mdx | 2 +- docs/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 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/pages/enterprise/sso/adfs.mdx b/docs/pages/enterprise/sso/adfs.mdx index 87d1ee6ebb8d7..193e42fcb1d50 100644 --- a/docs/pages/enterprise/sso/adfs.mdx +++ b/docs/pages/enterprise/sso/adfs.mdx @@ -7,7 +7,7 @@ h1: Single Sign-On with Active Directory Federation Services This guide will explain how to configure Active Directory Federation Services ([ADFS](https://en.wikipedia.org/wiki/Active_Directory_Federation_Services)) to be a single sign-on (SSO) provider to issue SSH credentials to specific groups of users. -When used in combination with role based access control (RBAC), it allows SSH administrators to +When used in combination with role based access control (RBAC), it allows administrators to define policies like: - Only members of "DBA" group can SSH into machines running PostgreSQL. diff --git a/docs/pages/enterprise/sso/azuread.mdx b/docs/pages/enterprise/sso/azuread.mdx index 2af91dcd8aa74..f53efdc61bec8 100644 --- a/docs/pages/enterprise/sso/azuread.mdx +++ b/docs/pages/enterprise/sso/azuread.mdx @@ -5,7 +5,7 @@ h1: Single Sign-On with Active Directory (AD) on Azure --- This guide will cover how to configure Microsoft Azure Active Directory to issue -SSH credentials to specific groups of users with a SAML Authentication Connector. When used in combination with role-based access control (RBAC), it allows SSH administrators to define policies like: +SSH credentials to specific groups of users with a SAML Authentication Connector. When used in combination with role-based access control (RBAC), it allows administrators to define policies like: - Only members of the "DBA" Azure AD group can SSH into machines running PostgreSQL. - Developers must never SSH into production servers. diff --git a/docs/pages/enterprise/sso/google-workspace.mdx b/docs/pages/enterprise/sso/google-workspace.mdx index ae2a666cbb854..d3df864cdda08 100644 --- a/docs/pages/enterprise/sso/google-workspace.mdx +++ b/docs/pages/enterprise/sso/google-workspace.mdx @@ -7,7 +7,7 @@ videoBanner: WTLWc6nnPfk This guide will explain how to configure [Google Workspace](https://workspace.google.com/) to be a single sign-on (SSO) provider to issue SSH credentials to specific groups of users. -When used in combination with role based access control (RBAC) it allows SSH administrators +When used in combination with role based access control (RBAC) it allows administrators to define policies like: - Only members of "DBA" Google group can SSH into machines running PostgreSQL. diff --git a/docs/pages/enterprise/sso/oidc.mdx b/docs/pages/enterprise/sso/oidc.mdx index f0ed092565917..d62f701ad3c5d 100644 --- a/docs/pages/enterprise/sso/oidc.mdx +++ b/docs/pages/enterprise/sso/oidc.mdx @@ -6,7 +6,7 @@ h1: Single Sign-On with OAuth2 and OIDC This guide will explain how to configure an SSO provider using [OpenID Connect](http://openid.net/connect/) (also known as OIDC) to issue SSH credentials to a specific groups of users. -When used in combination with role based access control (RBAC) it allows SSH +When used in combination with role based access control (RBAC) it allows administrators to define policies like: - Only members of "DBA" group can SSH into machines running PostgreSQL. diff --git a/docs/pages/enterprise/sso/okta.mdx b/docs/pages/enterprise/sso/okta.mdx index f5da81a2abf49..9bd6cbaa47891 100644 --- a/docs/pages/enterprise/sso/okta.mdx +++ b/docs/pages/enterprise/sso/okta.mdx @@ -9,7 +9,7 @@ videoBanner: SM4Am-i8cj4 This guide will cover how to configure [Okta](https://www.okta.com/) to issue SSH credentials to specific groups of users. When used in combination with role -based access control (RBAC), it allows SSH administrators to define policies +based access control (RBAC), it allows administrators to define policies like: - Only members of "DBA" group can SSH into machines running PostgreSQL. diff --git a/docs/pages/enterprise/sso/one-login.mdx b/docs/pages/enterprise/sso/one-login.mdx index ad56100f33cfe..87879311801ae 100644 --- a/docs/pages/enterprise/sso/one-login.mdx +++ b/docs/pages/enterprise/sso/one-login.mdx @@ -6,7 +6,7 @@ h1: Single Sign-On with One Login This guide will explain how to configure [OneLogin](https://www.onelogin.com/) to issue SSH credentials to specific groups of users. When used in combination with role -based access control (RBAC) it allows SSH administrators to define policies +based access control (RBAC) it allows administrators to define policies like: - Only members of "DBA" group can SSH into machines running PostgreSQL. From 7077a3e0cd13dd28e94f14bc4c6f6bc4a3a8d2ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Krzysztof=20Skrz=C4=99tnicki?= Date: Tue, 31 May 2022 15:58:20 +0200 Subject: [PATCH 36/40] Cosmetic changes to Okta guide. --- docs/pages/enterprise/sso/okta.mdx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/pages/enterprise/sso/okta.mdx b/docs/pages/enterprise/sso/okta.mdx index 9bd6cbaa47891..007b203f13c02 100644 --- a/docs/pages/enterprise/sso/okta.mdx +++ b/docs/pages/enterprise/sso/okta.mdx @@ -5,7 +5,7 @@ h1: Single Sign-On with Okta videoBanner: SM4Am-i8cj4 --- -## How to use Okta as a single sign-on (SSO) provider for SSH +## How to use Okta as a single sign-on (SSO) provider This guide will cover how to configure [Okta](https://www.okta.com/) to issue SSH credentials to specific groups of users. When used in combination with role @@ -14,6 +14,7 @@ like: - Only members of "DBA" group can SSH into machines running PostgreSQL. - Developers must never SSH into production servers. +- ... and many others. Date: Tue, 31 May 2022 15:58:53 +0200 Subject: [PATCH 37/40] Extend `tctl sso test` exapmles. --- docs/pages/setup/reference/cli.mdx | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/pages/setup/reference/cli.mdx b/docs/pages/setup/reference/cli.mdx index c1ddb900f6326..a164b4cddbd8d 100644 --- a/docs/pages/setup/reference/cli.mdx +++ b/docs/pages/setup/reference/cli.mdx @@ -1352,6 +1352,19 @@ The pipeline may also utilise `tee` to capture the connector generated with `tct $ tctl sso configure ... | tee connector.yaml | tctl sso test ``` +You can test existing auth connector by combining the command with `tctl get`: + +```bsh +$ tctl get saml/your-connector-name --with-secrets | tctl sso test +```` + + + Make sure to include `--with-secrets` flag, or the exported auth connector will not be testeable. + + ### tctl sso configure github Configure Github auth connector. From 83738eccd323e820756c919054fc359f75264d7a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Krzysztof=20Skrz=C4=99tnicki?= Date: Thu, 2 Jun 2022 13:32:26 +0200 Subject: [PATCH 38/40] Add a notice about required permissions. --- docs/pages/setup/reference/cli.mdx | 37 ++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/docs/pages/setup/reference/cli.mdx b/docs/pages/setup/reference/cli.mdx index a164b4cddbd8d..09d24e788abad 100644 --- a/docs/pages/setup/reference/cli.mdx +++ b/docs/pages/setup/reference/cli.mdx @@ -1319,6 +1319,43 @@ The test process will modify the list of configured auth connectors or result in $ tctl [] sso test [] ``` + + To use this command, you must have access to `github_request`, `oidc_request`, `saml_request` resources (depending on the type of connector being tested). + + If you receive "permission denied" error, modify one of your roles to allow access to: + +```yaml + - resources: + - github_request + verbs: + - list + - create + - read + - update + - delete + - resources: + - oidc_request + verbs: + - list + - create + - read + - update + - delete + - resources: + - saml_request + verbs: + - list + - create + - read + - update + - delete +``` + + + #### Arguments - `[]` Connector resource definition file. Optional. Empty for stdin. From 8244e9cb305e0de2e90707f74271a5d8f10e96eb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Krzysztof=20Skrz=C4=99tnicki?= Date: Thu, 2 Jun 2022 13:41:34 +0200 Subject: [PATCH 39/40] Gitlab guide changes. --- docs/pages/enterprise/sso/gitlab.mdx | 122 ++++++++++++++++----------- 1 file changed, 73 insertions(+), 49 deletions(-) diff --git a/docs/pages/enterprise/sso/gitlab.mdx b/docs/pages/enterprise/sso/gitlab.mdx index da1ea6c0b5c0b..af41108f105bf 100644 --- a/docs/pages/enterprise/sso/gitlab.mdx +++ b/docs/pages/enterprise/sso/gitlab.mdx @@ -49,7 +49,7 @@ like: You should have at least one group configured in GitLab to map to Teleport roles. In this example we use the names `gitlab-dev` and `gitlab-admin`. Assign users to each of these groups. -1. Create a Application in one of your Groups that will allow using GitLab as a OAuh provider to Teleport. +1. Create a Application in one of your Groups that will allow using GitLab as a OAuth provider to Teleport. Navigate to "Settings >> Applications" menu for your group. Settings @@ -71,53 +71,10 @@ If you are self hosting that is likely another local address. ## Configure Teleport -### Create a OIDC Connector +### Create Teleport Roles -Create a OIDC connector [resource](../../setup/reference/resources.mdx): -Replace the Application ID and the Secret with the values from GitLab. - -```yaml -kind: oidc -metadata: - name: gitlab -spec: - claims_to_roles: - - claim: groups - roles: - - admin - value: gitlab-admin - - claim: groups - roles: - - dev - value: gitlab-dev - client_id: Application_ID - client_secret: Secret - display: GitLab - issuer_url: https://gitlab.com - prompt: "none" - redirect_url: https://teleport.example.com:3080/v1/webapi/oidc/callback - scope: - - email -version: v2 -``` - - - The `prompt` value must be `none`. Setting to `none` means Teleport will not send this as a parameter sending the `select_account` parameter will result in an error from GitLab. - - -Create the connector using `tctl` tool: - -```bsh -$ tctl create oidc-connector.yaml -``` - -## Create Teleport Roles - -We are going to create 2 roles, privileged role admin who is able to login as -root and is capable of administrating the cluster and non-privileged dev. +We are going to create 2 roles, privileged role `admin` which is able to login as +root and is capable of administrating the cluster and non-privileged role `dev`. ```yaml kind: role @@ -166,7 +123,74 @@ $ tctl create admin.yaml $ tctl create dev.yaml ``` -## Testing +### Create & Test OIDC Connector + +Create a OIDC connector [resource](../../setup/reference/resources.mdx). + +Use the [`tctl sso configure oidc`](../../setup/reference/cli.mdx#tctl-sso-configure-oidc) command to do so: + +```bsh +$ tctl sso configure oidc --preset gitlab --secret SECRET --id CLIENT_ID --scope email \ + -r groups,gitlab-admin,access \ + -r groups,gitlab-dev,editor \ + | tee gitlab-connector.yaml +``` + +Replace the with `CLIENT_ID` (= `Application ID`) and `Secret` with previously stored values from GitLab configuration. + +The resulting file should be similar to this: + +```yaml +kind: oidc +metadata: + name: gitlab +spec: + claims_to_roles: + - claim: groups + value: gitlab-admin + roles: + - admin + - claim: groups + value: gitlab-dev + roles: + - dev + client_id: CLIENT_ID + client_secret: SECRET + display: Gitlab + issuer_url: https://gitlab.com + prompt: none + redirect_url: https://teleport.example.com:3080/v1/webapi/oidc/callback + scope: + - email +version: v3 +``` + + + The `prompt` value must be set to one of: `none`, `login`, `consent`. Doing otherwise will result in an error from GitLab. + + +Create the connector using `tctl` tool: + +```bsh +$ tctl create gitlab-connector.yaml +``` + +Before creating the connector, you should test it using [`tctl sso test`](../../setup/reference/cli.mdx#tctl-sso-test) command: + +```bsh +$ tctl sso test gitlab-connector.yaml +``` + +You can also combine the commands into a pipeline: + +```bsh +$ tctl sso configure oidc ... | tee gitlab-connector.yaml | tctl sso test +``` + +## Validation The Web UI will now contain a new button: "Login with GitLab". The CLI is the same as before: @@ -190,7 +214,7 @@ automatically in a browser). type="note" title="IMPORTANT" > - Teleport only supports sending party initiated flows for OIDC Connect. This + Teleport only supports sending party-initiated flows for OIDC Connect. This means you can not initiate login from your identity provider, you have to initiate login from either the Teleport Web UI or CLI. From f29558453c544cce61366d52d7e80c76266e3a38 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Krzysztof=20Skrz=C4=99tnicki?= Date: Thu, 2 Jun 2022 14:09:33 +0200 Subject: [PATCH 40/40] Changes from review. --- docs/pages/setup/admin/github-sso.mdx | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/pages/setup/admin/github-sso.mdx b/docs/pages/setup/admin/github-sso.mdx index 06b630639225c..810635a4f7c1b 100644 --- a/docs/pages/setup/admin/github-sso.mdx +++ b/docs/pages/setup/admin/github-sso.mdx @@ -34,11 +34,9 @@ Instructions for creating a GitHub OAuth app are available here: [Creating an OAuth App](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) -## Step 2/5. Define the GitHub authentication connector +## Step 2/5. Define a GitHub authentication connector -Define a GitHub authentication connector by creating a file called `github.yaml`. - -You can do it with the following command: +Define a GitHub authentication connector by running the following command: ```code $ tctl sso configure github --id --secret -r octocats,admins,access | tee github.yaml @@ -70,15 +68,15 @@ spec: - access ``` -The values of `client_id`, `client_secret` come from the GitHub OAuth App you created earlier. `redirect_url` is automatically configured by [`tctl sso configure github`](../reference/cli.mdx#tctl-sso-configure-github) based on the settings of Teleport cluster. +The values of `client_id` and `client_secret` come from the GitHub OAuth App you created earlier. `redirect_url` was automatically configured based on the settings of your Teleport cluster when you ran [`tctl sso configure github`](../reference/cli.mdx#tctl-sso-configure-github). - The flag `--teams-to-logins` (`-r` for short) can be repeated multiple times with each repetition creating additional mapping entry. + The `--teams-to-logins` flag (`-r` for short) can be repeated multiple times. Each repetition will create an additional entry in the `teams_to_logins` mapping of your GitHub authentication connector. - If multiple roles are desired, they can be listed separated by commas: `-r org,team,role1,role2,role3,...`. + To map a GitHub team to multiple Teleport roles, list these roles after the name of the GitHub team, separated by commas: `-r org,team,role1,role2,role3,...`. Teleport will request only the `read:org` OAuth scope. Read more about OAuth scopes in [GitHub's documentation](https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/).