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

> Secure access to your ngrok endpoints with Frontegg 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 Frontegg as the primary Identity Provider for ngrok endpoints using single sign-on (SSO).
By integrating Frontegg SSO with ngrok, you can:

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

## What you'll need

* A Frontegg 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. Download the IDP metadata

* Access the Frontegg Portal and sign in using your Frontegg administrator account.
* On the left menu, click your environment under **Environments** and then click **Env settings**.
* On the **General Settings** page, copy both the **Client ID** and **API Key** values.
* Open a terminal window and run the following command to get an access token:

  ```bash theme={null}
  curl --request POST \
    --url https://api.frontegg.com/auth/vendor/ \
    --header 'accept: application/json' \
    --header 'content-type: application/json' \
    --data '{"clientId": "CLIENT_ID","secret": "API_KEY"}'
  ```

  Replace the following with values:

  * CLIENT\_ID: The client ID value you copied before.
  * API\_KEY: The API key value you copied before.
* Copy the value of the **token** attribute from the response.
* In the same terminal window, run the following command to download the metadata XML file from Frontegg:

  ```bash theme={null}
  curl --location --request POST 'https://api.frontegg.com/oauth/resources/configurations/saml/v1/https%3A%2F%2Ftemporary' \
  --header 'frontegg-vendor-host: YOUR_FRONTEGG_HOST_URL' \
  --header 'Authorization: Bearer TOKEN' \
  --header 'Content-Type: application/json' \
  --data-raw '{
     "acsUrl": "https://temporary",
     "entityId": "https://temporary"
  }'
  ```

  Replace the following with values copied on previous steps:

  * YOUR\_FRONTEGG\_HOST\_URL: The value of the **Domain name** from the **Env settings > Domains** tab.
  * TOKEN: The token you copied before.
* Copy the response and save it as the `idp_metadata.xml` file locally on your desktop.
  The response starts with `<EntityDescriptor` and ends with `</EntityDescriptor>`.
  Anything different may be an error.

## 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 Frontegg:

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

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**. You use this URL to test the integration.

## 3. Configure Frontegg

* In the same terminal window in which you ran the previous commands, run the following command to create a SAML configuration related to your ngrok SAML endpoint:

  ```bash theme={null}
  curl --location --request POST 'https://api.frontegg.com/oauth/resources/configurations/saml/v1/URL-ENCODED-NGROK-ENTITY-ID' \
  --header 'frontegg-vendor-host: YOUR_FRONTEGG_HOST_URL' \
  --header 'Authorization: Bearer TOKEN' \
  --header 'Content-Type: application/json' \
  --data-raw '{
     "acsUrl": "NGROK_ACS_URL",
     "entityId": "NGROK_ENTITY_ID_URL"
  }'
  ```

  Replace the following with the values copied on previous steps:

  * URL-ENCODED-NGROK-ENTITY-ID: URL-Encoded value of the ngrok **Entity ID** retrieved from the SAML action (see the [SAML action documentation](/traffic-policy/actions/saml/) for how to retrieve these values).
  * YOUR\_FRONTEGG\_HOST\_URL: The value of the **Domain name** from the **Env settings > Domains** tab.
  * TOKEN: The Frontegg token you copied before.
  * NGROK\_ACS\_URL: The value of the ngrok **ACS URL** retrieved from the SAML action developer preview docs.
  * NGROK\_ENTITY\_ID\_URL: The value of the ngrok **Entity ID** retrieved from the SAML action developer preview docs.

## 4. Update Frontegg login method

* Access the Frontegg Portal and sign in using your Frontegg administrator account.
* On the left menu, click your environment under **Environments**, click **Authentication**, and then click **Login method**.
* On the **Select your login method** page, make sure **Hosted login** is selected, and click **Add new** twice.
* In the first empty field, enter your ngrok forwarding URL (for example, `https://123456789.ngrok.app/`).
  In the second field, enter the **ACS URL** retrieved from the SAML action (see the [SAML action documentation](/traffic-policy/actions/saml/)).
* Click **Save**.

## 5. 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 Frontegg authentication.

## Grant access to Frontegg users

Create a Frontegg user:

* On the left menu of the Frontegg Portal, click your environment, click **Backoffice**, click **Accounts**, and then click **Add New**.
* On the **Add new account** popup, enter a name for the account, `ngrok.com` in the **Domain** field, and then click **Save**.
* On the left menu, click **Backoffice**, click **Users**, and then click **Add New**.
* On the **Add new user** popup, enter a name and email, select the account you have created, and then click **Save**.
  By default, the user is assigned the **Admin** role.

## Test the integration

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