Skip to content

Add Google Workspace WIF integration docs #528

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
hslatman wants to merge 1 commit into
base: main
Choose a base branch
from
+88 −10
Draft

Add Google Workspace WIF integration docs #528

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 88 additions & 10 deletions tutorials/connect-google-workspace-to-smallstep.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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.

Expand All @@ -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 **<team-slug>>** with your Smallstep team slug:

```{
"team": {
"Value": "<team-slug>"
}
}
```
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.
Expand Down
Loading