Authentication

Windshift supports multiple authentication methods that can be used individually or combined.

SSO / OIDC

Windshift integrates with any OpenID Connect provider (Keycloak, Okta, Auth0, Azure AD, Google, etc.) using the zitadel/oidc library.

How It Works

  1. Users click "Sign in with SSO" on the login page
  2. Windshift redirects to the identity provider's authorization endpoint
  3. After authentication, the provider redirects back with an authorization code
  4. Windshift exchanges the code for tokens and extracts user claims
  5. A session is created and the user is logged in

Configuration

OIDC providers are configured through the Windshift admin panel under Admin > Single Sign-On (SSO). Required fields:

  • Client ID - From your identity provider
  • Client Secret - From your identity provider
  • Issuer URL - The OIDC discovery URL (e.g., https://auth.example.com/realms/windshift)

Features

  • PKCE - Enabled by default for enhanced security
  • Clock skew tolerance - 5 seconds to handle minor time differences
  • Custom scopes - Defaults to openid, email, profile; additional scopes can be configured
  • Attribute mapping - Map custom claim names to Windshift user fields (email, name, username, picture)
  • Auto-provisioning - Users are automatically created on first SSO login
  • Email verification - Optionally require verified email addresses from the provider

SAML Requires Pro

SAML 2.0 providers are also supported for enterprise environments. Configuration is available through the admin panel alongside OIDC.

LDAP Requires Pro

Windshift can authenticate users against an LDAP directory (Active Directory, OpenLDAP, etc.).

Connection

  • LDAPS (port 636) - TLS connection from the start
  • STARTTLS (port 389) - Upgrades a plain connection to TLS
  • TLS verification - Can be disabled for development environments (not recommended for production)

Bind Configuration

Windshift connects to LDAP using a service account:

  • Bind DN - Distinguished name of the service account (e.g., cn=windshift,dc=example,dc=com)
  • Bind Password - Service account password
  • Base DN - Search base for user lookups

User Attributes

The following attributes are extracted from LDAP entries:

Attribute Description
DN Distinguished Name
UID User identifier
Email Email address
FirstName Given name
LastName Surname
DisplayName Full display name

Search uses whole-subtree scope with a 30-second timeout.

WebAuthn / FIDO2

Windshift supports hardware security keys and biometric authentication via WebAuthn. Users can register passkeys from their profile settings as a second factor or primary authentication method.

The --allowed-hosts and --allowed-port flags are used to configure the WebAuthn relying party origin.

Session Management

Sessions use secure, HTTP-only cookies with the following defaults:

Setting Value
Token size 256-bit (32 bytes)
Default duration 24 hours
"Remember me" duration 30 days

Session keys are derived from SSO_SECRET (the same secret used for SSO state) using SHA-256, producing deterministic cookie encryption keys. Each session tracks:

  • IP address
  • User agent
  • Expiration time
  • Activation status

Admin Fallback

For environments where SSO is the only authentication method, the --enable-fallback flag provides a password-based admin login as a recovery mechanism:

./windshift --enable-fallback

Password Login

Password-based login can be toggled on or off in the admin panel. When SSO is configured, you can optionally disable password login to enforce SSO-only authentication.