> ## 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 (SAML)

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

<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 walks you through configuring Descope as the primary Identity Provider for 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 edges and tunnels and are redirected to Descope for authentication.

## What you'll need

* A Descope project with administrative rights and an Enterprise license to be able to create SAML applications.
* An ngrok Pay-as-you-go account with an authtoken or admin access to configure endpoints with SAML.

## 1. Fetch IdP metadata

### 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 `SAML` is selected under **Authentication protocol**, and then click **Create**.
* On the **ngrok** application page, click the download button next to **Descope Metadata (XML)** to download the Metadata file that you'll need later on.
  Make sure to leave this page open.
* **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**.

## 2. Configure ngrok

<Warning>
  The SAML Traffic Policy action is currently in [developer preview](/traffic-policy/actions/saml/). [Request access](https://dashboard.ngrok.com/developer-preview) to configure SAML via Traffic Policy.
</Warning>

Once you have developer preview access, create a `policy.yaml` file with the following content, replacing `YOUR_IDP_METADATA_XML` with the IdP metadata XML from Descope:

```yaml theme={null}
on_http_request:
  - actions:
      - type: saml
        config:
          idp_metadata: 'YOUR_IDP_METADATA_XML'
```

The SAML action generates your ngrok SP Entity ID and ACS URL based on your endpoint URL. Refer to the [SAML action documentation](/traffic-policy/actions/saml/) for how to retrieve these values to complete your IdP configuration.

## 3. Configure Descope

* Back in the Descope Console, under your **ngrok** application, select **Enter the connection details manually** under **Service Provider (SP)**.
* Enter the following values in the input fields and save the configuration.

  Replace the following with the values from the SAML action developer preview docs (see [SAML action documentation](/traffic-policy/actions/saml/)):

  * `NGROK_ACS_URL`: The ACS URL generated by the ngrok SAML action for your endpoint.
  * `NGROK_ENTITY_ID_URL`: The SP Entity ID generated by the ngrok SAML action for your endpoint.

## 4. Start a tunnel

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

Run the following command, replacing `3000` with your local web app port and `YOUR_DOMAIN` with your ngrok domain:

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

Copy the URL next to **Forwarding**. You use this URL to test the Descope authentication.

## 5. Test the integration

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