> ## 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.

# miniOrange SSO (SAML)

> Use miniOrange SAML to secure access to ngrok endpoints with single sign-on.

<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 miniOrange as the primary Identity Provider for ngrok tunnels using single sign-on (SSO).
By integrating miniOrange SSO with ngrok, you can:

* Restrict access to ngrok tunnels only to users authenticated via miniOrange
* Use miniOrange security policies and MFA authenticators
* Use miniOrange's Dashboard to facilitate access to ngrok apps

## What you'll need

* A miniOrange account with administrative rights to create apps.
* An ngrok Pay-as-you-go account with an authtoken or admin access to configure endpoints with SAML.

## 1. Configure miniOrange

* Access miniOrange and sign in using your miniOrange administrator account.
* On the **Dashboard** page, click **Apps** on the left menu, click **Add Application**, click the **SAML/WS-Fed** tile, and then click the **Custom SAML App** tile.
* On the **Add App** page, enter `ngrok SAML` in the **Custom Application Name** field.
* Click the **SSO** tab, enter temporary values (such as `https://temporary`) in both the **SP Entity ID or Issuer** and the **ACS URL** fields, and then click **Save**.

## 2. Download the IdP metadata

* On the **View Apps** page, click **Select** in the **ngrok** app line, and then click **Metadata**.
* On the **View IDP Metadata** page, click **Show Metadata Details**, click **Download Metadata**, and then save the XML file on your desktop.

## 3. 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 miniOrange:

```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.

## 4. Obtain the SP metadata

The SAML action generates your ngrok SP Entity ID and ACS URL based on your endpoint URL. Once you have [developer preview access](https://dashboard.ngrok.com/developer-preview), refer to the [SAML action documentation](/traffic-policy/actions/saml/) for how to retrieve these values.

## 5. Link miniOrange with ngrok

* On the miniOrange Dashboard, click **Apps** on the left menu, click **Select** in the **ngrok SAML** app line, and then click **Edit**.
* On the **Edit Application** page, enter the SP Entity ID and ACS URL from the [SAML action documentation](/traffic-policy/actions/saml/) (see [Obtain the SP metadata](#4-obtain-the-sp-metadata)) into the corresponding fields.
* On the **Edit Application** page, click **Save**.

## 6. 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 miniOrange authentication.

## Grant access to miniOrange users

miniOrange allows its users to access SAML-integrated apps.
To create a user, follow the instructions below:

* On the left menu of the miniOrange Dashboard, click **Users** and then click **User List**.
* On the **Users** page, click **Add User**, enter values for the **Email**, **Username**, **First Name**, **Last Name**, and **Password** fields, and then click **Create User**.

## Test the integration

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