diff --git a/docs/img/sso/googleoidc/consent-screen-2.png b/docs/img/sso/googleoidc/consent-screen-2.png deleted file mode 100644 index b0b63a948abad..0000000000000 Binary files a/docs/img/sso/googleoidc/consent-screen-2.png and /dev/null differ diff --git a/docs/img/sso/googleoidc/create-oauth-client-id.png b/docs/img/sso/googleoidc/create-oauth-client-id.png index 972d6343429f2..031959fdfc315 100644 Binary files a/docs/img/sso/googleoidc/create-oauth-client-id.png and b/docs/img/sso/googleoidc/create-oauth-client-id.png differ diff --git a/docs/img/sso/googleoidc/google-create-credentials.png b/docs/img/sso/googleoidc/google-create-credentials.png new file mode 100644 index 0000000000000..086026e177baa Binary files /dev/null and b/docs/img/sso/googleoidc/google-create-credentials.png differ diff --git a/docs/img/sso/googleoidc/google-new-project.png b/docs/img/sso/googleoidc/google-new-project.png new file mode 100644 index 0000000000000..54904e1a7060f Binary files /dev/null and b/docs/img/sso/googleoidc/google-new-project.png differ diff --git a/docs/img/sso/googleoidc/google-oauth-consent.png b/docs/img/sso/googleoidc/google-oauth-consent.png new file mode 100644 index 0000000000000..f28a0766d8576 Binary files /dev/null and b/docs/img/sso/googleoidc/google-oauth-consent.png differ diff --git a/docs/img/sso/googleoidc/google-oauth.png b/docs/img/sso/googleoidc/google-oauth.png new file mode 100644 index 0000000000000..331f63aff1272 Binary files /dev/null and b/docs/img/sso/googleoidc/google-oauth.png differ diff --git a/docs/img/sso/googleoidc/google-service-account.png b/docs/img/sso/googleoidc/google-service-account.png new file mode 100644 index 0000000000000..9899a873a1232 Binary files /dev/null and b/docs/img/sso/googleoidc/google-service-account.png differ diff --git a/docs/img/sso/googleoidc/oauth-client-id-and-secret.png b/docs/img/sso/googleoidc/oauth-client-id-and-secret.png new file mode 100644 index 0000000000000..ed1d9d4517085 Binary files /dev/null and b/docs/img/sso/googleoidc/oauth-client-id-and-secret.png differ diff --git a/docs/img/sso/googleoidc/redirect-uri.png b/docs/img/sso/googleoidc/redirect-uri.png new file mode 100644 index 0000000000000..9985b8b6b3912 Binary files /dev/null and b/docs/img/sso/googleoidc/redirect-uri.png differ diff --git a/docs/img/sso/googleoidc/select-scopes.png b/docs/img/sso/googleoidc/select-scopes.png new file mode 100644 index 0000000000000..efcb5466d4d0e Binary files /dev/null and b/docs/img/sso/googleoidc/select-scopes.png differ diff --git a/docs/img/sso/googleoidc/service-account-keys.png b/docs/img/sso/googleoidc/service-account-keys.png new file mode 100644 index 0000000000000..e300da9444e73 Binary files /dev/null and b/docs/img/sso/googleoidc/service-account-keys.png differ diff --git a/docs/img/sso/googleoidc/service-account-unique-id.png b/docs/img/sso/googleoidc/service-account-unique-id.png new file mode 100644 index 0000000000000..4398fc676b1ef Binary files /dev/null and b/docs/img/sso/googleoidc/service-account-unique-id.png differ diff --git a/docs/img/sso/googleoidc/serviceacct-key.png b/docs/img/sso/googleoidc/serviceacct-key.png index 2791620e3d07b..61e462d3c0ca3 100644 Binary files a/docs/img/sso/googleoidc/serviceacct-key.png and b/docs/img/sso/googleoidc/serviceacct-key.png differ diff --git a/docs/img/sso/googleoidc/serviceacct-uniqueid.png b/docs/img/sso/googleoidc/serviceacct-uniqueid.png deleted file mode 100644 index a04d789860bb4..0000000000000 Binary files a/docs/img/sso/googleoidc/serviceacct-uniqueid.png and /dev/null differ diff --git a/docs/pages/access-controls/sso/google-workspace.mdx b/docs/pages/access-controls/sso/google-workspace.mdx index 37b3729c79190..89a72a24c778d 100644 --- a/docs/pages/access-controls/sso/google-workspace.mdx +++ b/docs/pages/access-controls/sso/google-workspace.mdx @@ -4,228 +4,305 @@ description: How to configure Teleport access with Google Workspace (formerly kn 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 Teleport credentials to specific -groups of users. When used in combination with role-based access control (RBAC) -it allows Teleport administrators to define policies like: +This guide explains how to configure [Google Workspace](https://workspace.google.com/) +to be a single sign-on (SSO) provider that issues Teleport credentials to specific +groups of users. When you use Google Workspace in combination with Teleport role-based +access control (RBAC), you can define policies like the following: - Only members of the "DBA" Google group can connect to PostgreSQL databases. -- Developers must never SSH into production servers. +- Developers must never use SSH to access production servers. ## Prerequisites -Before you get started you’ll need: +Before you get started, verify the following: -- 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. +- You have a Google Workspace super administrator account. + As a best practice, you should set up a separate account that requires multifactor + authentication to perform administrative actions. In most cases, you should avoid + granting your own sign-in user account elevated administrative privileges. -(!docs/pages/includes/commercial-prereqs-tabs.mdx!) +- You can sign up for Google Cloud and create a Google Cloud project. + Note that this guide doesn't require using any paid Google Cloud services. + +- You can set up Google Workspace groups. + +- You have a Teleport role with permission to maintain `oidc` resources. + This permission is available in the preset `editor` role. + +- You have a Teleport cluster, Enterprise edition, and command-line tools. + + (!docs/pages/includes/commercial-prereqs-tabs.mdx!) - (!docs/pages/includes/tctl.mdx!) ## Step 1/4. Configure Google Workspace -The setup will consist of: +The following steps are required to configure Google Workspace to work with Teleport: -- 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. +- Review your Google Workspace edition to determine how it integrates with Teleport. +- Create a new project on the Google Cloud Platform. +- Configure OAuth consent for the new project. +- Enable the required APIs. +- Create an OAuth client ID to allow Google Workspace users to log in to your Teleport cluster. +- Create a service account for Teleport to access additional Google Groups information. +- Configure domain-wide delegation for the service account. -### Ensure your Google Workspace plan is correct +### Review your Google Workspace edition -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. +Google Workspace is available in multiple editions with different features and capabilities +for individuals and organizations. Because of differences between Google Workspace editions, +there are fundamental differences in how Teleport integrates with Google Workspace depending on +the Google Workspace edition you use. -#### How Google Workspace APIs differ by service level +Some editions of Google Workspace provide **transitive group membership**. +With transitive group membership, a user can be a member of one group by virtue of being in +another group. For example, if there is a child group nested within a parent group, every +member of the child group is also a member of the parent group. Teleport can support both +direct group membership and transitive group membership, but does so using different methods. -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 editions and API Google Workspace service accounts can determine whether a user has a transitive -membership to a specific group by calling methods within the Google Workspace +membership in a specific group by calling methods in 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 +specific Google Workspace editions. 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. +Workspace editions. #### How Teleport uses Google Workspace APIs -Teleport's OIDC connector uses Google Workspace's APIs differently depending -on the resource version. +The Teleport OIDC connector uses the Google Workspace APIs to map Google Workspace +group members to the Teleport roles they belong to. -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. +To list a user's Google Workspace groups, Teleport first attempts to +get credentials by calling Cloud Identity API methods. If successful, Teleport uses +the credentials to query a user's transitive group memberships. -We currently support version `v3` of the OIDC connector. The OIDC connector maps a -user's roles to the Google Workspace groups they belong to. +If the credentials don't exist, Teleport gets credentials by calling +Directory API methods. Teleport then uses the Directory API to list the +user's groups in the entire Google Workspace for your organization. +Groups that the user belongs to that are external to the workspace aren't listed. -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. +#### How to check your current edition -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. +To determine whether your Google Workspace edition supports querying transitive +group memberships: -#### How to check your current plan +1. Open [Inspect Groups](https://admin.google.com/ac/groupsinspection) +in the Google Workspace Admin Console. -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. Select "List all -groups for a member" and "Include external groups" to test. + Group inspection relies on the Cloud Identity API. + +1. Select **List all groups for a member** and **Include external groups**. + + If your Google Workspace edition supports the Cloud Identity API, you should + block access to external groups at the workspace level as described in [Allow or block + access to external groups](https://support.google.com/a/answer/9468710). Otherwise, + membership in any group external to the workspace will prevent users from signing in. + + If your Google Workspace edition doesn't support the Cloud Identity API, you must + ensure that your role-based access controls don't depend on transitive group memberships. -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. +### Create a new project -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. +If you want to add single sign-on for Teleport to an existing Google Cloud project, you can +select that project in the Google Cloud console and skip this step. If you don't have a project +or want to create a new project specifically for Teleport, you can go directly to the +Enabled APIs & Service [project selector dashboard](https://console.cloud.google.com/projectselector2/apis/dashboard) +to create one. -### Create a new project +To create a new project: -In the GCP console, choose the project dropdown menu, and [create a new project](https://console.cloud.google.com/projectselector2/apis/dashboard). +1. Open the Google Cloud console. - ![creation of a Google Cloud Platform project](../../../img/sso/googleoidc/new-project.png) +1. In the Google Cloud console navigation menu, click **APIs & Services**. + +1. In **Enabled APIs and services**, click the project selector, then click **New Project**. + If there are no projects to select in the dashboard, click **Create Project**. + + ![Create or select a project](../../../img/sso/googleoidc/google-new-project.png) + +1. Type a Project name and select an organization and a location for the project, then +click **Create**. ### Configure OAuth consent -On the -[OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent) -page of the GCP console, select"Internal" as your User Type. +To configure OAuth consent for the new project: + +1. In the Google Cloud console sidebar, click **OAuth consent screen**. -![configuration of the OAuth consent screen](../../../img/sso/googleoidc/consent-screen-1.png) +1. Select **Internal** as the User Type, then click **Create**. + + ![Select Internals](../../../img/sso/googleoidc/google-oauth-consent.png) -On the next page, configure the appearance of your connector by picking a -visible name, user support email, etc. +1. Configure the OAuth client consent information by doing the following: + + - Type an application name. + - Select a user or group to receive email messages from users about their OAuth consent. + - Set other application options, as needed. + - Provide the email address of the developer to contact if there are changes to the project. -### Select scopes +1. Click **Save and continue**. -On the next page, click on **ADD OR REMOVE SCOPES**. -Select the `.../auth/userinfo.email` and `openid` scopes. +1. Click **Add or remove scopes**. -![select email and openid scopes](../../../img/sso/googleoidc/consent-screen-2.png) +1. Select **.../auth/userinfo.email** and **openid** scopes, then click **Update**. -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. +1. Click **Save and continue**. - +1. Review the information on the Summary page, then click **Back to dashboard**. -Your Google Workspace account must enable support for the API you choose to use. +### Enable the required APIs -Please consult the documentation for your chosen API to ensure that you have the -correct Google Workspace plan. +To enable required APIs for the OAuth client: - +1. Select [Admin SDK API](https://console.cloud.google.com/apis/library/admin.googleapis.com) +in the API Library, then click **Enable** to support direct group membership. +1. Select [Cloud Identity API](https://console.cloud.google.com/apis/library/cloudidentity.googleapis.com) +in the API Library, then click **Enable** to support transitive group membership. + +You can enable one or both API libraries. +However, your Google Workspace edition must support the API you choose to use. +Consult the documentation for the API library to ensure that you have a +supported Google Workspace edition. ### Create an OAuth client ID -Under **Credentials**, select **CREATE CREDENTIALS**, then **OAuth client ID**: +To create an OAuth client identifier: + +1. In the Google Cloud console sidebar, click **APIs & Services**. -![Create an OAuth Client ID](../../../img/sso/googleoidc/create-oauth-client-id.png) +1. In the APIs & Services sidebar, click **Credentials**. -Select "Web application" as the Application type, pick a name, then set the -redirect URI based on the address of your Teleport Proxy Service or cloud tenant: -`/v1/webapi/oidc/callback` +1. Click **Create credentials** to display a list of the credentials you can create. + + ![Create credentials](../../../img/sso/googleoidc/google-create-credentials.png) -![OAuth client ID creation](../../../img/sso/googleoidc/clientid-creation.png) +1. Select **OAuth client ID**. -Copy the Client ID and Client Secret from the next screen or click **DOWNLOAD JSON**: +1. Select **Web application** as the Application type, and type a name for the application. -![OAuth client data](../../../img/sso/googleoidc/clientid-data.png) +1. Under Authorized redirect URIs, click **Add URI**. + +1. Set the redirect URI to the address of your Teleport cluster, then add +`/v1/webapi/oidc/callback` to the URI. + + ![OAuth client ID creation](../../../img/sso/googleoidc/redirect-uri.png) + +1. Click **Create**. + +1. Copy the **Client ID** and **Client secret** from the OAuth client created or click **Download JSON** +to save this information, then click **OK**. + + If you choose to save the client identifier and client secret by clicking **Download JSON**, + be aware that this JSON file isn't the one used to handle the credentials for authentication. + A second JSON file is generated when you create the service account for the OAuth client. + + For example: + + ![OAuth client data](../../../img/sso/googleoidc/oauth-client-id-and-secret.png) ### Create a service account -From the GCP **IAM & Admin** menu select **Service Accounts**. From the kebab -menu click **CREATE SERVICE ACCOUNT**: +To create a service account: -![Create a service account](../../../img/sso/googleoidc/create-service-account.png) +1. In the Google Cloud console sidebar, click **IAM & admin**, then select **Service Accounts**. -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. +1. Click **Create service account**. -![service account creation](../../../img/sso/googleoidc/serviceacct-creation.png) +1. Type a name for your service account and, optionally, a description of what the service account is for. + +1. Click **Create and continue**, then click **Done**. -Click the newly-created account to view its details, and copy the Unique ID for later. + ![Create the service account](../../../img/sso/googleoidc/google-service-account.png) -![service account unique ID](../../../img/sso/googleoidc/serviceacct-uniqueid.png) + After you click **Done**, the new service account is added to the list of service accounts for the current + project. You can click the newly-created account to view its details and to edit information for the + account. -Create a new key for the service account, select JSON as the key type, and save -the resulting JSON file. +1. Click the new service account to displays its Details, and copy its **Unique ID** for later. + + ![Copy the Unique ID for the service account](../../../img/sso/googleoidc/service-account-unique-id.png) -![service account key creation](../../../img/sso/googleoidc/serviceacct-key.png) +1. Click **Keys**, click **Add key**, and select **Create new key** to create keys for the service account. -Later, we will make this JSON available to the Teleport Auth Service via the -OIDC Connector configuration, either by referencing a local file or pasting the -JSON into the `tctl` command creating the connector. If you plan to take the -first approach, you will need to upload the JSON to the Auth Service. + ![service account key creation](../../../img/sso/googleoidc/service-account-keys.png) - -Teleport requires the service account JSON to be available to all Teleport Auth -Service hosts when deploying Teleport in a High Availability configuration. -For high availability or cloud deployments, we suggest providing the JSON when -creating the connector resource. - +1. Select **JSON** as the Key type, then click **Create**. + + Google Cloud automatically downloads a JSON file with the keys for the service account + similar to the following: + ```yaml + { + "type": "service_account", + "project_id": "teleport-project-xxxxxx", + "private_key_id": "f06e000000000000000dc18", + "private_key": "-----BEGIN PRIVATE KEY-----\n0000000000000w==\n-----END PRIVATE KEY-----\n", + "client_email": "g-w-sso@teleport-project-xxxxxx.iam.gserviceaccount.com", + "client_id": "11xxxxxxxxxxxxx76", + "auth_uri": "https://accounts.google.com/o/oauth2/auth", + "token_uri": "https://oauth2.googleapis.com/token", + "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", + "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/gwsso%40teleport-project-xxxxxx.iam.gserviceaccount.com", + "universe_domain": "googleapis.com" + } + ``` + + This file is used to configure the OIDC connector for the Teleport Auth Service to use, + either by referencing a local file on the host running the Teleport Auth Service or including the contents + in the command line to create the connector resource. + ### Configure domain-wide delegation -Configure [domain-wide -delegation](https://admin.google.com/ac/owl/domainwidedelegation) for your -newly-created service account: +Now that you have a service account for Teleport to use, you can configure +[domain-wide delegation](https://admin.google.com/ac/owl/domainwidedelegation) for the +service account. + +To configure delegation: -Click "Add new" and add the numeric Unique ID that you've copied earlier from -the service account: +1. Open the Google Workspace Admin console and navigate to +[Manage domain-wide delegation](https://admin.google.com/ac/owl/domainwidedelegation). -![domain-wide delegation](../../../img/sso/googleoidc/domainwidedelegation.png) +1. Click **Add new**. -Add **one** of the following scopes depending on your Google Workspace: -- Direct and Indirect Groups (*Transitive Group Membership Support*) - - `https://www.googleapis.com/auth/cloud-identity.groups.readonly` -- Direct Groups Only - - `https://www.googleapis.com/auth/admin.directory.group.readonly` +1. Paste the numeric Unique ID that you copied from the service account. + +1. Add **one** of the following scopes depending on your Google Workspace edition: + + - For direct groups only, add: + `https://www.googleapis.com/auth/admin.directory.group.readonly` + - For direct and transitive group membership support, add: + `https://www.googleapis.com/auth/cloud-identity.groups.readonly` + +1. Click **Authorize**. ## Step 2/4. Create an OIDC connector -Create the OIDC connector resource using `tctl`. We will explain how to choose -values for fields within the resource spec below: +After you have prepared Google Workspace, you can create the OIDC connector by +running the `tctl sso configure oidc` command. Depending on how you have deployed +your Teleport cluster, you can create the OIDC connector resource in one of two ways: + +- You can **embed** the service account information in the connector resource. +- You can **upload** the service account JSON file to hosts running the Teleport Auth Service. + +The service account JSON must be available to **all Teleport Auth Service hosts** if you +deploy Teleport as a high availability cluster. In most cases, you should use the +**embedded JSON** method to create the connector in high availability and cloud deployments to avoid +storing credentials in a file on multiple servers. + +The alternative to creating the OIDC connector with embedded JSON is to upload the JSON file. +If you have a self-hosted Teleport cluster, you can upload the service account JSON file to all hosts +running the Teleport Auth Service. - + -Use this method to define the service account JSON in the connector resource. -This method doesn't require providing the JSON file to the host(s) running the -Auth Service. +The following command defines the service account by embedding JSON in the command used to create the connector resource. +With this method, you don't have to provide the JSON file to all of the hosts running the Teleport Auth Service. ```code $ tctl sso configure oidc --preset google --id \ @@ -236,12 +313,24 @@ $ tctl sso configure oidc --preset google --id \ --google-acc ' { "type": "service_account", - ... + "project_id": , + "private_key_id": , + "private_key": "-----BEGIN PRIVATE KEY-----\n0000000000000w==\n-----END PRIVATE KEY-----\n", + "client_email": , + "client_id": , + "auth_uri": "https://accounts.google.com/o/oauth2/auth", + "token_uri": "https://oauth2.googleapis.com/token", + "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", + "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/gwsso%40teleport-project-xxxxxx.iam.gserviceaccount.com", "universe_domain": "googleapis.com" }' ``` -The file created will resemble: +After copying this command, be sure to remove the brackets (< >) and replace the placeholder strings with the +appropriate information for your Google Workspace. For example, replace `` with +the email address for the domain administrator similar to `admin@yourdomain.com`. + +This command creates a file similar to the following: ```yaml kind: oidc @@ -265,7 +354,15 @@ spec: { "type": "service_account", - ... + "project_id": , + "private_key_id": , + "private_key": "-----BEGIN PRIVATE KEY-----\n0000000000000w==\n-----END PRIVATE KEY-----\n", + "client_email": , + "client_id": , + "auth_uri": "https://accounts.google.com/o/oauth2/auth", + "token_uri": "https://oauth2.googleapis.com/token", + "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", + "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/gwsso%40teleport-project-xxxxxx.iam.gserviceaccount.com", "universe_domain": "googleapis.com" } issuer_url: https://accounts.google.com @@ -274,22 +371,26 @@ version: v3 ``` - + -Use this method for single self-hosted Teleport Auth instances, or when you can -easily and reliably make the JSON file available to all hosts running the Auth -service. +The following command specifies the path to the JSON file on a host running the Teleport Auth Service. +You can use this method for self-hosted Teleport Auth Service instances if you can +make the JSON file available to all hosts running the Teleport Auth Service. ```code $ tctl sso configure oidc --preset google --id \ --secret \ ---google-acc-uri .json \ +--google-acc-uri .json \ --claims-to-roles groups,auditor@example.com,auditor \ --claims-to-roles groups,teleport-developers@example.com,access \ --google-admin= > gworkspace-connector.yaml ``` -The file created will resemble: +After copying this command, be sure to remove the brackets (< >) and replace the placeholder strings with the +appropriate information for your Google Workspace. For example, replace `` with +the email address for the domain administrator similar to `admin@yourdomain.com`. + +This command creates a file similar to the following: ```yaml kind: oidc @@ -309,7 +410,7 @@ spec: client_secret: display: Google google_admin_email: - google_service_account_uri: /PATH/TO/SERVICE-ACCOUNT-KEY.json + google_service_account_uri: .json issuer_url: https://accounts.google.com redirect_url: https://teleport.example.com/v1/webapi/oidc/callback version: v3 @@ -318,88 +419,50 @@ version: v3 - - Be sure to remove < > brackets around tokens in the sample configuration above. - For example, replace `` with `admin@yourdomain.com`. - - The email that you set for `google_admin_email` **must** be the email address of -a user that has permission to list all groups, users, and group membership in -your Google Workspace account. This user will generally need super admin or group -admin privileges. +an account that has permission to list all groups, users, and group membership in +Google Workspace. In general, this user account must have full administrative privileges +or group administrative privileges. -Do not use the email of the service account for `google_admin_email`. The -configuration display will look the same, but the service account will not have +Don't use the email of the service account for `google_admin_email`. The +configuration might look the same, but the service account doesn't have the required domain-wide delegation. -The `client_id` field must be the unique ID number captured from the Google Cloud -Platform UI. An indicator that this is misconfigured is if you see "invalid Google -Workspace credentials for scopes [...]" in your audit log, accessible from the -Auth service host or the **Management** section of the web UI. +The `client_id` field must be the unique numeric ID for the service account that you created +for the OAuth client in the Google Cloud console. You can check whether this setting is configured +correctly by viewing the audit logs on the host running the Teleport Auth Service or from +the **Management** tab in the Teleport Web UI. If you see "invalid Google Workspace +credentials for scopes [...]" in audit log messages, change the `client_id` setting in the +resource configuration file. For more information about viewing audit logs, see +[Troubleshooting](#troubleshooting). -Test the connector: +To test the connector, run the following command: ```code $ cat gworkspace-connector.yaml | tctl sso test ``` -This will open your browser and attempt to sign you in to your Teleport cluster -using Google. If it fails, the CLI output will provide useful troubleshooting +This command opens the browser and attempts to sign you in to your Teleport cluster +using Google. If it fails, review the command output for troubleshooting information. -Create the connector using the `tctl` tool: +To create the connector using the `tctl` tool, run the following command: ```code $ tctl create -f gworkspace-connector.yaml ``` -
-If you have a configured connector from a version of Teleport older than 8.1.2, -you can upgrade your connector from `v2` to `v3`: - -First, fetch the connector data: - -```code -$ umask 077 -$ tctl get --with-secrets oidc/connectorname > connector.yaml -``` - -Next, edit `connector.yaml` to change the version number from `v2` to `v3`, and -then update the connector: - -```code -$ tctl create -f connector.yaml -$ rm connector.yaml -``` - -Then, to start fetching transitive groups instead of just direct groups, edit -the [domain-wide -delegation](https://admin.google.com/ac/owl/domainwidedelegation) for your -service account and swap out the OAuth scopes for -`https://www.googleapis.com/auth/cloud-identity.groups.readonly`. To undo the -change, remove that scope and add -`https://www.googleapis.com/auth/admin.directory.group.readonly` again. - -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 3/4. Test your Google Workspace OIDC connector -The Web UI will now contain a new button: "Login with Google". To log in with -the CLI: +After you create the connector, the Teleport Web UI displays a new sign-in option, **Login with Google**. +To sign in from the command-line: ```code $ tsh --proxy=proxy.example.com login --auth=google ``` -This command will print the SSO login URL (and will try to open it -automatically in a browser). +This command displays the single sign-on endpoint URL and tries to open it +automatically in a browser. ## Step 4/4. Enable default OIDC authentication diff --git a/docs/pages/includes/commercial-prereqs-tabs.mdx b/docs/pages/includes/commercial-prereqs-tabs.mdx index e5f3cdfb0a5d2..fab6aa24d7d8e 100644 --- a/docs/pages/includes/commercial-prereqs-tabs.mdx +++ b/docs/pages/includes/commercial-prereqs-tabs.mdx @@ -1,13 +1,13 @@ + scope={["enterprise"]} label="Self-Hosted Enterprise"> -- A running Teleport Enterprise cluster, including the Auth Service and Proxy Service. For - details on how to set this up, see our Enterprise [Getting - Started](../choose-an-edition/teleport-enterprise/introduction.mdx) guide. +- A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise [Getting +Started](../choose-an-edition/teleport-enterprise/introduction.mdx) guide. -- The Enterprise `tctl` admin tool and `tsh` client tool version >= (=teleport.version=), - which you can download by visiting your [Teleport account](https://teleport.sh). +- The Enterprise `tctl` admin tool and `tsh` client tool version >= (=teleport.version=). +You can download these tools by visiting your [Teleport account](https://teleport.sh). +You can verify the tools you have installed by running the following commands: ```code $ tctl version