# Using Descope With On-Premises B2B Customers

[Kevin Gao](/content/blog/author/kevin-gao/index.html)
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](https://app.descope.com/)
- 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](/content/use-cases/sso/index.html), [MFA](/content/use-cases/mfa/index.html), 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

| **Endpoint** | **Purpose** |
| --- | --- |
| https://api.descope.com | Descope APIs: authentication, user/session management |
| https://static.descope.com | Hosted Flows, JavaScript SDK, web components |

### 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](https://www.cloudflare.com/ips/). 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):
```powershell
brew install ngrok/ngrok/ngrok
```
- Windows: Download the installer from [https://ngrok.com/download](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:
```powershell
ngrok config add-authtoken <your-ngrok-token>
```

**Step 3:** Start the tunnel

Assuming your application is running locally on port `3000`:
```powershell
grok http 3000
```

This will generate a temporary HTTPS URL such as:
```html
Forwarding https://brisk-horse.ngrok.io → http://localhost:3000
```

**Step 4:** Configure Descope

In the [Descope Console](https://app.descope.com/):
- 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](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install/)

**Step 2:** Authenticate and create a tunnel
```powershell
cloudflared tunnel login
cloudflared tunnel create descope-tunnel
```

**Step 3:** Configure routing and DNS
```powershell
cloudflared tunnel route dns descope-tunnel login.customer-domain.com
```

**Step 4:** Start the tunnel
```powershell
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

| **Feature** | **Firewall Rules (Strategy 1)** | **Reverse Tunnel (Strategy 2)** |
| --- | --- | --- |
| Best for Production | Yes | No (unless using paid plan) |
| Minimal IT Involvement | No | Yes |
| Custom Domain Support | Yes | Yes |
| Persistent URLs | Yes | Only with paid plans |
| Secure HTTPS Communication | Yes | Yes |
| Supports Webhooks & Redirects | Yes | Yes |
| Deployment Complexity | Moderate | Low |

## 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](/content/blog/post/sso-setup-suite/index.html) 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](/content/use-cases/b2b-apps/index.html) 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.