Using Descope With On-Premises B2B Customers

As more enterprises adopt hybrid and private cloud deployment strategies, it’s increasingly common for SaaS companies to offer on-premises versions of their applications. These apps must still support enterprise-grade features like SSO, MFA, user provisioning, and audit trails—all without compromising security or usability.

Descope is uniquely positioned to support such scenarios, providing a flexible identity platform that works equally well in the cloud and within customer-hosted environments.

This guide explores how to integrate Descope into an on-premises or hybrid environment, with recommendations on secure communication, network configuration, and common deployment patterns.

Key deployment considerations

When deploying an app to a customer’s data center or private VPC, you’ll need to:

• Isolate credentials: Use a static API key per customer/project

• Ensure connectivity: Allow your customer’s environment to communicate with Descope APIs

• Support secure redirects: For authentication flows, SSO, or webhook-based events

• Integrate with customer-managed IdPs: Especially when using SAML or OIDC-based SSO with local infrastructure like ADFS

Using a static Descope Project key

Each customer deployment should have its own dedicated Descope project and API key. This ensures:

• Clean isolation between customer data

• Easy revocation and rotation of keys

• Better auditing and operational control

Follow these steps to set up your Descope Project key:

• Log in to the Descope Console

• Create a new Project per on-prem customer

• Navigate to Project Settings > API Keys

• Securely distribute the Project ID, Public Key, and Management Key to your customer environment

• Configure these as environment variables or in your app’s secrets manager

💡 You can also create separate tenants within a project to support multi-org logic inside a single customer deployment.

Enabling network access to Descope

To enable Descope features such as SSO, MFA, hosted authentication Flows, and webhooks in an on-premises environment, the deployed application must be able to communicate with the Descope cloud platform.

Depending on your customer’s network posture, there are two primary strategies to establish this connectivity:

• Strategy 1: Configure firewall rules and ACLs to allow direct traffic to/from Descope

• Strategy 2: Use a reverse proxy tunnel (e.g., ngrok or Cloudflare Tunnel) to establish secure connectivity without modifying firewall rules

Strategy 1: Configure firewall rules or ACLs

This is the preferred approach for production environments where stable, direct communication is required.

Descope endpoints to allow

Ingress rules (incoming traffic to customer environment)

Some Descope features require initiating HTTP(S) requests from Descope to the on-premises application. These include:

• SSO and OAuth redirect responses

• Hosted Flow redirect responses

• Webhook notifications (e.g., login events, step-up MFA success)

To support these use cases:

• Allow inbound HTTPS traffic on port 443

• Restrict access to known callback or webhook routes such as:

  • https://your-customer-app.com/callback

  • https://your-customer-app.com/descope/webhook

• (Optional) Use IP-based allowlisting. Descope routes all outbound traffic through Cloudflare’s published IP ranges. Customers can restrict ingress to these IPs for enhanced security.

Egress rules (outgoing traffic from customer environment)

The on-premises application must initiate secure requests to Descope for operations such as:

• Session validation

• Authentication API calls

• Retrieving hosted Flow assets

To support these:

• Allow outbound HTTPS traffic on port 443

• Permit access to:

  • https://api.descope.com

  • https://static.descope.com

• Ensure DNS resolution is enabled for both domains

• If an outbound proxy is used, ensure TLS inspection does not interfere with certificate validation or SDK behavior

Strategy 2: Use a reverse proxy tunnel (e.g., ngrok or Cloudflare Tunnel)

This approach is ideal when the customer cannot or does not want to modify firewall rules. A secure tunnel exposes specific local ports or paths to the internet, enabling Descope to send requests as needed.

• No changes required to the customer’s firewall or ACLs

• Suitable for testing, proof-of-concept deployments, and high-security environments

• Allows secure HTTPS-based communication for authentication and event delivery

ngrok setup guide

Step 1: Install ngrok

Download and install the ngrok CLI:

• macOS/Linux (via Homebrew):

brew install ngrok/ngrok/ngrok

• Windows: Download the installer from https://ngrok.com/download

Step 2: Authenticate (recommended for reserved domains)

If you have a paid ngrok plan and want to use static subdomains or additional access control:

