Google OAuth

Configure Nexus to use Google OAuth for user authentication, providing a 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:

• Google Cloud Console access

• Administrative permissions to configure OAuth applications

Guide#

Create Google Cloud Project#

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

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.

Create Google Auth Platform#

Open the left sidebar and navigate to APIs & Services → OAuth Consent Screen.

Once on the Overview page, click Get Started.

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.

Create OAuth Client#

Navigate to APIs & Services → OAuth Consent Screen → Clients page.

Click "+ Create Client" and select Web Application.

Configure OAuth Client#

Name: Nexus

Add your Nexus origin under Authorized JavaScript origins, and add an Authorized redirect URI using the name you will give the provider in Nexus (a lowercase slug, e.g. google):

If hosting Nexus 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!

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.

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:

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:

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:

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

auth:
secrets:
  OAUTH_CLIENT_ID: <CLIENT_ID_FROM_GOOGLE>
  OAUTH_CLIENT_SECRET: <CLIENT_SECRET_FROM_GOOGLE>
configMap:
AUTH_TYPE: google_oauth