​
Prerequisites

Before starting this integration, ensure you have:
  1. A Hanko Cloud account and project. Set up your account here if you haven’t already.
  2. A Facebook developer account. Visit the Facebook developer portal and select Login to create an account.

​
Get your provider redirect URL

You’ll need to configure a redirect URL in your Facebook application. This URL determines where Facebook redirects users after successful authentication. The redirect URL combines your Hanko API base URL with the /thirdparty/callback endpoint. To find your redirect URL:
  1. Sign in to cloud.hanko.io.
  2. Select your Organization.
  3. Select your Project.
  4. In the left sidebar, click Settings, then select Social connections.
  5. Find your redirect URL in the Redirect URL input.
Hanko Redirect URL
You need the redirect URL for creating a new Facebook application in the next step.

​
Create a Facebook application

  1. Navigate to and log in to the Facebook developer portal.
  2. In the top navigation, select Apps.
  3. Click Create app in the center of the page or on the top right.
Facebook apps dashboard
  1. Enter your app details and click Next.
Facebook app details prompt on app creation
  1. On the Use cases view, select Authenticate and request data from users with Facebook Login.
  2. Click Next.
Facebook use cases prompt on app creation
  1. On the Business view, select I don't want to connect a business portfolio yet (or connect your existing business portfolio if available).
  2. Click Next.
Facebook business portfolio connection prompt on app creation
  1. On the Create app view, click Go to dashboard.
Facebook finalize app creation
  1. On the app dashboard, click Customize adding a Facebook Login button in the Add and customize use cases section.
Facebook customize login use case
  1. In the Customize use case view, select Permissions in the left sidebar.
  2. Click the add button for the email permission in the permissions table to enable email access.
Facebook customize login use case permissions by adding the email permission
  1. In the Customize use case view, select Settings in the left sidebar.
  2. Under Valid OAuth Redirect URIs, add the redirect URL you retrieved from the Hanko Console.
Facebook customize login use case settings by adding valid OAuth redirect URLs
When testing locally, you don’t need to add localhost redirect URLs as Facebook automatically allows all http://localhost redirects.

​
Get your client ID and secret

  1. Navigate to the App settings > Basic for your app.
  2. Copy the App ID.
  3. Show and copy the App Secret.
Facebook customize login use case settings by adding valid OAuth redirect URLs

​
Configure Facebook credentials in Hanko

  1. In the Hanko Cloud Console, navigate to your project Settings and select URLs.
  2. Configure a Default Redirect URL - the frontend URL where Hanko redirects users if authentication fails. For applications using hanko-elements web components, this should be the page containing the component to handle errors properly.
  3. Configure your Allowed Redirect URLs - the frontend URLs where Hanko can redirect users after successful authentication. For hanko-elements applications, this should be the page containing the authentication component.
    The allowed redirect URL supports wildcard matching through globbing:
    • https://*.example.com matches https://foo.example.com and https://bar.example.com.
    • https://foo.example.com/* matches URLs like https://foo.example.com/page1 and https://foo.example.com/page2.
    • Use ** to act as a super-wildcard/match-all.
Hanko Redirect URLs configuration
  1. Navigate to your project Settings and select Social connections.
  2. In the Providers section, find Facebook and expand its configuration.
  3. Enable the Facebook provider using the toggle switch.
  4. Enter the Facebook App ID as the Client ID.
  5. Enter the Facebook App Secret as the Client Secret.
  6. Click Save to apply your configuration.
Configure Facebook provider in Hanko Cloud social connection settings

​
Implement Facebook login in your frontend

You can integrate Facebook authentication using either:
Follow our quickstart guides to integrate the <hanko-auth> component from @teamhanko/hanko-elements into your application. Once configured, the component will automatically display a Facebook sign-in button in the login interface.
Make sure to configure the page the web component is embedded on as your error redirect URL as well as an allowed redirect URL (see the previous step).
After successful Facebook authentication, Hanko issues a session cookie and the component continues its normal flow. Authentication errors are automatically captured and displayed within the component.

​
Publish your app

After following this guide, your Facebook app will have an Unpublished status, which limits its usage to developers and testers. To allow all users to authenticate with Facebook, you must submit your app for Facebook’s App Review process and get it approved for public use.