Using WorkOS with On-prem Customers

WorkOS can be used with both cloud and on-prem deployments. This guide explains the considerations needed to use WorkOS features with on-prem deployment strategies. For example, many SaaS companies offer enterprise solutions where their infrastructure can be deployed to a customer’s cloud or data center.

When using an on-prem deployment strategy, two key considerations are:

Outside of these considerations, WorkOS integration for on-prem customers functions in the same way as in cloud deployments.

Since a full deployment of your software is being deployed to your customer’s environment, each deployment requires its own unique WorkOS API key. This can be accomplished by creating a separate environment in your WorkOS dashboard for each on-prem customer.

Each WorkOS workspace comes with Staging and Production environments by default. To create a new environment for an on-prem customer:

The support team will create the environment, which will then be available in the environments dropdown menu in your WorkOS workspace.

To retrieve the client ID and API key for this environment, navigate to the API Keys section of the WorkOS dashboard where the values are available to download.

A common challenge with on-premise deployments is coordinating which traffic will be allowed by the firewall. Several strategies exist for allowing traffic to and from WorkOS to communicate with an on-prem deployment.

The most common approach is to deploy your application with the WorkOS integration to your customer’s on-prem environment configured the same as you would for cloud application users, then have the firewall rules or access control lists (ACLs) set to allow WorkOS API traffic.

WorkOS uses Cloudflare to ensure security and reliability. If you need to allowlist IP addresses for redirect requests, you can use the IP ranges listed in the Cloudflare documentation.

Firewall Ingress Rules (Incoming Traffic)

Ingress rules control external traffic entering your network. Some features of WorkOS require requests originating from our APIs directly to the on-prem installation, such as authentication callbacks, action callbacks, and webhooks.

Events can also be ingested with the Events API, which is the preferred method for event delivery in an on-prem deployment scenario since those requests will originate from your on-prem application infrastructure.

Firewall Egress Rules (Outgoing Traffic)

Egress rules manage traffic leaving your network to external services.

Key aspects include:

Best Practices

Implement a workflow of starting with restrictive default deny rules, then carefully opening only necessary ports and protocols to ensure that your integration with WorkOS is secure.

Another approach is to use a service like ngrok to manage traffic to and from the WorkOS API instead of modifying firewall rules. This approach allows you to implement WorkOS authentication without adjusting firewall configurations.

With ngrok, you can:

Implementation involves installing the ngrok client on your application server, establishing a tunnel to your application’s local port, and configuring your WorkOS integration to use the ngrok-provided public URL.

This approach requires configuration of third-party software and additional cost. ngrok offers different pricing tiers based on your needs, with paid plans providing features like persistent URLs, IP restrictions, and additional security controls essential for production environments.

For customers operating in air-gapped environments with no external network connectivity, cloud-based authentication services like WorkOS cannot be utilized as they require API connectivity.

However, many organizations with air-gapped environments have established security protocols that permit the deployment of approved third-party software within their isolated networks, as their security architecture already provides robust authentication mechanisms internally.

In these scenarios, we recommend a dual-implementation approach:

This approach allows you to maintain a consistent product experience across different deployment scenarios while accommodating the strict security requirements of air-gapped customers.