> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/crosswatch/settings/ui-settings/security/oidc-sign-in/google-oidc-sign-in.md). # 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 ``` {% hint style="warning" %} Google requires HTTPS redirect URIs for web applications. Limited localhost exceptions apply. {% endhint %} ### 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. {% hint style="warning" %} Google limits Testing applications to configured test users. Test authorizations expire after seven days. {% endhint %} ### 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 user@example.com ``` 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. {% hint style="warning" %} Do not trust all addresses unless your environment explicitly requires it. {% endhint %} ### 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..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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://wiki.crosswatch.app/crosswatch/settings/ui-settings/security/oidc-sign-in/google-oidc-sign-in.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.