---
title: "Google Oauth Group Mapping - DreamFactory Documentation"
source: "http://wiki.dreamfactory.com/Security/Google_Oauth_Group_Mapping"
canonical_url: "http://wiki.dreamfactory.com/Security/Google_Oauth_Group_Mapping"
converted_at: "2026-04-16T05:03:36.464Z"
format: "markdown"
converted_by: "html-to-md-ai"
---
[]()
	
	
	
	# Security/Google Oauth Group Mapping

	
		From DreamFactory Wiki
		
		
		
		
		[Jump to navigation](#mw-head)
		[Jump to search](#searchInput)
		## Contents

- [1 Google OAuth Group-to-Role Mapping](#Google_OAuth_Group-to-Role_Mapping)

- [1.1 Prerequisites](#Prerequisites)

- [1.2 Part 1: Google Cloud Console Setup](#Part_1:_Google_Cloud_Console_Setup)

- [1.2.1 Step 1: Create a Google Cloud Project](#Step_1:_Create_a_Google_Cloud_Project)

- [1.2.2 Step 2: Enable Required APIs](#Step_2:_Enable_Required_APIs)

- [1.2.3 Step 3: Configure the OAuth Consent Screen](#Step_3:_Configure_the_OAuth_Consent_Screen)

- [1.2.4 Step 4: Add Scopes](#Step_4:_Add_Scopes)

- [1.2.5 Step 5: Create OAuth Credentials](#Step_5:_Create_OAuth_Credentials)

- [1.3 Part 2: DreamFactory Configuration](#Part_2:_DreamFactory_Configuration)

- [1.3.1 Step 1: Create the Google OAuth Service](#Step_1:_Create_the_Google_OAuth_Service)

- [1.3.2 Step 2: Enable Group-to-Role Mapping](#Step_2:_Enable_Group-to-Role_Mapping)

- [1.3.3 How Role Assignment Works](#How_Role_Assignment_Works)

- [1.4 Troubleshooting](#Troubleshooting)

- [1.4.1 Users receive a 403 error during login](#Users_receive_a_403_error_during_login)

- [1.4.2 Group mapping is not working (user gets default role)](#Group_mapping_is_not_working_(user_gets_default_role))

- [1.4.3 "Access denied" or scope-related errors](#"Access_denied"_or_scope-related_errors)

- [1.4.4 Login works but no role is assigned](#Login_works_but_no_role_is_assigned)

- [1.5 Migration from Admin SDK API](#Migration_from_Admin_SDK_API)

# Google OAuth Group-to-Role Mapping

This guide walks through configuring Google OAuth authentication in DreamFactory with optional automatic role assignment based on Google Workspace group membership.

With this feature enabled, when a user logs in via Google OAuth, DreamFactory reads their Google group memberships and assigns a DreamFactory role based on a configurable group-to-role mapping.

## Prerequisites

- A Google Workspace account (not a personal Gmail account)

- Access to the [Google Cloud Console](https://console.cloud.google.com/)

- Administrative access to your DreamFactory instance

**ℹ️ Note:** Google Workspace admin privileges are **not** required for end users. Any standard Google Workspace user can have their group memberships read during OAuth login.
## Part 1: Google Cloud Console Setup

### Step 1: Create a Google Cloud Project

1. Go to the [Google Cloud Console](https://console.cloud.google.com/)

2. Click **Select a Project** then **New Project**

3. Enter a project name (e.g., `DreamFactory OAuth`) and click **Create**

4. Make sure the new project is selected in the project dropdown

### Step 2: Enable Required APIs

1. Navigate to **APIs & Services** then **Enabled APIs & Services**

2. Click **+ ENABLE APIS AND SERVICES**

3. Search for and enable the following APIs:
- **Google People API** (required for basic OAuth login)

- **Cloud Identity API** (required for group-to-role mapping)

**⚠️ Warning:** Previous versions of this guide referenced the **Admin SDK API** for group fetching. This has been replaced by the **Cloud Identity API**, which does not require admin privileges or domain-wide delegation.
### Step 3: Configure the OAuth Consent Screen

1. Navigate to **APIs & Services** then **OAuth consent screen**

2. Select **Internal** (for Google Workspace users within your organization) and click **Create**

3. Fill in the required fields:
- **App name**: e.g., `DreamFactory`

- **User support email**: your admin email

- **Developer contact information**: your admin email

4. Click **Save and Continue**

### Step 4: Add Scopes

1. On the **Scopes** step, click **Add or Remove Scopes**

2. Add the following scopes:
- `openid`

- `[https://www.googleapis.com/auth/userinfo.email](https://www.googleapis.com/auth/userinfo.email)`

- `[https://www.googleapis.com/auth/userinfo.profile](https://www.googleapis.com/auth/userinfo.profile)`

- `[https://www.googleapis.com/auth/cloud-identity.groups.readonly](https://www.googleapis.com/auth/cloud-identity.groups.readonly)`

3. Click **Update** and then **Save and Continue**

**ℹ️ Note:** The `cloud-identity.groups.readonly` scope is only needed if you plan to use group-to-role mapping. If you only need basic Google OAuth login, the first three scopes are sufficient.
### Step 5: Create OAuth Credentials

1. Navigate to **APIs & Services** then **Credentials**

2. Click **+ CREATE CREDENTIALS** then **OAuth client ID**

3. Set **Application type** to **Web application**

4. Enter a name (e.g., `DreamFactory OAuth Client`)

5. Under **Authorized redirect URIs**, add:
`https://<your-dreamfactory-url>/api/v2/user/session/google_oauth`
Replace `<your-dreamfactory-url>` with your actual DreamFactory instance URL. The path must end with the service name you will create in DreamFactory (e.g., `google_oauth`).

6. Click **Create**

7. Copy the **Client ID** and **Client Secret**

**⚠️ Warning:** The Client Secret cannot be recovered after you close this dialog. Ensure you save it securely.
## Part 2: DreamFactory Configuration

### Step 1: Create the Google OAuth Service

1. Log in to your DreamFactory instance as an administrator

2. Navigate to **Services** then **Create**

3. Select **OAuth** as the Service Type and **Google OAuth** as the sub-type

4. Configure the service:
- **Name**: Must end with `_oauth` (e.g., `google_oauth`)

- **Label**: A display name (e.g., `Google Login`)

- **Description**: Optional

5. Under the **Config** tab:
- **Client ID**: Paste the Client ID from Google Cloud Console

- **Client Secret**: Paste the Client Secret from Google Cloud Console

- **Redirect URL**: Must match the redirect URI you configured in Google Cloud Console

- **Default Role**: Select a fallback role for users whose group membership does not match any mapping

### Step 2: Enable Group-to-Role Mapping

1. On the same **Config** tab, toggle **Map Google Groups to Roles** to enabled

2. Under **Google Group to Role Mapping**, add your mappings:
- **Google Group Email**: The email address of the Google group (e.g., `[[email protected]](/cdn-cgi/l/email-protection)`)

- **DreamFactory Role**: The DreamFactory role to assign to members of that group

3. Add as many mappings as needed

4. Click **Save**

### How Role Assignment Works

When a user logs in via Google OAuth with group mapping enabled, DreamFactory assigns a role using the following priority:

1. **Group mapping** -- If the user belongs to a Google group that has a configured role mapping, that role is assigned

2. **Default role** -- If no group mapping matches, the default role configured on the service is used

3. **App-to-role mapping** -- If neither of the above applies, any existing app-to-role mappings for the service are used

Role assignments are refreshed on every login to reflect the user's current group memberships in Google Workspace.

## Troubleshooting

### Users receive a 403 error during login

- Verify the **Cloud Identity API** is enabled in Google Cloud Console

- Confirm the `cloud-identity.groups.readonly` scope is added to the OAuth consent screen

- If your OAuth consent screen is in **Testing** mode, ensure the user's email is added to the test users list

### Group mapping is not working (user gets default role)

- Verify the Google group email in the mapping matches exactly (case-insensitive)

- Confirm the user is a direct member of the Google group (nested group memberships are not resolved)

- Check your DreamFactory log for warnings containing `Google OAuth: Failed to fetch groups` -- this indicates the Cloud Identity API call failed

### "Access denied" or scope-related errors

- Re-check that all four scopes are added to the OAuth consent screen in Google Cloud Console

- If the consent screen is set to **Internal**, the user must belong to your Google Workspace organization

- If the consent screen is set to **External**, it must be published (not in Testing mode) for external users

### Login works but no role is assigned

- Ensure **Map Google Groups to Roles** is toggled on in the DreamFactory service config

- Verify at least one group-to-role mapping is configured

- Check that the **Default Role** is set as a fallback

## Migration from Admin SDK API

If you previously configured Google OAuth group mapping using the Admin SDK API and domain-wide delegation:

1. **Enable the Cloud Identity API** in your Google Cloud Console project (APIs & Services then Enable APIs)

2. **Add the new scope** `[https://www.googleapis.com/auth/cloud-identity.groups.readonly](https://www.googleapis.com/auth/cloud-identity.groups.readonly)` to your OAuth consent screen

3. **Remove the old scope** `[https://www.googleapis.com/auth/admin.directory.group.readonly](https://www.googleapis.com/auth/admin.directory.group.readonly)` from the consent screen (optional, but recommended)

4. **Remove domain-wide delegation** in Google Workspace Admin Console then Security then API controls then Domain-wide delegation (optional cleanup)

5. **Update DreamFactory** to the latest version containing the Cloud Identity API integration

6. No changes are needed to your group-to-role mappings in DreamFactory -- they continue to work as before

Retrieved from "[https://wiki.dreamfactory.com/index.php?title=Security/Google_Oauth_Group_Mapping&oldid=819](https://wiki.dreamfactory.com/index.php?title=Security/Google_Oauth_Group_Mapping&oldid=819)"
		[Category](/Special:Categories): - [Security](/Category:Security)