Google OIDC sign-in

Connect Google accounts to CrossWatch through OpenID Connect.

CrossWatch supports Google accounts through OpenID Connect (OIDC).

Link a Google account to a CrossWatch administrator or managed user. Then use that account to sign in.

Google is configured as a standard OIDC provider in CrossWatch.

Requirements

Before you start, you need:

1. A working CrossWatch installation.
2. A public HTTPS address for CrossWatch.
3. Access to the Google Cloud Console.
4. A Google account to link to CrossWatch.

For example:

https://crosswatch.example.com

When using a custom port:

https://crosswatch.example.com:8787

Google requires HTTPS redirect URIs for web applications. Limited localhost exceptions apply.

Create or select a Google Cloud project

Open Google Cloud Console → Google Auth Platform.

Create a project or select an existing project for CrossWatch.

If needed, select Get started. Then configure the application information.

Google Auth Platform manages OAuth clients, branding, audiences, and scopes.

Configure the audience

Open Google Auth Platform → Audience.

Choose the audience that matches your environment:

• External usually suits personal installations.
• Internal limits access to a Google Workspace organization.

Google only permits Internal for projects in a Google Cloud organization.

If the app is in Testing, add each permitted Google account as a test user.

Google limits Testing applications to configured test users. Test authorizations expire after seven days.

Create the OAuth client

Open Google Auth Platform → Clients. Create an OAuth client.

Set Application type to Web application.

Name the client, for example, CrossWatch.

Google generates a Client ID and Client secret. You need both values in CrossWatch.

Configure the redirect URI

Under Authorized redirect URIs, add the CrossWatch callback URL:

https://YOUR-CROSSWATCH-ADDRESS:PORT/api/app-auth/oidc/callback

For example:

https://crosswatch.example.com:8787/api/app-auth/oidc/callback

The URI must exactly match CrossWatch's request. Match the protocol, hostname, port, and path.

Google returns redirect_uri_mismatch when any value differs.

CrossWatch always uses this callback path:

/api/app-auth/oidc/callback

Leave Authorized JavaScript origins empty. CrossWatch uses a server-side authorization code flow.

Save the OAuth client.

Configure OIDC in CrossWatch

Open Settings → UI Settings → Security → OIDC sign-in.

Configure these values:

Enabled:       Enabled
Issuer URL:    https://accounts.google.com
Client ID:     Your Google OAuth Client ID
Client secret: Your Google OAuth Client secret
Scopes:        openid profile email

Google's OIDC issuer is:

https://accounts.google.com

CrossWatch requires the openid scope. Do not enter an email address as a scope.

Click Save OIDC.

CrossWatch now displays Configured, not linked. The provider works, but no account has a linked Google identity.

Link your Google account

1. Click Link OIDC account.
2. Select the Google account to associate.
3. Complete Google's sign-in flow.

CrossWatch stores Google's issuer and subject identifier against your account.

The status then shows identity details, such as:

Google User
[e-mail]

The displayed details depend on Google's returned identity data.

CrossWatch shows OIDC sign-in only after at least one account has a valid linked identity.

Test Google sign-in

1. Log out of CrossWatch.
2. Select Sign in with OIDC on the login screen.
3. Authenticate with the linked Google account.

CrossWatch matches the Google issuer and subject identifier. It does not identify accounts by email alone.

Reverse proxy installations

CrossWatch must determine its external HTTPS address behind a reverse proxy.

For example, a browser may use:

https://crosswatch.example.com:9000

The proxy may connect internally using:

http://192.168.1.50:8787

Google must receive the external HTTPS callback URI.

Your reverse proxy should send:

X-Forwarded-Proto: https
X-Forwarded-Host: crosswatch.example.com:9000

CrossWatch trusts these headers only from configured Trusted proxies.

Open Settings → UI Settings → Security → Trusted proxies. Add the proxy IP address or network.

For example:

192.168.1.100

Docker proxies may appear through a bridge address. Configure the actual proxy address or trusted Docker network.

Do not trust all addresses unless your environment explicitly requires it.

Synology Reverse Proxy

Open the CrossWatch reverse proxy rule in Synology DSM. Add these custom headers:

X-Forwarded-Proto: https
X-Forwarded-Host: crosswatch.example.com:9000

Replace the hostname and port with CrossWatch's public address.

Also add the Synology proxy address under Trusted proxies in CrossWatch.

Troubleshooting

Error 400: redirect_uri_mismatch

Check the redirect_uri in Google's error details.

For example, Google may receive:

http://crosswatch.example.com:8787/api/app-auth/oidc/callback

while the OAuth client permits:

https://crosswatch.example.com:8787/api/app-auth/oidc/callback

CrossWatch is not detecting HTTPS correctly. Check:

• X-Forwarded-Proto
• X-Forwarded-Host
• Trusted proxies

Google rejects differences in scheme, hostname, port, or callback path.

Google sign-in works, but status says “Configured, not linked”

Use a CrossWatch version that includes the OIDC administrator status fix.

Older development builds could store an administrator identity but report it as unlinked.

Administrator identities are stored under:

app_auth.oidc_identity

Managed-user identities are stored under:

app_auth.users.<user>.oidc

CrossWatch preserves both configuration forms.

Access blocked by Google

For an External application in Testing, add the Google account to the test user list.

Google allows only configured test users during Testing.

OIDC sign-in is missing

OIDC must be:

• Enabled.
• Configured.
• Linked to at least one CrossWatch account.

CrossWatch intentionally hides OIDC sign-in until a linked identity exists.

Example configuration

Google OAuth client:

Application type: Web application

Authorized redirect URI:
https://crosswatch.example.com:9898/api/app-auth/oidc/callback

CrossWatch:

OIDC:          Enabled
Issuer URL:    https://accounts.google.com
Client ID:     123456789.apps.googleusercontent.com
Client secret: ********
Scopes:        openid profile email

Save the configuration, link an account, and complete Google sign-in.

OIDC sign-in is then available for the linked account.