bifrost/docs/enterprise/setting-up-google-workspace.mdx

---
title: "Setting up Google Workspace"
description: "Step-by-step guide to configure Google Workspace as your identity provider for Bifrost Enterprise SSO and Directory-based user provisioning."
icon: "google"
---

## Overview

This guide walks you through configuring **Google Workspace** as your identity provider for Bifrost Enterprise. The integration has two pieces:

1. **OAuth 2.0 login** — users sign in to Bifrost with their Google Workspace accounts via a Google OAuth Client ID.
2. **Directory API provisioning (optional)** — a Google **service account** with domain-wide delegation lets Bifrost list users and groups from the Workspace directory for bulk import and team sync.

You can run login-only (no service account) or full provisioning (with service account + domain-wide delegation).

## Prerequisites

- A Google Workspace domain with **Super Admin** access to the Admin console
- A Google Cloud project where you can create OAuth clients and service accounts
- Bifrost Enterprise deployed and accessible
- The redirect URI for your Bifrost instance (e.g. `https://your-bifrost-domain.com/login`)
- Bifrost [roles](./rbac) created for the roles you plan to map

---

## Step 1: Configure the OAuth consent screen

1. In the Google Cloud Console, go to **APIs & Services → OAuth consent screen**.

<Frame>
  <img src="/media/user-provisioning/gws-apis-and-services.png" alt="Google OAuth consent screen configuration" />
</Frame>

2. Choose **Internal** if you only want Workspace users, or **External** otherwise.
3. Fill in App name, support email, and developer contact.
4. Add the scopes: `openid`, `profile`, `email`.
5. Save.

---

## Step 2: Create an OAuth Client ID

1. Open **APIs & Services → Credentials → Create credentials → OAuth client ID**.

<Frame>
  <img src="/media/user-provisioning/gws-auth-client-creation.png" alt="Creating a Google OAuth Web Application Client ID" />
</Frame>

2. Configure:

| Field | Value |
| --- | --- |
| **Application type** | Web application |
| **Name** | Bifrost Enterprise |
| **Authorized JavaScript origins** | `https://your-bifrost-domain.com` |
| **Authorized redirect URIs** | `https://your-bifrost-domain.com/login` |

3. Save and copy the **Client ID** and **Client Secret**.

---

## Step 3: (Optional) Create a service account for Directory API access

Skip this section if you only want SSO login without directory-based user import.

1. Go to **IAM & Admin → Service Accounts → Create service account**.

<Frame>
  <img src="/media/user-provisioning/gws-service-account-id.png" alt="Creating a Google service account" />
</Frame>

2. Give it a name (e.g. `bifrost-provisioning`). You can skip the "Grant this service account access to project" step — no GCP IAM roles are required; access is granted via domain-wide delegation in Step 5.
3. Open the service account → **Keys → Add Key → Create new key → JSON**. Download and store the JSON file securely.
4. From the service account **Details** tab, copy the **Unique ID** (a numeric value, **not** the email or OAuth Client ID).

---

## Step 4: Enable the Admin SDK API

If you're using the service account path:

1. Open **APIs & Services → Library**.
2. Search for **Admin SDK API** and click **Enable**.

---

## Step 5: Set up domain-wide delegation

