Authentication

Windshift supports several authentication methods. You can use them separately or combine them.

SSO / OIDC

Windshift uses the zitadel/oidc library to integrate with OpenID Connect providers such as Keycloak, Okta, Auth0, Azure AD, and Google.

How It Works

  1. The user clicks "Sign in with SSO" on the login page.
  2. Windshift redirects the user to the identity provider authorization endpoint.
  3. After authentication, the provider redirects the user back with an authorization code.
  4. Windshift exchanges the code for tokens and extracts the user claims.
  5. Windshift creates a session and signs in the user.

Configuration

Configure OIDC providers in Admin > Single Sign-On (SSO). Enter these required fields:

  • Client ID: From your identity provider.
  • Client Secret: From your identity provider.
  • Issuer URL: The OIDC discovery URL, such as https://auth.example.com/realms/windshift.

Features

  • PKCE: Enabled by default.
  • Clock skew tolerance: Five seconds for minor time differences.
  • Custom scopes: Defaults to openid, email, and profile. You can configure additional scopes.
  • Attribute mapping: Maps custom claim names to Windshift user fields, including email, name, username, and picture.
  • Auto-provisioning: Windshift creates users on their first SSO login.
  • Email verification: You can require verified email addresses from the provider.

Private identity providers

By default, Windshift blocks OIDC discovery, JWKS, and token requests to private, loopback, link-local, multicast, and CGNAT destinations. If your identity provider is internal, enable the global private-egress switch:

ALLOW_LOCAL_CONNECTIONS=true

or with the binary:

./windshift --allow-local-connections

This switch applies to all server-side outbound HTTP, not only OIDC. See Configuration Options for the trade-offs. Windshift ignores the removed OIDC_ALLOWED_PRIVATE_CIDRS variable.

SAML Requires Pro

Windshift also supports SAML 2.0 providers. Configure them in the admin panel alongside OIDC.

LDAP Requires Pro

Windshift can authenticate users against an LDAP directory, such as Active Directory or OpenLDAP.

Connection

  • LDAPS (port 636): Uses TLS from the start.
  • STARTTLS (port 389): Upgrades a plain connection to TLS.
  • TLS verification: You can disable it for development. Do not disable it for production.

Bind Configuration

Windshift uses a service account to connect to LDAP:

  • Bind DN: Distinguished name of the service account, such as cn=windshift,dc=example,dc=com.
  • Bind Password: Service account password.
  • Base DN: Search base for user lookups.

User Attributes

Windshift extracts these attributes from LDAP entries:

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

Windshift searches the whole subtree and uses a 30-second timeout.

WebAuthn / FIDO2

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

Use --allowed-hosts and --allowed-port to configure the WebAuthn relying party origin.

Session Management

Windshift uses secure, HTTP-only cookies for sessions. The defaults are:

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

Windshift derives session keys from SSO_SECRET, the same secret used for SSO state. SHA-256 produces deterministic cookie encryption keys. Each session records:

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

Admin Fallback

If SSO is the only authentication method, use --enable-fallback to enable password-based admin login for recovery:

./windshift --enable-fallback

Password Login

You can enable or disable password login in the admin panel. When you configure SSO, you can disable password login to enforce SSO-only authentication.