Using Descope With On-Premises B2B Customers

Kevin Gao Head of AI Strategy and DX

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

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:

grok 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

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

Securing complex enterprise environments with Descope

Descope brings flexible, modern B2B CIAM 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.