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.

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.

---

Step 2: Configure Google Workspace

A Google Workspace super admin performs these steps in 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

1. Click Authorize.

If you only want to share department and not groups, authorize only the first scope and tell BlueFletch. Group lookups will then be skipped.

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 [e-mail]. 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.

• 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.

---

Step 3: Send the Directory Account to BlueFletch

Send BlueFletch the email address of the account from 2c (for example [e-mail]). BlueFletch will enable the feature for your organization and let you know when it's ready.

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.

---

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

{
  "appConfig": {
    "bfAuth": {
      "google": {
        "clientId": "<your Web application client ID>.apps.googleusercontent.com",
        "workspaceDomain": "example.com",
        "directoryProxyUrl": "<directory service URL from BlueFletch>",
        "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 [e-mail])

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|[e-mail]|[e-mail]|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:

{
  "group_inclusion": {
    "Store Operations": ["StoreOpsApps"],
    "[e-mail]": ["ManagerApps", "StoreOpsApps"],
    "Associates": ["AssociateApps"]
  }
}

Use the group's email address (for example [e-mail]), not its display name ("Store Managers").

---

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.