> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onyx.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Google OAuth
> Google OAuth authentication setup
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](/deployment/authentication/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](/deployment/authentication/sso_providers#plan-availability)).
**Prerequisites:**
* [Google Cloud Console](https://console.cloud.google.com/) access
* Administrative permissions to configure OAuth applications
## Guide
Navigate to the Google Cloud Console [Project Creation page](https://console.cloud.google.com/projectcreate)
and fill in the required fields.
Navigate to **APIs & Services** and find [Google People
API](https://console.cloud.google.com/apis/library/people.googleapis.com).
Ensure your newly created project is selected in the top bar and click **Enable**.
Open the left sidebar and navigate to **APIs & Services** → **OAuth Consent Screen**.
Once on the **Overview** page, click **Get Started**.
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.
Navigate to **APIs & Services** → **OAuth Consent Screen** → **Clients** page.
Click **"+ Create Client"** and select **Web Application**.
**Name:** `Onyx`
Add 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:
```
http://localhost:3000
http://localhost:3000/api/auth/oidc/YOUR_PROVIDER_NAME/callback
```
If hosting Onyx on a custom domain use:
```
https://YOUR_ONYX_DOMAIN.com
https://YOUR_ONYX_DOMAIN.com/api/auth/oidc/YOUR_PROVIDER_NAME/callback
```
Make sure the URIs you enter here match the URI you use to access Onyx!
Click **Create** → **Download JSON** to save the OAuth client credentials. Alternatively,
save the **Client ID** and **Client Secret** to a password or secrets manager.
Navigate to **Admin Panel** → **Organization** → [SSO Providers](/deployment/authentication/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:
```bash .env theme={null}
GOOGLE_OAUTH_SCOPE_OVERRIDE=openid,email,profile,https://www.googleapis.com/auth/drive.readonly
```
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:
```bash .env theme={null}
OIDC_PKCE_ENABLED=true
```
`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:
```bash .env theme={null}
AUTH_TYPE=google_oauth
OAUTH_CLIENT_ID=YOUR_CLIENT_ID
OAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET
# If you are deploying to a custom domain, you will need to set the `WEB_DOMAIN` environment variable.
WEB_DOMAIN=https://YOUR_ONYX_DOMAIN.com
```
```bash values.yaml theme={null}
auth:
secrets:
OAUTH_CLIENT_ID:
OAUTH_CLIENT_SECRET:
configMap:
AUTH_TYPE: google_oauth
```