Single Sign-on Authentication With Google Workspace

Overview

This guide walks you through setting up Google Workspace SSO authentication with SigNoz.

What you'll accomplish:

• Configure Google Workspace as an identity provider (IdP) for SigNoz
• Enable your team to access SigNoz using their existing Google Workspace accounts

Prerequisites

Before starting, ensure you have:

• Google Workspace account with Super-Admin access
• SigNoz account (Cloud or Self-Hosted) with administrative access
• Your SigNoz instance URL (e.g., https://signoz.example.com)

Configuration Steps

Step 1: Create OAuth 2.0 Credentials in Google Cloud

1. Visit the Google Cloud Console → Credentials
2. Select or create a project for SigNoz
3. Click Create credentials → OAuth client ID → Web application
4. Add an Authorized redirect URI:

   https://${SIGNOZ_BASEURL}/api/v1/complete/google
   

5. Click Create and note the Client ID and Client Secret. You'll paste these into SigNoz shortly

Step 2: Configure SigNoz for Google Authentication

Now you'll configure SigNoz to accept authentication from Google Workspace:

1. Navigate to SigNoz Settings:

   • Go to your SigNoz dashboard
   • Click on Settings in the left sidebar
   • Navigate to Organization Settings → Members & SSO
   • Click on Authenticated Domains

2. Add New Domain:

   • Click Add a Domain
   • Enter your company domain (e.g., example.com for users with @example.com emails)

3. Enter Configuration Details:

   Domain: example.com
   Google Client ID: <client-id-from-google>
   Google Client Secret: <client-secret-from-google>
   

   Where to find these values:

   • Domain: The email domain for users who should use SSO (e.g., example.com for users with @example.com emails)
   • Google Client ID: The Client ID from Google Cloud Console
   • Google Client Secret: The Client Secret from Google Cloud Console

4. Save Configuration:

   • Click Save to apply the Google authentication configuration

Step 3: Enforce SSO

Back in the domain list, toggle Enforce SSO. From now on, all users with the email format <user>@your-email-domain.com will be forced to log in through Google.

Step 4: Test the Setup

Open a private/incognito window and visit your SigNoz URL. You will be redirected to Google for authentication and then back to SigNoz.

Step 5: Configure Group-Based Access (Optional)

You can restrict SigNoz access to specific Google Workspace groups and use group membership for role mapping. This requires a Google Cloud service account with Domain-Wide Delegation.

5.1: Create a Service Account

1. Go to Google Cloud Console → IAM & Admin → Service Accounts
2. Click Create Service Account
3. Give it a name (e.g., signoz-group-sync) and click Create and Continue
4. Skip the optional steps and click Done
5. Click the newly created service account → Keys → Add Key → Create new key → JSON
6. Save the downloaded JSON key file — you'll paste its contents into SigNoz

5.2: Enable Domain-Wide Delegation

1. On the service account page, click Edit (pencil icon)
2. Expand Show Advanced Settings
3. Check Enable Google Workspace Domain-wide Delegation
4. Click Save
5. Note the Client ID (numeric) shown on the service account details page

5.3: Authorize Scopes in Google Workspace Admin

1. Go to Google Workspace Admin Console → Security → API Controls → Domain-wide Delegation
2. Click Add new
3. Enter the service account Client ID
4. Add the following OAuth scope:

   https://www.googleapis.com/auth/admin.directory.group.readonly
   

5. Click Authorize

5.4: Enable the Admin SDK API

1. Go to Google Cloud Console → APIs & Services → Library
2. Search for Admin SDK API
3. Click Enable

5.5: Configure Group Fetching in SigNoz

1. Go to Settings → Organization Settings → Members & SSO → Authenticated Domains
2. Click on your Google Auth domain to edit it
3. In the Group Access section, configure the following:

4. Click Save

Step 6: Configure Role Mapping (Optional)

Role mapping automatically assigns SigNoz roles (VIEWER, EDITOR, ADMIN) to users when they log in, based on their Google Workspace group memberships.

Role Resolution Priority

When a user logs in, SigNoz determines their role using this priority (highest to lowest):

1. Use Role Attribute — if enabled and the IDP token contains a role claim, that role is used directly
2. Group Mappings — if the user belongs to multiple mapped groups, the highest-privilege role wins (ADMIN > EDITOR > VIEWER)
3. Default Role — fallback role from configuration
4. VIEWER — ultimate default if nothing else is configured

Configure in SigNoz

1. Go to Settings → Organization Settings → Members & SSO → Authenticated Domains
2. Click on your Google Auth domain to edit it
3. In the Role Mapping section, configure the following:

   • Default Role: Select the role assigned when no other mapping matches (e.g., VIEWER)

   • Group Mappings: Add entries mapping Google Workspace group emails to SigNoz roles:

     Google Workspace Group	SigNoz Role
     platform-admins@company.com	ADMIN
     engineering@company.com	EDITOR
     everyone@company.com	VIEWER

   • Use Role Attribute: Turn ON to use a role claim directly from the IDP token instead of group-based mapping. Leave OFF for group-based role mapping. This option applies only if your IDP token already includes a role claim. For standard Google Workspace OAuth, this is not typically available — use group-based mapping instead.

4. Click Save

Troubleshooting

Common issues and solutions:

• "Authentication failed" error: Check that the redirect URI exactly matches https://${SIGNOZ_BASEURL}/api/v1/complete/google in Google Cloud
• Stuck in a login loop: Ensure Enforce SSO is enabled and the user's email domain matches the configured authenticated domain
• Groups not being fetched: Verify that the service account has Domain-Wide Delegation enabled, the admin.directory.group.readonly scope is authorized in Google Workspace Admin, and the Admin SDK API is enabled in Google Cloud
• "Insufficient permissions" error for groups: Check that the admin email in Domain to Admin Email has permissions to list groups in Google Workspace. The admin must have at least the Groups Reader role
• User created with wrong role: Check the role resolution priority — if Use Role Attribute is ON, it takes precedence over group mappings. Verify your group mappings use the full group email address (e.g., engineering@company.com, not just engineering)
• Allowed Groups blocking login: If you configured Allowed Groups, ensure the user is a member of at least one listed group. Check with Fetch Transitive Group Membership ON if the user is in a nested group
• Locked out?: If you're unable to login because of faulty SSO setup, use password authentication by appending ?password=Y to your login URL: <your-instance-url>/login?password=Y

Next Steps

Once Google Workspace SSO is configured:

• Users with your organization's email domain can sign in without prior invites
• Configure group-based access to restrict login to specific Google Workspace groups
• Set up role mapping to automatically assign SigNoz roles based on group membership
• Consider setting up additional security policies in Google Workspace for enhanced security