Skip to main content
Configure Onyx to use Google OAuth for user authentication, providing a seamless login experience through existing Google accounts. Google providers are managed at Admin Panel → Organization → SSO Providers. No environment variables or restarts are needed, and you can configure multiple providers (enabling more than one at the same time requires the Business plan, see Plan Availability). Prerequisites:

​
Guide

1

Create Google Cloud Project

Navigate to the Google Cloud Console Project Creation page and fill in the required fields.Google Cloud Console Project Creation Page
2

Enable Google People API

Navigate to APIs & Services and find Google People API.Ensure your newly created project is selected in the top bar and click Enable.Google Cloud Console People API Enable Page
3

Create Google Auth Platform

Open the left sidebar and navigate to APIs & Services → OAuth Consent Screen.Once on the Overview page, click Get Started.Google Cloud Console OAuth Consent Screen Page
4

Configure OAuth Project & Consent Screen

Fill in the App name and User support email fields.Select your Audience. If you have a Google Workspace organization, select Internal. If not, select External.
If you select External, you will need to add your users manually in the Audience tab under Test users.
Fill in any other required fields and finalize the configuration.
5

Create OAuth Client

Navigate to APIs & Services → OAuth Consent Screen → Clients page.Click ”+ Create Client” and select Web Application.Google Cloud Console OAuth Client Creation Page
6

Configure OAuth Client

Name: OnyxAdd your Onyx origin under Authorized JavaScript origins, and add an Authorized redirect URI using the name you will give the provider in Onyx (a lowercase slug, e.g. google):If hosting Onyx locally use:
If hosting Onyx on a custom domain use:
Google Cloud Console OAuth Client Creation Page
Make sure the URIs you enter here match the URI you use to access Onyx!
7

Save OAuth Credentials

Click Create → Download JSON to save the OAuth client credentials. Alternatively, save the Client ID and Client Secret to a password or secrets manager.
8

Add the Provider in Onyx

Navigate to Admin Panel → Organization → SSO Providers and click Add Provider.Select the Google provider type, enter the Name you used in the redirect URI, and paste the Client ID and Client Secret.After creating the provider, its row shows the exact Redirect URI. Confirm it matches what you registered on the OAuth client, then sign in through the new option on the login page.

​
Customizing requested scopes

By default, Onyx requests openid, email, and profile from Google during login — the minimum needed to identify the user. Overriding the list is primarily useful when the access token issued at login should be passed through to tool calls that need additional Google API access. Starting in v4.5, set Scopes on the provider entry (Admin Panel → Organization → SSO Providers) to override the list per provider. A provider’s Scopes take precedence. When left empty, the deployment-wide environment variable applies, then the built-in defaults. On v4.4.x, the only override is the deployment-wide GOOGLE_OAUTH_SCOPE_OVERRIDE environment variable, a comma-separated list:
.env
The override replaces the default scopes — make sure openid, email, and profile are still included if you want standard login to keep working.
Any scopes you add here must also be enabled on the OAuth client in Google Cloud Console (consent screen + client configuration). Onyx only changes what is sent in the authorize request; Google still rejects scopes that are not configured for the client.
These scopes apply only to the app login and pass-through OAuth flows. The Google Drive and Gmail connectors use their own scopes and OAuth flow, which are not affected by this setting.

​
Enabling PKCE

PKCE is disabled by default. Starting in v4.5, turn on Enable PKCE on the provider entry (Admin Panel → Organization → SSO Providers). On v4.4.x, the deployment-wide OIDC_PKCE_ENABLED environment variable enables it for all providers. Google login shares the OIDC login route, so the OIDC-named variable applies here too:
.env
OIDC_PKCE_ENABLED=true forces PKCE on for every provider, including providers whose Enable PKCE toggle is off. Unset it if you want the per-provider toggles to be the source of truth.

​
Upgrading from v4.3 or Earlier

Versions before v4.4.0 configured a single Google provider through environment variables, using the redirect URI https://YOUR_ONYX_DOMAIN.com/auth/oauth/callback on the OAuth client. On v4.4.0 and later these variables no longer enable Google login, and they are planned for full removal in v4.5. New installs must use the admin panel flow above.
When you upgrade an existing deployment, its environment-based configuration is imported into an SSO provider entry automatically, and existing logins keep working. The import runs once, when the upgrade first runs against your existing database, so keep the configuration in place through the upgrade. The migrated provider keeps using the redirect URI already registered in the Google Cloud Console, so nothing changes on the Google side. Once the migrated provider appears in the admin panel, sign-ins and token refresh use the provider entry’s credentials, and AUTH_TYPE, OAUTH_CLIENT_ID, and OAUTH_CLIENT_SECRET can be removed. The variables only act as a fallback for login accounts that no provider entry matches, such as after deleting or renaming the migrated provider.
For reference, a pre-v4.4.0 configuration looks like:
.env
values.yaml