ngrok config add-authtoken <your-ngrok-token>

Step 3: Start the tunnel

Assuming your application is running locally on port 3000:

ngrok http 3000

This will generate a temporary HTTPS URL such as:

Forwarding https://brisk-horse.ngrok.io → http://localhost:3000

Step 4: Configure Descope

In the Descope Console:

• Set your redirect and webhook URLs to use the ngrok domain:

  • https://brisk-horse.ngrok.io/callback

  • https://brisk-horse.ngrok.io/descope/webhook

This ensures Descope can successfully return authentication responses and deliver events to the on-premises application.

Cloudflare Tunnel setup (alternative)

If your customer already uses Cloudflare or prefers a corporate-grade tunneling service:

Step 1: Install cloudflared

Instructions: Cloudflare Tunnel Installation Guide

Step 2: Authenticate and create a tunnel

cloudflared tunnel login
cloudflared tunnel create descope-tunnel

Step 3: Configure routing and DNS

cloudflared tunnel route dns descope-tunnel login.customer-domain.com

Step 4: Start the tunnel

cloudflared tunnel run descope-tunnel

Step 5: Configure Descope

Use the public domain (e.g., https://login.customer-domain.com/callback) in your Descope SSO and webhook configuration.

Security considerations for Tunnels

• Ensure your ngrok or Cloudflare Tunnel configuration includes basic auth, access control, or IP restrictions

• Use persistent URLs (available in paid plans) for production environments

• Monitor tunnel uptime and reconnect if interrupted

• Validate certificates and ensure TLS is enabled

Summary: Choosing between the two approaches

Example: Embedded admin dashboard for healthcare SaaS

A B2B healthcare platform offers an on-premises deployment of their admin dashboard to hospitals with strict compliance requirements. The deployment:

• Lives within a hospital-managed AWS VPC

• Uses ADFS for employee authentication

• Requires SSO with SAML and step-up MFA

• Must allow login redirect and webhook events

Here's how the Descope integration works:

• A dedicated Descope Project with SAML SSO configured via the SSO Setup Suite

• A static redirect URL configured via a secure tunnel with a domain like hospital-ngrok.io

• Egress rules allowing access to api.descope.com

• Login flow triggers MFA via Descope Flows, even though the IdP is on-premises

This setup enabled full compliance with internal IT policies while allowing Descope to manage authentication seamlessly.

Air-gapped environments

Fully isolated or air-gapped environments—such as those in defense, finance, or government—do not allow any internet access. In these cases, cloud-based identity services like Descope cannot be directly used.

Recommended dual strategy:

1. For connected environments: Continue using Descope for SSO, MFA, and Flows

2. For air-gapped deployments:

   • Build a lightweight plugin that mimics Descope’s JWT issuance locally

   • Use internal IdPs (e.g., Active Directory) with your own auth logic

   • Mirror your Descope integration patterns (e.g., claims, roles, sessions) to maintain application consistency

Though not directly connected, this hybrid model allows your app to maintain a uniform experience across deployments while satisfying even the most stringent network restrictions.

Connecting to on-premises identity providers (e.g., ADFS)

Descope supports IdP-initiated and SP-initiated SSO via both SAML and OIDC, making it easy to connect with common on-premises identity providers like:

• Microsoft ADFS

• PingFederate

• ForgeRock

• Shibboleth

• Keycloak in on-premises mode

To set this up, use the SSO Setup Suite in the Descope Console, which provides a step-by-step guided configuration flow to:

• Upload or fetch IdP metadata

• Set ACS / Redirect URIs

• Configure attribute mappings (email, name, groups, etc.)

• Test and verify the SSO connection securely

💡 Descope supports both tenant-specific and project-wide SSO connections—ideal for multi-tenant SaaS platforms.

Securing complex enterprise environments with Descope

Descope brings flexible, modern authentication to even the most technically demanding enterprise scenarios. With built-in support for SSO, MFA, device security, and webhook-driven flows, you can confidently deploy your product into customer-owned infrastructure without sacrificing security or developer experience.

For help getting started with on-premises deployments, reach out to our support team or explore our documentation.