> ## Documentation Index
> Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Secure your endpoints with Descope SSO (OpenID Connect)

> Secure access to your ngrok endpoints with Descope single sign-on (SSO) using OpenID Connect.

<Note>
  This guide refers to using SSO to authenticate access to your **endpoints**. You cannot use these instructions to set up SSO for logging into your ngrok account in the dashboard.
</Note>

This guide explains how to configure Descope as the primary Identity Provider for your ngrok endpoints using single sign-on (SSO).
By integrating Descope SSO with ngrok, you can:

* Restrict access to ngrok endpoints only to users authenticated via Descope
* Use Descope security policies and MFA authenticators
* Use the Descope Console to facilitate access to ngrok apps

The ngrok integration with Descope supports SP-Initiated SSO.
In this mode, users access ngrok endpoints and are redirected to Descope for authentication.

## What you'll need

* A Descope account with administrative rights to a Descope Project.
* An ngrok Pay-as-you-go account with an authtoken or admin access to configure endpoints with OpenID Connect.

## 1. Configure Descope

### Add the ngrok app in Descope

* Open the Descope Console.
* On the left menu, click **Applications**, and then click **+ Application** in the top right corner.
* In the popup window, enter `ngrok` in the **Name** field, make sure that `OIDC` is selected under **Authentication protocol**, and then click **Create**.
* On the **ngrok** application page, make a note of the **Issuer** URL.
* **Optional**: If you wish to change the Auth Hosting URL to use a different flow for ngrok SSO, you can change that on this page, and click **Save**.

### Create a client secret in Descope

* Go to **Access Keys** in the Descope Console.
* Click **+ Access Key** in the top right corner.
* In the popup window, enter `ngrok` in the **Name** field, change the **Expiration** time to whatever you prefer, and then click **Generate Key**.
* Once the **Access Key** has been created, make a note of it for later.

## 2. Configure ngrok

ngrok can use Descope SSO in two ways:

* From the ngrok CLI (using the `--oidc` parameter)
* From the ngrok dashboard

### **Option 1**: ngrok CLI

<Note>
  This tutorial assumes you have an app running locally (for example, on `localhost:3000`) with the ngrok client installed.
</Note>

* Launch a terminal.
* Enter the following command to launch an ngrok tunnel with Descope SSO:

  ```bash theme={null}
  ngrok http 3000 --oidc=DESCOPE_ISSUER_URL \
  --oidc-client-id=DESCOPE_CLIENT_ID \
  --oidc-client-secret=DESCOPE_CLIENT_SECRET \
  ```

  Replace the following with values:

  * `DESCOPE_ISSUER_URL`: This is your Issuer URL that you copied from the **Applications** page earlier.
  * `DESCOPE_CLIENT_ID`: This is your Descope Project ID, which can be found under **Project Settings** in the Descope Console.
  * `DESCOPE_CLIENT_SECRET`: This is the Descope Access Key that you created from earlier.

  Alternatively, add the `--url YOUR_DOMAIN` argument to get your custom URL, replacing `YOUR_DOMAIN` with your URL of preference.
* Copy the URL available next to **Forwarding** (for example, `https://descope-sso-test.ngrok.app`).
* Skip to **Step 3**.

### **Option 2**: Traffic Policy

<Note>
  This tutorial assumes you have an app running locally (for example, on `localhost:3000`) with the ngrok client installed.
</Note>

Create a `policy.yaml` file with the following content, replacing the placeholder values with those copied from Descope:

```yaml theme={null}
on_http_request:
  - actions:
      - type: openid-connect
        config:
          issuer_url: 'YOUR_DESCOPE_ISSUER_URL'
          client_id: 'YOUR_DESCOPE_PROJECT_ID'
          client_secret: 'YOUR_DESCOPE_ACCESS_KEY'
          scopes:
            - openid
            - profile
            - email
```

Launch an ngrok tunnel with this policy:

```bash theme={null}
ngrok http 3000 --traffic-policy-file policy.yaml --url YOUR_DOMAIN
```

Copy the URL next to **Forwarding** (for example, `https://descope-sso-test.ngrok.app`).

## 3. Test the integration

* In your browser, launch an incognito window.
* Access your ngrok endpoint (for example, `https://descope-sso-test.ngrok.app` or using the copied URL).
* You should be prompted to log in with Descope.
* After logging in, you should be able to see your web app.