From 477d6987601d0aac592080879e3fa6bc9df6257a Mon Sep 17 00:00:00 2001 From: Edoardo Spadolini Date: Wed, 6 Apr 2022 18:23:49 +0200 Subject: [PATCH] Document limitations with the Google OIDC connector and transitive group memberships (#11422) * Document limitations with Google OIDC * Reorganize the Google OIDC API instructions - Organize the Google OIDC guide into steps. This required removing the header from the oidcauthentication.mdx partial. - Use H3s for the "Configure Google Workspace" H2 - Add an explanation of the Workspace APIs * Fix inaccuracies * PR suggestions Co-authored-by: Paul Gottschling --- docs/pages/enterprise/sso/gitlab.mdx | 2 + .../pages/enterprise/sso/google-workspace.mdx | 254 ++++++++++++++---- docs/pages/enterprise/sso/oidc.mdx | 2 + .../enterprise/oidcauthentication.mdx | 2 - 4 files changed, 203 insertions(+), 57 deletions(-) diff --git a/docs/pages/enterprise/sso/gitlab.mdx b/docs/pages/enterprise/sso/gitlab.mdx index c5061fe4f3fe0..f1e5b93aec06a 100644 --- a/docs/pages/enterprise/sso/gitlab.mdx +++ b/docs/pages/enterprise/sso/gitlab.mdx @@ -22,6 +22,8 @@ like: This guide requires a commercial edition of Teleport. +## 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 e2126c6836c96..a094dee2c4e0f 100644 --- a/docs/pages/enterprise/sso/google-workspace.mdx +++ b/docs/pages/enterprise/sso/google-workspace.mdx @@ -16,86 +16,222 @@ to define policies like: - Developers must never SSH into production servers. - ... and many others. - - This guide requires an enterprise version of Teleport. - -(!docs/pages/includes/enterprise/oidcauthentication.mdx!) + This guide requires Teleport Cloud or Teleport Enterprise. + + ## Prerequisites 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/)). + + + +- 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. -## Configuring Google Workspace - -The setup will consist of creating a new project on Google Cloud Platform, -configuring its OAuth consent screen, creating an OAuth client ID to allow -Google Workspace users to log in to your Teleport cluster, and creating a service -account for Teleport to fetch the additional Google Groups data. - -The Google Workspace integration in Teleport supports mapping roles to the -groups that a user belongs to both directly and indirectly (by virtue of -belonging to a group that belongs to another group). However, fetching the -complete list of so-called *transitive* groups requires a Google Workspace -Enterprise subscription or a Cloud Identity Premium subscription (see the Google Cloud [API -docs](https://cloud.google.com/identity/docs/reference/rest/v1/groups.memberships/searchTransitiveGroups) -for more info). - -As an alternative that works with all Google Workspace accounts, -fetching just the groups with direct membership is also supported. The preferred -behavior is selected depending on the OAuth scopes granted to the service -account associated with the connector. - -
-Teleport versions prior to 8.1.2 only support fetching groups with direct -membership with the -`https://www.googleapis.com/auth/admin.directory.group.readonly` scope. -Furthermore, the list of groups is filtered by domain name, and any group registered -on a different domain or subdomain than the user's will be ignored. - -To avoid -unexpected changes in how access is granted to users for preexisting SSO -connectors, this behavior will persist even after upgrading, until the `version` -field of the [connector resource](#create-an-oidc-connector) is changed from `v2` -to `v3`. -
- -- [Create a new project](https://console.cloud.google.com/projectselector2/apis/dashboard). +## Step 1/4. Enable default OIDC authentication + +(!docs/pages/includes/enterprise/oidcauthentication.mdx!) + +## Step 2/4. Configure Google Workspace + +The setup will consist of: + +- Determining whether your Google Workspace plan is correct for your Teleport + usage +- Creating a new project on Google Cloud Platform +- Configuring OAuth consent for the new project +- Creating an OAuth client ID to allow Google Workspace users to log in to your + Teleport cluster +- Creating a service account for Teleport to fetch the additional Google Groups + data. + +### Ensure your Google Workspace plan is correct + +Teleport's Google Workspace integration works differently depending on your +Google Workspace plan. In this section, we will explain how to determine if +Teleport supports your current Google Workspace setup. + +#### How Google Workspace APIs differ by service level + +In Google Workspace, **transitive group membership** takes place when a user is +a member of one group by virtue of being in another group. This happens when a child +group is nested within a parent group, so that a member of a child group is also +a member of the parent group. + +Google Workspace service accounts can determine whether a user has a transitive +membership to a specific group by calling methods within the Google Workspace +**Cloud Identity API**. These API methods are only usable for users belonging to +specific Google Workspace plans: + +- Enterprise Standard +- Enterprise Plus +- Enterprise for Education +- Cloud Identity Premium + +The Google Workspace **Directory API** allows administrators to list users and +groups in their Google Workspace domain, but does not enable them to query +transitive group memberships. The Directory API is available for all Google +Workspace plans. + +#### How Teleport uses Google Workspace APIs + +Teleport's OIDC connector uses Google Workspace's APIs differently depending +on the resource version. + +We will show you how to configure the connector later in the +guide, but for now, you should ensure that your Google Workspace plan allows you +to use Teleport as you intend. + +We currently support OIDC connector versions `v2` and `v3`. + + + +Teleport versions prior to 8.1.2 only support `v2` of the OIDC connector. + + + + + + +The OIDC connector maps a user's roles to the Google Workspace groups they +belong to. + +In order to list a user's Google Workspace groups, Teleport will first attempt to +fetch credentials for calling Cloud Identity API methods, then use these +credentials to query a user's transitive group memberships. + +If these credentials do not exist, Teleport will fetch credentials for the +Directory API instead, and will use this API to list the user's groups in your +entire Google Workspace account. Groups that the user belongs to that are +external to the workspace will not be listed. + + + + +The OIDC connector maps a user's roles to the Google Workspace groups they belong to. + +If these credentials do not exist, Teleport will fetch credentials for the +Directory API instead, and will use this API to list the user's groups within +your Google Workspace domain. Any group registered on a different domain or +subdomain than the user's will be ignored. + + + + +#### How to check your current plan + +To troubleshoot whether your Google Workspace plan supports querying transitive +group memberships, you can visit the +[Groups Inspection](https://admin.google.com/ac/groupsinspection) page in the +Google Admin Console, which relies on the Cloud Identity API. + +If your Google Workspace plan does not support the Cloud Identity API, you must +ensure that your RBAC does not depend on transitive group memberships. + +When querying transitive group memberships, we recommend blocking access to +external groups at the workspace level (following [these +instructions](https://support.google.com/a/answer/9468710)), as membership in +any group that the service account doesn't have full visibility on (including +all groups external to the workspace) will prevent users from logging in. + +### Create a new project + +In the GCP console, choose to [Create a new project](https://console.cloud.google.com/projectselector2/apis/dashboard). + ![creation of a Google Cloud Platform project](../../../img/googleoidc/new-project.png) -- [Configure the OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent): +### Configure OAuth consent - Select "Internal" as your User Type. - ![configuration of the OAuth consent screen](../../../img/googleoidc/consent-screen-1.png) +On the +[OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent) +page of the GCP console, select"Internal" as your User Type. + +![configuration of the OAuth consent screen](../../../img/googleoidc/consent-screen-1.png) Configure the appearence of your connector by picking a visible name, user support email, etc. - - Select the `.../auth/userinfo.email` and `openid` scopes. + +### Select scopes + +Select the `.../auth/userinfo.email` and `openid` scopes. ![select email and openid scopes](../../../img/googleoidc/consent-screen-2.png) -- Enable the [Cloud Identity API](https://console.cloud.google.com/apis/library/cloudidentity.googleapis.com) or the [Admin SDK API](https://console.cloud.google.com/apis/library/admin.googleapis.com) for transitive and direct group membership, respectively. Enabling both is fine. +Enable the +[Cloud Identity API](https://console.cloud.google.com/apis/library/cloudidentity.googleapis.com) +or the +[Admin SDK API](https://console.cloud.google.com/apis/library/admin.googleapis.com) +for transitive and direct group membership, respectively. Enabling both is fine. + + + +Your Google Workspace account must enable support for the API you choose to use. + +Please consult the documentation for your chosen API to ensure that you have the +correct Google Workspace plan. -- [Create an OAuth client ID](https://console.cloud.google.com/apis/credentials/oauthclient): + + +### Create an OAuth client ID + +In the [Create an OAuth client ID](https://console.cloud.google.com/apis/credentials/oauthclient) page of the GCP console, select "Web application" as the Application type, pick a name, then add the following as an authorized redirect URI. + +```txt +https://
:3080/v1/webapi/oidc/callback +``` - Select "Web application" as the Application type, pick a name, then add `https://
:3080/v1/webapi/oidc/callback` as an authorized redirect URI. ![OAuth client ID creation](../../../img/googleoidc/clientid-creation.png) Copy the Client ID and Client Secret from the next screen or by clicking "Download OAuth client". ![OAuth client data](../../../img/googleoidc/clientid-data.png) -- [Create a service account](https://console.cloud.google.com/iam-admin/serviceaccounts/create): +### Create a service account - Pick a name for your service account. Leave project access grants and user access grants empty. +On the [Create a service account](https://console.cloud.google.com/iam-admin/serviceaccounts/create) page, pick a name for your service account. Leave project access grants and user access grants empty. ![service account creation](../../../img/googleoidc/serviceacct-creation.png) - + Click the newly-created account to view its details, and copy the Unique ID for later. ![service account unique ID](../../../img/googleoidc/serviceacct-uniqueid.png) @@ -107,7 +243,9 @@ to `v3`. Teleport requires the service account JSON to be available to all Teleport Auth Server hosts when deploying Teleport in a High Availability configuration. Unless you paste the JSON into the OIDC Connector configuration, you will need to upload the JSON file to all Auth Server hosts. -- Configure [domain-wide +### Configure domain-wide delegation + +Configure [domain-wide delegation](https://admin.google.com/ac/owl/domainwidedelegation) for your newly-created service account: @@ -121,7 +259,7 @@ to `v3`. fetch both direct and indirect groups or just direct groups, respectively. -## Create an OIDC connector +## Step 3/4. 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. @@ -179,7 +317,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`. -## Testing +## Step 4/4. 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: @@ -234,3 +372,9 @@ Example of a user being denied because the role `clusteradmin` wasn't set up. ``` + +## Further reading + +- [Google Workspace Cloud Identity API](https://cloud.google.com/identity) +- [Google Workspace Directory API](https://developers.google.com/admin-sdk/directory) +- [How nested Google Workspace groups work](https://support.google.com/a/answer/167100?hl=en) diff --git a/docs/pages/enterprise/sso/oidc.mdx b/docs/pages/enterprise/sso/oidc.mdx index 59ab7f1426193..e6b5cca9ae291 100644 --- a/docs/pages/enterprise/sso/oidc.mdx +++ b/docs/pages/enterprise/sso/oidc.mdx @@ -20,6 +20,8 @@ administrators to define policies like: This guide requires an Enterprise edition of Teleport. +## 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 e31838d1333a0..1168ea91ace0f 100644 --- a/docs/pages/includes/enterprise/oidcauthentication.mdx +++ b/docs/pages/includes/enterprise/oidcauthentication.mdx @@ -1,5 +1,3 @@ -## Enable default OIDC authentication - 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.