Last updated

Single Sign-On

Single Sign-On (SSO) lets users sign in through an external OIDC identity provider. Windshift supports Keycloak, Authentik, Pocket ID, and other OIDC-compliant providers. Only system administrators can configure SSO.

Add a provider

  1. Open Admin, then Single Sign-On.
  2. Select Add Provider.
  3. Enter a slug, a display name, and the provider details:
    • Issuer URL: the OIDC issuer, for example https://auth.example.com/realms/myrealm.
    • Client ID and Client Secret from the identity provider.
    • Scopes: the OIDC scopes, usually openid profile email.
  4. Copy the Callback URL and add it as the redirect URL in the identity provider.
  5. Select Test Connection to check the provider.
  6. Select Enabled to allow sign-in, and Default to preselect it.

Use Attribute mapping only when the provider uses non-standard claim names. Some providers, such as Microsoft Entra ID, include only a display name by default. Add given_name and family_name as optional claims so Windshift receives the structured name.

Provisioning and account linking

  • Auto-provision users creates a Windshift account on the first SSO login. Leave it off to require an existing account.
  • Link accounts without IdP email verification links an identity to an existing account by email even when the provider does not verify the address. Enable it only when the provider controls its users' email addresses.

GitHub login

GitHub is available as a login provider alongside OIDC, for both the main application and customer portals.

  1. Open Admin, then Single Sign-On.
  2. Select Add Provider, then GitHub.
  3. Enter the OAuth client ID and secret from a dedicated GitHub OAuth App. Use the callback URL shown on the page. This login configuration is separate from source control access and requests no repository permissions.
  4. Optionally set Restrict to GitHub organization. Enter the organization login, not a URL. Windshift checks active membership on every GitHub sign-in, including for already linked accounts.
  5. Select Enabled.

GitHub must verify an email address before sign-in, and existing Windshift accounts are linked by verified email. Login requests read:user and user:email, plus read:org when an organization restriction is set. Existing Windshift sessions are not revoked when organization membership changes.

Customer-only providers

Set a provider's Account type to Portal-only customers to admit portal customers rather than internal users. You can optionally assign new customers to a customer organisation and require existing customers to belong to it. Account type and organisation assignment cannot be changed after you create the provider. The provider list marks a customer-only provider with a Customer-only label.

Sign-in policy

The Security page sets the instance sign-in policy. Choose SSO only to require SSO, or allow SSO alongside password sign-in. Turning on Preview mode warns users without blocking sign-in.

Note: Set the BASE_URL environment variable before you register the callback URL. Without it, Windshift falls back to a local address and sends that address to the identity provider.