1. In the [Google Admin Console](https://admin.google.com), go to **Security → Access and data control → API controls → Manage Domain Wide Delegation**.

<Frame>
  <img src="/media/user-provisioning/gws-domain-wide-delegation.png" alt="Google Workspace Domain-Wide Delegation configuration" />
</Frame>

2. Click **Add new**.
3. Enter the service account's **Unique ID** (from Step 3).
4. Add these OAuth scopes (copy the full URLs, comma-separated):

```
https://www.googleapis.com/auth/admin.directory.user.readonly,
https://www.googleapis.com/auth/admin.directory.group.readonly,
https://www.googleapis.com/auth/admin.directory.group.member.readonly
```

5. **Authorize**.

<Note>
  Domain-wide delegation requires impersonating an admin user. Pick an admin email that will persist (e.g. a dedicated `sso-admin@company.com`) — Bifrost uses this as the **Admin Email** in configuration.
</Note>

---

## Step 6: Configure Bifrost

### Using the Bifrost dashboard

1. In Bifrost, go to **Governance → User Provisioning**.
2. Select **Google Workspace** as the SCIM Provider.
3. Fill in the fields:

| Field | Value |
| --- | --- |
| **Domain** | Your Google Workspace primary domain (e.g. `company.com`) |
| **Client ID** | OAuth Client ID from Step 2 |
| **Client Secret** | OAuth Client Secret from Step 2 |
| **Audience** | Optional override (defaults to Client ID) |
| **Admin Email** | Admin user to impersonate for Directory API (Step 5) |
| **Service Account Source** | Choose one: Paste JSON / Environment variable / File path |
| **Service Account JSON / Env Var / File** | The value for the chosen source |

<Frame>
  <img src="/media/user-provisioning/gws-form.png" alt="Bifrost Google Workspace configuration form" />
</Frame>

4. Click **Verify** — Bifrost validates the OAuth client and, if a service account is provided, attempts a Directory API impersonation to confirm delegation is working.
5. Configure **Attribute → Role / Team / Business Unit** mappings to map groups or organizational units to Bifrost roles and teams.
6. Toggle **Enabled** and click **Save Configuration**.

### Using `config.json`

```json
{
  "scim_config": {
    "enabled": true,
    "provider": "google",
    "config": {
      "domain": "company.com",
      "clientId": "123-abc.apps.googleusercontent.com",
      "clientSecret": "${GOOGLE_WORKSPACE_CLIENT_SECRET}",
      "adminEmail": "sso-admin@company.com",
      "serviceAccountEnvVar": "GOOGLE_SA_JSON",
      "teamIdsField": "groups"
    }
  }
}
```

Pick one of the three service-account sources: `serviceAccountJson` (raw JSON string), `serviceAccountEnvVar` (env var name holding the JSON), or `serviceAccountFile` (absolute path to the key file).


### Custom attribute mapping

You can also map any custom attributes to any entity (role, team or business unit). Make sure these are configured to send back to Bifrost in token configuration.

<Frame>
  <img
    src="/media/user-provisioning/custom-attribute-mapping.png"
    alt="Attribute Mappings configuration in Bifrost"
  />
</Frame>

### Configuration reference

| Field | Required | Description |
| --- | --- | --- |
| `domain` | Yes | Google Workspace primary domain (e.g. `company.com`). |
| `clientId` | Yes | OAuth 2.0 Web Client ID from Step 2. |
| `clientSecret` | Yes | Client Secret — required for token revocation and for confidential server-side flows. |
| `audience` | No | Expected JWT audience. Defaults to `clientId`. |
| `adminEmail` | Yes  | Workspace admin to impersonate via domain-wide delegation. Required when any service-account field is set. |
| `serviceAccountJson` | One of 3 | Raw JSON string of the service account key. |
| `serviceAccountEnvVar` | One of 3 | Name of the environment variable containing the JSON. |
| `serviceAccountFile` | One of 3 | Absolute path to the JSON key file on the Bifrost host. |
| `attributeRoleMappings` | Yes | Ordered list of attribute→role mappings. |
| `attributeTeamMappings` | No | Attribute→team mappings (all matches apply). |
| `attributeBusinessUnitMappings` | No | Attribute→business-unit mappings (all matches apply). |

<Warning>
  Bifrost rejects configs that set a service-account credential source without `adminEmail` — domain-wide delegation cannot work without an impersonation subject.
</Warning>

---

## Testing the Integration

1. Open the Bifrost dashboard in an incognito window.
2. You're redirected to `accounts.google.com`; sign in with a Workspace user.
3. Verify you land on the Bifrost dashboard and appear under **Governance → Users**.
4. If provisioning is configured, open **Governance → User Provisioning → Import Users**, filter by a Workspace group, click **Preview**, and confirm users show up.

---

## Troubleshooting

### `admin_policy_enforced` or `access_denied` during OAuth

- The Workspace admin has blocked third-party OAuth apps. In the Admin Console, go to **Security → Access and data control → API controls** and allow the Bifrost OAuth client.

### `unauthorized_client: Client is unauthorized to retrieve access tokens`

- The service account Unique ID and scopes in **Domain-Wide Delegation** don't match. Re-enter the Unique ID (the numeric value from the service account's **Details** tab, not the OAuth client ID).

### `Not Authorized to access this resource/api` from Directory API

- The impersonated `adminEmail` is missing the **User Management Admin** role. Promote them in Admin Console → Admin roles.
- The Admin SDK API is not enabled on the Cloud project.

### Users see a consent prompt every login

- On the OAuth consent screen, ensure the app is **Published** (or **Internal** for Workspace-only apps) so it doesn't stay in testing mode.

### `domain_mismatch`

- The primary domain in the Workspace does not match the `domain` field. Use the primary domain, not an alias.

---

## Next Steps

- [User Provisioning overview](./user-provisioning) — capabilities, attribute mappings, bulk import
- [Role-Based Access Control](./rbac) — configure custom roles before mapping
- [Audit Logs](./audit-logs) — track authentication events