Authentication

Polygent issues its own RS256 JWTs after authenticating users through OAuth2 (Google or Microsoft) or generic OpenID Connect (Okta, Auth0, Keycloak, or any OIDC-compliant IdP). All authentication settings live under the Login section in appsettings.json. For the user-facing flow (multi-tab sync, token rotation) see the Concepts page.

Method	Use
Google OAuth2	Production sign-in for Google Workspace teams
Microsoft OAuth2	Production sign-in for Microsoft 365 / Entra ID teams
Generic OpenID Connect	Okta, Auth0, Keycloak, or any OIDC-compliant IdP — configurable, no code changes

Only one provider can be active at a time. Set Login:LoginType to Google, Microsoft, or OpenIdConnect.

`Login` Section Reference

Setting	Type	Default	Description
`Login:AccessTokenMinutesLifetime`	int	`15`	JWT access token expiration (minutes)
`Login:RefreshTokenDaysLifetime`	int	`7`	Refresh token expiration (days)
`Login:ClientUrl`	string	empty	Frontend base URL — used for redirects after OAuth
`Login:ClientId`	string	empty	OAuth provider client ID
`Login:ClientSecret`	string	empty	OAuth provider client secret
`Login:LoginType`	enum	`Google`	`Google`, `Microsoft`, or `OpenIdConnect`
`Login:TenantId`	string	empty	Microsoft tenant ID (Microsoft only; `common` for any tenant)
`Login:Authority`	string	empty	OIDC issuer URL (OpenIdConnect only — required)
`Login:OidcDisplayName`	string	empty	Label shown on the SSO button (defaults to "SSO")
`Login:OidcScopes`	string	empty	Extra scopes appended to `openid profile email` (space- or comma-separated)
`Login:EnableTestLogin`	bool	`false`	Bypass OAuth — never enable in production
`Login:EnableSeamlessSso`	bool	`false`	Suppress the OAuth account picker on re-login
`Login:AllowNewUsers`	bool	`true`	Allow first-time users to auto-register on login

Google OAuth2

{
  "Login": {
    "LoginType": "Google",
    "ClientId": "your-client-id.apps.googleusercontent.com",
    "ClientSecret": "your-client-secret",
    "ClientUrl": "https://polygent.example.com"
  }
}

Authorized redirect URI to register: {ClientUrl}/signin-google

In Google Cloud Console, add this URI under APIs & Services → Credentials → your OAuth client → Authorized redirect URIs.

Microsoft OAuth2

{
  "Login": {
    "LoginType": "Microsoft",
    "ClientId": "your-application-id",
    "ClientSecret": "your-client-secret",
    "TenantId": "common",
    "ClientUrl": "https://polygent.example.com"
  }
}

Redirect URI to register: {ClientUrl}/signin-microsoft

In Microsoft Entra ID (Azure Portal), add this URI under App registrations → your app → Authentication → Redirect URIs.

Use common as TenantId to allow any Microsoft account, or a specific tenant GUID to restrict sign-in to your organization.

Generic OpenID Connect (Okta / Auth0 / Keycloak)

Register an OIDC client at your IdP and configure Polygent with the issuer URL — Polygent discovers endpoints automatically via {Authority}/.well-known/openid-configuration. No code changes are required.

{
  "Login": {
    "LoginType": "OpenIdConnect",
    "Authority": "https://your-tenant.okta.com/oauth2/default",
    "ClientId": "your-client-id",
    "ClientSecret": "your-client-secret",
    "OidcDisplayName": "Okta",
    "OidcScopes": "",
    "ClientUrl": "https://polygent.example.com"
  }
}

Redirect URI to register at the IdP: {ClientUrl}/signin-oidc

Add this URI as an allowed callback/redirect URI in your IdP's application settings.

IdP	`Authority` example
Okta	`https://your-tenant.okta.com/oauth2/default`
Auth0	`https://your-tenant.auth0.com/`
Keycloak	`https://keycloak.example.com/realms/your-realm`

Notes:

Flow is Authorization Code + PKCE. Polygent queries the user-info endpoint for claims.
The email and name (or preferred_username) standard OIDC claims are required. Configure your IdP to release them.
OidcDisplayName controls the sign-in button label (e.g., "Sign in with Okta"). Defaults to "SSO" when empty.
OidcScopes appends extra scopes to the default openid profile email — use it for things like groups (Keycloak) or offline_access.

JWT Configuration

Polygent auto-generates an RSA signing key on first run, stored at {StoragePath}/signing-key.xml. The defaults are sensible for most deployments:

Setting	Default	Notes
Algorithm	RS256	Asymmetric — 2048-bit key generated on first start
Access token TTL	15 minutes	Configurable via `Login:AccessTokenMinutesLifetime`
Refresh token TTL	7 days	Configurable via `Login:RefreshTokenDaysLifetime`
Token rotation	Enabled	Each refresh issues a new pair
Clock skew tolerance	30 seconds	Built-in; absorbs minor drift between load-balanced API hosts

The signing key is validated on startup with a sign/verify probe. If the key file is corrupt, startup aborts — restore from backup or delete the file to let Polygent regenerate one (this invalidates all existing sessions).

Cookies are HttpOnly (no JavaScript access)
Cookies are Secure (HTTPS-only)
Cookies are SameSite=Lax — same-site navigation works; cross-site form posts are blocked

Open Redirect Protection

Polygent validates the returnUrl after OAuth callback against the configured Login:ClientUrl. Set ClientUrl correctly to ensure only legitimate post-login URLs are honored.

ASP.NET Core OAuth middleware creates correlation and nonce cookies during the OAuth redirect. If the flow is interrupted (user cancels, presses back, network error), these cookies persist and break subsequent login attempts with a correlation mismatch.

Polygent automatically clears these cookies:

Before each new OAuth flow in the login endpoints
On all callback paths (success, failure, missing info, login rejected)

You do not need to configure this — it is built in.

Seamless SSO

Set Login:EnableSeamlessSso to true to suppress the OAuth account picker when the user already has an active provider session. Only enable for environments where the OAuth tenant is single-account (e.g., a corporate Workspace).

Restricting New User Auto-Registration

By default, the first time a user authenticates with an email that has no existing account, Polygent auto-creates the account. Set Login:AllowNewUsers to false to require all users to be pre-provisioned:

Existing users continue to sign in normally
OAuth users with no existing account are rejected after successful provider authentication and redirected to /login?error=registration_disabled
Test-login emails with no existing account are rejected with a user-facing error message
Pre-provision new users in Settings → Users before they attempt to sign in

User Blocking

Admins can soft-block users from Settings → Users. Blocked users:

Cannot sign in (existing tokens are revoked at next refresh)
Are removed from workspace member lists in the UI
Retain their data (sessions, tickets, comments) so audit history is preserved

Creating Users

Admins can create user accounts before those users have ever signed in. From Settings → Users, click Create User and provide a name, email, and (optionally) roles.

On the user's first sign-in (Google, Microsoft, or generic OpenID Connect) Polygent matches by email — no duplicate account is created and the pre-assigned roles are retained.
Admins can rename users, change their roles, block them, or delete them outright. Block is reversible and preserves audit history (sessions, tickets); Delete is permanent and removes the user along with their workspace memberships.
Created users do not receive an email invitation. Share the Polygent sign-in URL with them directly, and make sure the email you enter matches the email they will sign in with at the OAuth provider.

Token Cleanup

Expired/revoked refresh tokens older than 7 days are cleaned up automatically. No manual maintenance is required.

Sign-in Methods​

Login Section Reference​

Google OAuth2​

Microsoft OAuth2​

Generic OpenID Connect (Okta / Auth0 / Keycloak)​

JWT Configuration​

Cookie Behavior​

Open Redirect Protection​

OAuth Cookie Hygiene​

Seamless SSO​

Restricting New User Auto-Registration​

User Blocking​

Creating Users​

Token Cleanup​

See Also​

Sign-in Methods