> For the complete documentation index, see [llms.txt](https://docs.bluefletch.com/bluefletch-enterprise/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bluefletch.com/bluefletch-enterprise/product-guides/authentication-and-sso/features/google-workspace-groups.md). # Google Workspace Groups ## Overview When users sign in to BlueFletch Launcher with **Google Sign-In**, the sign-in token from Google identifies the user but does not include their Google Workspace **groups** or **department**. With this feature enabled, BlueFletch looks up the signed-in user's department and group memberships from your Google Workspace directory right after sign-in and adds them to the user's session. You can then use them in `group_inclusion` to control which apps and layouts each user sees. The lookup is done by a BlueFletch directory service that you authorize in your Google Admin Console with **domain-wide delegation**, using **read-only** access. Devices never hold any Google admin credentials. #### What BlueFletch can and can't access * **Read-only.** BlueFletch only requests the two read-only Directory scopes listed below. It cannot create, change, or delete users or groups. * **Only the signed-in user.** Each lookup returns data for the user who just signed in on the device, verified from their Google sign-in token. There is no way to request another user's data. * **Only department and groups.** BlueFletch reads the user's department (from their organization info) and the email addresses of the groups they belong to. Results are held in memory for up to a few hours to reduce calls to Google, and are not stored anywhere else. * **You stay in control.** Removing the delegation grant in your Admin Console stops all access immediately. #### Prerequisites * Google Sign-In is already configured for BlueFletch Launcher (`appConfig.bfAuth.google` with the Launcher applications' `clientId`). * A BlueFletch Auth release that supports Workspace groups and department (contact BlueFletch for the minimum version). * A Google Workspace **super admin** to complete the Admin Console steps. *** ## Setup Overview 1. **In Google Admin Console:** 1. Authorize BlueFletch's service account with domain-wide delegation 2. Create a custom read-only role (only allow Users.Read and Groups.Read) 3. Create an email account that uses the custom role in (b). 2. **Send BlueFletch** the directory account's email address. BlueFletch enables the feature for your organization. 3. **Update your Launcher configuration** with the directory service URL, and map groups to apps. *** ## Step 1: Get Your Client ID and Service URL from BlueFletch Contact your BlueFletch representative or BlueFletch Support and ask to enable **Google Workspace Groups**. Include: * Your BlueFletch organization ID (the `orgId` in your Launcher configuration) * Your Google Workspace domain (e.g. `example.com`) * Which BlueFletch environment(s) you use (for example, a QA and a Production organization) BlueFletch will send you: * **Client ID**: a long number (about 21 digits) used in Step 2. This is a Google Cloud ID that represents the BlueFletch service's service account. * **Directory service URL**: used in Step 4. {% hint style="info" %} If you use more than one BlueFletch environment, BlueFletch may provide a different Client ID for each. Complete Step 2 once for each Client ID you receive. {% endhint %} *** ## Step 2: Configure Google Workspace A Google Workspace **super admin** performs these steps in [admin.google.com](https://admin.google.com). #### 2a. Authorize BlueFletch's Service Account (domain-wide delegation) 1. Go to **Security → Access and data control → API controls**. 2. Under **Domain wide delegation**, click **Manage Domain Wide Delegation**, then **Add new**. 3. In **Client ID**, enter the numeric Client ID from BlueFletch. 4. In **OAuth scopes**, enter exactly (comma-separated): ``` https://www.googleapis.com/auth/admin.directory.user.readonly, https://www.googleapis.com/auth/admin.directory.group.readonly ``` 5. Click **Authorize**. {% hint style="info" %} If you only want to share **department** and not groups, authorize only the first scope and tell BlueFletch. Group lookups will then be skipped. {% endhint %} #### 2b. Create a custom read-only admin role 1. Go to **Account → Admin roles** and click **Create new role**. 2. Name it, for example, **BlueFletch Directory Reader**. 3. Under **Admin API privileges**, check only: * **Users → Read** * **Groups → Read** 4. Leave all **Admin console privileges** unchecked. 5. Click **Continue**, then **Create role**. #### 2c. Create the directory account and assign the new custom role 1. Go to **Directory → Users** and add a dedicated user, for example `dir-reader@example.com`. It does not need a mailbox or any other Google services. 2. Open the role from 2b, click **Assign role**, and assign it to this user at your **top-level organizational unit**, so it can read every user who signs in on your devices. {% hint style="warning" %} * Use a **dedicated** account, not a super admin's personal account. * **Don't suspend or delete** this account. Lookups stop working if you do. * Nobody needs to sign in as this account. BlueFletch acts on its behalf only to make the read-only calls above. {% endhint %} *** ## Step 3: Send the Directory Account to BlueFletch Send BlueFletch the email address of the account from 2c (for example `dir-reader@example.com`). BlueFletch will enable the feature for your organization and let you know when it's ready. {% hint style="info" %} Changes in Google Admin Console can take some time to take effect. If lookups don't work right away, wait and try again before troubleshooting. {% endhint %} *** ## Step 4: Configure Launcher Add `directoryProxyUrl` to the `google` object inside `appConfig.bfAuth`, using the directory service URL from BlueFletch. #### Configuration The following key-value pairs can be set within the `appConfig.bfAuth.google` object of the Launcher configuration JSON file. | Key | Type | Description | | ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `directoryProxyUrl` | String | The directory service URL provided by BlueFletch. When not set, the feature is off and sign-in works as before. | | `directoryProxyRequired` | Boolean | When `true`, sign-in fails if the department and groups can't be retrieved. When `false`, the user is still signed in, just without directory groups. Default is `false`. | #### Example Configuration ```json { "appConfig": { "bfAuth": { "google": { "clientId": ".apps.googleusercontent.com", "workspaceDomain": "example.com", "directoryProxyUrl": "", "directoryProxyRequired": false, "baseConfig": { "auth_default_group": "Associates" } } } } } ``` #### How groups appear in the session After sign-in, the user's groups are set in this order: 1. The user's **department** (for example `Store Operations`) 2. The user's **Google groups**, as group **email addresses** (for example `store-managers@example.com`) 3. Your `auth_default_group`, if configured For example, a user in the Store Operations department who belongs to two groups would have: ``` Store Operations|all-staff@example.com|store-managers@example.com|Associates ``` * Groups are **direct** memberships only. If a user is in a group only through another group (a nested group), that group isn't included. * Group email addresses are **lowercase**. * The department is the one on the user's **primary** organization in Google Workspace (**Directory → Users → User information → Employee information**). #### Mapping groups to apps Use the department and group emails as keys in `group_inclusion`, exactly as they appear above: ```json { "group_inclusion": { "Store Operations": ["StoreOpsApps"], "store-managers@example.com": ["ManagerApps", "StoreOpsApps"], "Associates": ["AssociateApps"] } } ``` {% hint style="warning" %} Use the group's **email address** (for example `store-managers@example.com`), not its display name ("Store Managers"). {% endhint %} *** ## Troubleshooting | Symptom | Likely cause | What to do | | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | User signs in but only has `auth_default_group` | The lookup failed, or the feature isn't enabled for your organization yet | Confirm Step 3 is complete with BlueFletch. Check that `directoryProxyUrl` is set. | | No groups right after setup | Google Admin Console changes haven't taken effect yet | Wait and try again. | | Department appears but no groups | Only the user scope was authorized, or the role is missing **Groups → Read** | Check the scopes in 2a and the role privileges in 2b. | | No department | The user has no department set in Google Workspace | Set the department on the user's profile in Admin Console. | | Some users work and others don't | The role in 2c is assigned to a sub-organizational unit | Assign the role at the top-level organizational unit. | | Everything stopped working | The directory account was suspended or deleted, or the delegation grant was removed or changed | Restore the account or grant, making sure the scopes match 2a exactly. | | Sign-in fails completely (`directoryProxyRequired` is `true`) | The lookup failed | Set `directoryProxyRequired` to `false` while troubleshooting, then contact BlueFletch Support. | When contacting BlueFletch Support, include your organization ID, Workspace domain, and the time of a failed sign-in. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.bluefletch.com/bluefletch-enterprise/product-guides/authentication-and-sso/features/google-workspace-groups.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.