> ## 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 Endpoint SSO (OpenID Connect)

> Use miniOrange OIDC 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 explains how to configure 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

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

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

## 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 **OAUTH/OIDC** tile, and then click the **OAuth2/OpenID Connect** tile.
* On the **Add App** page, enter `ngrok OIDC` in the **Client Name** field, enter `https://idp.ngrok.com/oauth2/callback` in the **Redirect-URL** field, and then click **Save**.
* On the **View Apps** page, click **Select** in the **ngrok OIDC** app line, and then click **Edit**.
* On the **Edit Application** page, make note of the value of the **Client ID** field, click the **Click to reveal client secret** link, and then make note of the value of the **Client Secret** field.
* Click **Save**.
* On the **View Apps** page, click **Select** in the **ngrok** app line, and then click **OAuth Endpoints**.
* On the **OAuth Endpoints** page, make note of the URL of the **Discovery Endpoints** field.

## 2. Grant access to miniOrange users

miniOrange allows its users to access OIDC-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**.

## 3. Configure ngrok

ngrok can use miniOrange 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 miniOrange SSO:

  ```bash theme={null}
  ngrok http 3000 --oidc=MINIORANGE_OAUTH_URL \
  --oidc-client-id=MINIORANGE_CLIENT_ID \
  --oidc-client-secret=MINIORANGE_CLIENT_SECRET \
  ```

  Replace the following with values:

  * MINIORANGE\_OAUTH\_URL: The **Discovery Endpoint** URL you copied from miniOrange, without the `/.well-known/openid-configuration` suffix (for example, `https://login.xecurify.com/moas/discovery/v2.0/abcd1234`).
  * MINIORANGE\_CLIENT\_ID: The client ID you copied from miniOrange.
  * MINIORANGE\_CLIENT\_SECRET: The client secret you copied from miniOrange.

  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://miniorange-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 miniOrange:

```yaml theme={null}
on_http_request:
  - actions:
      - type: openid-connect
        config:
          issuer_url: 'YOUR_MINIORANGE_DISCOVERY_ENDPOINT_URL'
          client_id: 'YOUR_MINIORANGE_CLIENT_ID'
          client_secret: 'YOUR_MINIORANGE_CLIENT_SECRET'
          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://miniorange-sso-test.ngrok.app`).

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