WorkOS authentication

View as Markdown

Krenalis supports WorkOS as the authentication provider for the Admin Console. When WorkOS is configured, Krenalis never handles passwords directly, and members sign in through WorkOS AuthKit, which unlocks a broad set of authentication methods out of the box: social login (Google, Microsoft, GitHub and others), passwordless magic links, multi-factor authentication, and enterprise-grade Single Sign-On (SSO) via SAML 2.0.

Configure WorkOS

To configure WorkOS for Krenalis, complete the steps described in the following sections.

Redirects

In the WorkOS dashboard, open Applications, select the application you want to configure, and open the Redirects tab. Configure the following three sections using the URL of your Admin Console:

Section Description Value
Redirect URIs The URLs that WorkOS is permitted to use as redirect destinations after authentication. The Admin Console passes its own URL as the redirect URI when initiating login; WorkOS accepts it only if it matches an entry in this list. URL of your Admin Console, e.g. https://example.com/admin
Sign-in endpoint An endpoint in your app that redirects users to the WorkOS authentication UI to start the login flow. URL of your Admin Console, e.g. https://example.com/admin
Sign-out redirects The URLs to which users can be redirected after signing out of WorkOS. URL of your Admin Console, e.g. https://example.com/admin

CORS

In the WorkOS dashboard, open Applications, select the application you want to configure, and open the Sessions tab. Under Cross-Origin Resource Sharing (CORS), click Manage, then add the origin of your Admin Console as an allowed origin (e.g. https://example.com).

Sign-up

In the WorkOS dashboard, navigate to Authentication → Features → Sign-up and click Manage. Disable self-service sign-up.

Krenalis currently supports only an onboarding and invitation-based sign-up flow: the first admin is onboarded, and all subsequent members are invited through a WorkOS UI embedded in the Krenalis Admin Console. Direct sign-up is not supported.

Webhooks

WorkOS sends webhook events to Krenalis to keep member and organization data in sync. In the WorkOS dashboard, open Webhooks and click Create webhook. Enter the following endpoint URL:

https://<your-krenalis-host>/v1/workos/webhook

Enable the following events:

Event Description
user.updated Synchronizes changes to a member's name and email address.
user.deleted Synchronizes deletion of a member across all organizations.
organization.updated Synchronizes changes to an organization's name.
organization_membership.created Provisions a member when they are added to an organization in WorkOS.
organization_membership.deleted Removes a member when they are removed from an organization in WorkOS.

User registration action

To ensure that only invited users can sign up via WorkOS, configure the user registration action in your WorkOS dashboard. Navigate to Actions → Configuration and click Edit action in the User registration action section. Enter the following endpoint URL:

https://<your-krenalis-host>/v1/workos/actions/user-registration

When a new user attempts to sign up, WorkOS calls this endpoint before completing the registration. Krenalis checks that the email address matches an existing invitation — if it does not, registration is denied.

Set Deny user registration in the Error handling section of the action configuration. This ensures that if WorkOS cannot reach the Krenalis endpoint (for example due to a network issue or misconfiguration), unauthorized registrations are blocked rather than silently allowed through.

Configure Krenalis

Set the following environment variables before starting Krenalis. See Environment variables for the full reference.

Variable Description
KRENALIS_WORKOS_CLIENT_ID Client ID of your WorkOS environment.
KRENALIS_WORKOS_API_KEY API key for server-side WorkOS API calls.
KRENALIS_WORKOS_WEBHOOK_SECRET Secret for verifying webhook signatures.
KRENALIS_WORKOS_ACTIONS_SECRET Secret for verifying action request signatures.
KRENALIS_WORKOS_DEV_MODE Set to true to enable development mode (optional).

When KRENALIS_WORKOS_CLIENT_ID is set, all other KRENALIS_WORKOS_* variables are required and Krenalis will fail to start if any are missing.

Authentication flow

The following steps describe what happens when a member signs in:

  1. The member visits the Krenalis Admin Console.
  2. If no active session exists, the Admin Console redirects to the WorkOS authentication UI.
  3. After the member authenticates successfully, the WorkOS React SDK exposes a signed access token to the Admin Console.
  4. The Admin Console sends the access token to POST /v1/members/login.
  5. Krenalis verifies the token signature, then uses it to retrieve the member's information.
  6. Krenalis sets an encrypted session cookie and the member is authenticated.

Member lifecycle

When a member is invited to the WorkOS organization, the organization_membership.created webhook automatically creates their Krenalis account before they log in for the first time. If the webhook has not yet fired when the member attempts to sign in, Krenalis provisions the account at login as a fallback.

When a member is removed from the WorkOS organization, the organization_membership.deleted webhook removes their Krenalis account from that organization. When a WorkOS user is deleted entirely, the user.deleted webhook removes them from all organizations.

Changes to a member's name or email address in WorkOS are reflected in Krenalis automatically through the user.updated webhook. Similarly, changes to an organization's name are synchronized through the organization.updated webhook.

Development mode

Setting KRENALIS_WORKOS_DEV_MODE=true stores the WorkOS refresh token in the browser's localStorage instead of an HTTP-only cookie.

⚠️ Do not enable development mode in production. Storing tokens in localStorage exposes them to JavaScript and increases the risk of theft through XSS attacks.