# WorkOS authentication



Krenalis supports [WorkOS](https://workos.com) 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](https://www.krenalis.com/docs/configuration/environment-variables.md#workos) 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.