From 4440e0d2bbd43d3ce48e805c004b8a43f0bbd4c3 Mon Sep 17 00:00:00 2001 From: Herman Slatman Date: Mon, 6 Jul 2026 19:27:53 +0200 Subject: [PATCH] Add Google Workspace WIF integration docs --- .../connect-google-workspace-to-smallstep.mdx | 98 +++++++++++++++++-- 1 file changed, 88 insertions(+), 10 deletions(-) diff --git a/tutorials/connect-google-workspace-to-smallstep.mdx b/tutorials/connect-google-workspace-to-smallstep.mdx index 1d9b4773..5c012524 100644 --- a/tutorials/connect-google-workspace-to-smallstep.mdx +++ b/tutorials/connect-google-workspace-to-smallstep.mdx @@ -5,7 +5,7 @@ html_title: Integrate Google Workspace with Smallstep Tutorial description: Integrate Google Workspace with Smallstep for Chromebook device security. Complete guide for enforcing device trust in ChromeOS environments. --- -Smallstep can integrate with Google Workspace to keep your ChromeOS device inventory in sync. +Smallstep can integrate with Google Workspace to keep your ChromeOS device inventory in sync and manage credentials for ChromeOS devices. # Prerequisites @@ -34,36 +34,77 @@ Your Google Cloud project must have the Admin SDK API enabled. By default, it is 5. Choose **Done** 6. Open the details for the Service Account you just created 7. Copy the **Unique ID** (numeric) and the **Email** shown on the details tab; you’ll need them later -8. Visit the **Keys** tab, and choose **Add key**, then **Create new key** -9. Choose **Create** to create a JSON key -A file containing the service account key will be downloaded. Keep this safe and secure! +### 2. Setup Workload Identity Federation -### 2. Grant device directory API permissions +The Smallstep platform authenticates to your Google Workspace through Workspace Identity Federation for Google Kubernetes Engine. + +1. In Google Cloud, visit [IAM & Admin → Workload Identity Federation](https://console.cloud.google.com/iam-admin/workload-identity-pools) +2. Choose **Create pool** +3. Set a name, e.g. "Smallstep Google Workspace Sync Pool" +4. Optionally, provide a **Description** for the pool +5. Click **Continue** +6. Select **OpenID Connect (OIDC)** as the provider +7. Set a name, e.g. "Smallstep Google Workspace Sync" +8. Set the issuer URL to **https://container.googleapis.com/v1/projects/prod-us-central1-e5bd/locations/us-central1/clusters/primary** +9. Keep **Default audience** checked +10. Click **Continue** +11. For the **google.subject** attribute, set **assertion.sub** +12. Click **Add mapping**, and set **attribute.k8s_sa** to **assertion.kubernetes.io.serviceaccount.name** +13. Click **Save** + +### 3. Grant Access to the Service Account + +1. Click **Grant access** +2. Select **Grant access using service account impersonation** +3. Select the **Service account** you created earlier from the dropdown +4. Select **k8s_sa** as the attribute +5. Set **system:serviceaccount:default:inventory** as the value for the attribute +6. Click **Save** +7. When the modal appears, you can **Dismiss** it + +### 4. Grant device directory API permissions 1. In Google Admin, visit [Security → Access and data control → API controls](https://admin.google.com/ac/owl) 2. Under Domain wide delegation, select **Manage Domain Wide Delegation** 3. In the **API Clients** table, select **Add new** 1. Enter the **Unique ID** of the service account from Step 1 - 2. For the **OAuth Scopes**, enter the following scope: + 2. For the **OAuth Scopes**, enter the following scopes: ``` https://www.googleapis.com/auth/admin.directory.device.chromeos + https://www.googleapis.com/auth/verifiedaccess ``` 3. Choose **Authorize** -### 3. Add Google Workspace to Smallstep +### 5. Create and Assign Custom Admin Role to Service Account + +1. In Google Admin, visit [Account → Admin roles](https://admin.google.com/ac/list/roles) +2. Click **Create new role** +3. Give it a descriptive name, e.g. **Google Workspace Sync** +4. Enable the **Manage ChromeOS Devices** privilege (incl. all subitems) +5. Click **Continue** +6. Click **Create role** +7. Click the newly created role +8. Click **Admins assigned** +9. Click **Assign service accounts** +10. Enter the principal of the service account created earlier +11. Click **Assign role** + +### 6. Add Google Workspace to Smallstep In Smallstep, visit [Settings → Device Management](https://smallstep.com/app/?next=/settings/devices). Configure a new Google Workspace Integration with the following values: - The **Customer ID** of your Google Workspace tenant. The Customer ID is a short alphanumeric string. It can be obtained from the Google Workspace Admin [Account Settings](https://admin.google.com/ac/accountsettings/profile) page -- The **Service Account JSON key** you downloaded earlier -- An email address of a user in your Google Workspace directory with admin permissions +- The **Project ID** of the GCP project your service account was created in +- The **workload identity pool** +- The **workload identity provider** +- The service account **principal** -### 4. Add Smallstep certificates to Google Workspace +### 7. Add Smallstep certificates to Google Workspace After saving the Google Workspace connection, you will see settings for your integration. @@ -85,6 +126,43 @@ After saving the Google Workspace connection, you will see settings for your int - Choose **Add** 5. Repeat Step 4 for each of the certificates you downloaded +### 8. Verified Access Mode Configuration + +1. In Google Workspace, visit [Devices → Chrome → Settings](https://admin.google.com/ac/chrome/settings/device). +2. Select **Device settings** +3. Click **Verified mode** +4. Ensure the correct **Organizational Unit** is selected for scoping the configuration +4. Under Configuration, select **Require verified mode boot for verified access** +5. Set the email address of the GCP service account in the **Services with full access** field +6. Click Save + +### 9. ChromeOS Extension Configuration + +1. In Google Workspace, visit [Devices → Chrome → Apps & extension](https://admin.google.com/ac/chrome/apps). +2. Click **Users & browsers** +3. Ensure the proper **Organizational Unit** is selected for scoping the configuration +4. Click the **+** icon on the bottom right +5. Click **Add Chrome app or extension by ID** +6. Set the **Extension ID** to **icjpnolkgdnfgpccpkdlipalcmalkndl** +7. In the dropdown, choose **From a custom URL**, and set it to **https://packages.smallstep.com/chromeos/latest/update.xml** +8. Click **Save** +9. Click the newly created extension to edit it +10. Select **Force install + pin** as the **Installation policy** +11. Under **Certificate management**, enable **allow access to keys** and **Allow enterprise challenge** +12. Under **Policy for extensions**, add the following JSON, replacing **>** with your Smallstep team slug: + +```{ + "team": { + "Value": "" + } +} +``` +13. Click **Save** in the top right corner +14. Scroll down in the side panel details, and ensure the installation URL is set to ... +15. Set the **Update URL** to **Installation URL (see above)** +16. Click **Save** + + ### Confirmation Within a few minutes, you should see all of your ChromeOS devices in Smallstep's [Devices](https://smallstep.com/app/?next=/devices/all) tab.