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

# Facebook OAuth

> Configure ngrok to authenticate users with Facebook OAuth. Register an app and add the OAuth callback URL.

This guide explains how to create a Facebook app and configure ngrok to use Facebook OAuth for user authentication.
For more detail, see the [Facebook app registration](https://developers.facebook.com/docs/apps#register) documentation.

## What you'll need

* A [Facebook Developer](https://developers.facebook.com/apps/) account (convert your account to a developer account if needed).
* Your ngrok authtoken and an endpoint with the OAuth action in its Traffic Policy.

## Create a Facebook app

1. Follow [Facebook's documentation for creating an app](https://developers.facebook.com/docs/development/create-an-app/), and when prompted to select a use case, choose **Authenticate and request data from users with Facebook Login**.
2. Connecting a business portfolio is optional. You can skip it, since it isn't required to authenticate users to your own service.

<Note>
  The **Authenticate and request data from users with Facebook Login** use case sets up standard [Facebook Login](https://developers.facebook.com/docs/facebook-login/), which lets visitors sign in with their personal Facebook account. This is the right fit for gating a service behind an ngrok endpoint.
  You don't need [Facebook Login for Business](https://developers.facebook.com/docs/facebook-login/facebook-login-for-business) or the [Business app type](https://developers.facebook.com/docs/development/create-an-app/app-dashboard/app-types/) unless your app needs ongoing access to business assets such as Pages or ad accounts.
</Note>

## Configure your app for ngrok

In your app dashboard, set the following:

* **Valid OAuth Redirect URIs**: add `https://idp.ngrok.com/oauth2/callback` in your app's Facebook Login settings.
* **App ID** and **App Secret**: note these from **App settings → Basic** for use in your Traffic Policy below.
* **Mode**: switch your app from **Development** to **Live** using the toggle at the top of the dashboard. In Development mode, only app admins, developers, and testers can sign in.

<Note>
  ngrok does not support Facebook's Server IP allowlisting.
</Note>

## Update your ngrok endpoint Traffic Policy

1. Access the [ngrok Dashboard Endpoints page](https://dashboard.ngrok.com/endpoints?sortBy=createdAt\&orderBy=desc) and locate an existing endpoint you'd like to add this to or create a new one.
2. In your traffic policy, add the following configuration:

<Note>
  You may add [any scopes](https://developers.facebook.com/docs/apps/review/login-permissions) that are required by your application with the following caveats.

  * Scopes which require a Facebook [app review](https://developers.facebook.com/docs/apps/review/#app-review) are unsupported.
  * ngrok will enforce that users [accept all permissions](https://developers.facebook.com/docs/facebook-login/handling-declined-permissions#reprompt) before completing authorization.
</Note>

<CodeGroup>
  ```yaml policy.yml theme={null} theme={null}
  on_http_request:
    - actions:
        - type: oauth
          config:
            provider: facebook
            client_id: '{your app''s oauth client id}'
            client_secret: '{your app''s oauth client secret}'
            scopes:
              - email
  ```

  ```json policy.json theme={null} theme={null}
  {
    "on_http_request": [
      {
        "actions": [
          {
            "type": "oauth",
            "config": {
              "provider": "facebook",
              "client_id": "{your app's oauth client id}",
              "client_secret": "{your app's oauth client secret}",
              "scopes": [
                "email"
              ]
            }
          }
        ]
      }
    ]
  }
  ```
</CodeGroup>

Click **Save** to validate and update your traffic policy.

### Configure access control

Optionally, configure access control to your service by only allowing specific users or domains.

<CodeGroup>
  ```yaml policy.yml theme={null} theme={null}
  on_http_request:
    - expressions:
        - '!(actions.ngrok.oauth.identity.email in [''me@example.com''])'
      actions:
        - type: deny
  ```

  ```json policy.json theme={null} theme={null}
  {
    "on_http_request": [
      {
        "expressions": [
          "!(actions.ngrok.oauth.identity.email in ['me@example.com'])"
        ],
        "actions": [
          {
            "type": "deny"
          }
        ]
      }
    ]
  }
  ```
</CodeGroup>

## Further resources

* [Handling declined permissions](https://developers.facebook.com/docs/facebook-login/handling-declined-permissions)
* [App review](https://developers.facebook.com/docs/apps/review)

## User permission revocation

Facebook allows revocation of any permission as part of the authorization flow.
ngrok enforces that users initially grant all configured permissions.
After endpoint authorization, users may selectively revoke permissions.
If your application requires more than the `default` or `email` scope, follow [Facebook's rules](https://developers.facebook.com/docs/facebook-login/handling-declined-permissions#reprompt) for handling revoked permissions without violating terms of use.