> 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.md). # OIDC sign-in OIDC adds **Sign in with OIDC** to the CrossWatch login page. It authenticates existing CrossWatch accounts through an OpenID Connect provider. {% hint style="info" %} OIDC uses account linking. It does not create CrossWatch users, User Profiles, or permissions. {% endhint %} ### How it works CrossWatch keeps its own accounts and access model. OIDC only changes how a user proves their identity. ``` CrossWatch account ↓ Linked OIDC identity ↓ Identity provider ``` After sign-in, CrossWatch loads the linked account, its User Profile, and its Access Mode. ``` User Account = who signs in User Profile = delegated resource scope Access Mode = what the user may do OIDC = how the user authenticates ``` OIDC supports providers such as Authentik, Keycloak, Authelia, and Microsoft Entra ID. ### Before you begin You need an OpenID Connect application in your identity provider. Configure this redirect URI: ``` https://YOUR-CROSSWATCH-URL/api/app-auth/oidc/callback ``` The URI must exactly match CrossWatch's public URL. {% hint style="warning" %} Keep a local CrossWatch login available as a recovery path. OIDC does not replace the local username and password. {% endhint %} ### Configure OIDC 1. Sign in with a local CrossWatch account. 2. Open **Settings → UI Settings → Security**. 3. In **OIDC sign-in**, set **Enabled**. 4. Enter the provider's **Issuer URL** and **Client ID**. 5. Enter the **Client Secret**, when your provider requires one. 6. Use `openid profile email` for **Scopes**. 7. Click **Save OIDC**. The issuer is the provider's base OIDC identity URL. Do not enter authorization or token endpoint URLs. CrossWatch discovers them from: ``` /.well-known/openid-configuration ``` CrossWatch validates that the discovered issuer matches the configured issuer. ### Link an account Saving OIDC configures the provider. It does not link any account. 1. Sign in to the CrossWatch account you want to link. 2. Open **Settings → UI Settings → Security**. 3. In **OIDC sign-in**, click **Link OIDC account**. 4. Sign in with the identity provider account. 5. Complete the provider's approval flow. CrossWatch links the external identity using its issuer and `sub` claim. It does not match accounts by email address or username. An OIDC identity can link to only one CrossWatch account. ### Managed users Create the User Profile and CrossWatch account first. Then sign in as that account and link its OIDC identity. Each managed user needs a separate linked identity. ``` User Profile ↓ CrossWatch account ↓ Linked OIDC identity ``` OIDC does not change delegated resources or Read Only and Full Access permissions. See [Managed users](/crosswatch/settings/connections/managed-users.md) for the delegation model. ### Sign in with OIDC After OIDC is enabled and at least one enabled account is linked: 1. Open the CrossWatch login page. 2. Click **Sign in with OIDC**. 3. Authenticate with the identity provider. 4. Return to CrossWatch. CrossWatch validates the response and finds the linked account. If no matching link exists, CrossWatch rejects the sign-in. CrossWatch two-factor authentication still applies when enabled for that account. ### Unlink or change provider Click **Unlink** in **OIDC sign-in** to remove the external identity. This does not delete the CrossWatch account, User Profile, provider instances, or sync resources. If you change identity providers, link each account again. A new provider normally has a different issuer, subject, or both. ### Reverse proxy requirements Your identity provider must use CrossWatch's public URL in its callback: ``` https://YOUR-CROSSWATCH-URL/api/app-auth/oidc/callback ``` For a redirect URI mismatch, check the scheme, hostname, port, callback path, and forwarded host headers. The callback path is always `/api/app-auth/oidc/callback`. ### Troubleshooting * **Not configured** — enable OIDC and provide an Issuer URL and Client ID. * **Link unavailable** — save a valid configuration first. CrossWatch must discover the provider. * **Sign-in button missing** — enable OIDC and link at least one enabled account. * **Account not linked** — sign in locally, then link the matching OIDC identity. * **Identity already linked** — unlink it from the existing CrossWatch account first. * **OIDC sign-in expired** — restart the flow. Authorization and linking requests expire after about 10 minutes. * **Another code required** — CrossWatch two-factor authentication is enabled for the account. ### Security CrossWatch uses the OIDC Authorization Code flow with PKCE S256. It uses state, nonce, discovery, and JWKS signature verification. CrossWatch validates the ID token signature, issuer, audience, expiration, nonce, and subject. Common RSA and EC SHA-256, SHA-384, and SHA-512 signing algorithms are supported. If available, CrossWatch also reads UserInfo metadata such as username, email, and profile picture. --- # 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.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.