# 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 <span class="docs-pro-badge">Requires Pro</span>

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

## LDAP <span class="docs-pro-badge">Requires Pro</span>

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:

```bash
./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.