OIDC sign-in

Sign in with an OpenID Connect provider through linked CrossWatch accounts.

OIDC adds Sign in with OIDC to the CrossWatch login page.

It authenticates existing CrossWatch accounts through an OpenID Connect provider.

OIDC uses account linking. It does not create CrossWatch users, User Profiles, or permissions.

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.

Keep a local CrossWatch login available as a recovery path.

OIDC does not replace the local username and password.

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:

<issuer>/.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 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.