Integration detail

Overview

You can set up Facebook as an Identity Provider (IdP) for your application so your users can sign in to your application using their Facebook account. Okta manages connections to IdPs for your application, sitting between your application and the IdP that authenticates your users.

Prerequisites

Installing Facebook as an IdP requires:

• An Okta organization within the okta.com or oktapreview.com domains. You can create a developer org for free.
• An external application that requires user authentication.
• A Facebook for Developers account if you don't already have one.

Procedure

1. Register your application in Okta.
2. Create a client application on Facebook.
3. Create the identity provider in Okta.
4. Create the authorization URL.

Register your app integration in Okta

An Okta app integration is required to consume the response from Facebook after authentication and authorization. You can use either an existing OpenID Connect (OIDC) app integration or create a new one. Users that sign in for the first time are created within Okta and assigned to your app integration.

1. Sign in to your Okta organization with your administrator account.
2. From the Admin Console side navigation, click Applications > Applications.
3. Click Add Application.

If you want to add an existing OIDC app integration from the Okta catalog:

1. Enter the name of the app integration in the Search... text box.
2. On the catalog page for the app integration, click Add.
3. Enter a label for your copy of this app integration. Click Done to add it to your org.
4. On the Assignments tab, click Assign to assign the app integration to any user or group in your org. Click Done when the assignments are complete.

If you need to create a new OIDC app integration:

1. Click Create New App.
2. Select the appropriate Platform for your external application. Select OpenID Connect for the Sign on method, and click Create.
3. Enter a name and, optionally, upload a logo for your new app integration.
4. Add one or more Login redirect URIs. This URI is the Redirect URI location where the user is directed after they authenticate with Facebook.
5. Click Save to finish creating your Okta app integration.
6. On the General tab of your Okta app integration settings page, click Edit in the General Settings section.
7. For the Allowed grant types setting, enable the Implicit (Hybrid) option. The Allow ID Token with implicit grant type option is selected automatically. Using the Implicit flow streamlines authentication by returning tokens without introducing any unnecessary additional steps. It allows you to get an ID token quickly, which makes it easy to test your configuration. The Authorization Code grant flow is also supported.
8. Click Save to confirm your changes.
9. On the Assignments tab, you can assign the app integration to a specific user or group. Click Done when the assignments are complete.

To get the client credentials for your app integration:

1. On the General tab, copy the Client ID value from the Client Credentials section to complete the authorization URL step.

Create a client application on Facebook

1. On the Facebook for Developers site, create an app using the Create an App guide. When asked what you need your app to do, select Build Connected Experiences.

2. After you create the app, click Set Up in the Facebook Login tile on the Add Products to Your App page of the Facebook for Developers Console.

3. Select Web as the platform for your app.

4. In the Site URL box, enter the Okta redirect URI. The redirect URI sent in an authorization request from the client needs to match the redirect URI in the IdP. This URI is where the IdP returns the authentication response (the access token and the ID token). It needs to be a secure domain that you own. This has the same structure for most IdPs in Okta and is constructed using your Okta subdomain and the callback endpoint.

   For example, if your Okta subdomain is called company, then the URL is: https://company.okta.com/oauth2/v1/authorize/callback. If you have configured a custom domain in your Okta Org, use that value to construct your redirect URI, such as https://login.company.com/oauth2/v1/authorize/callback.

5. Click Save, then click Next until you exit the Facebook wizard.

6. In the dashboard for your Facebook app, open Facebook Login > Settings.

7. Under Client OAuth Settings, find the Valid OAuth Redirect URIs section and paste the redirect URI. Click Save Changes at the bottom of the page.

8. In the dashboard, open Settings > Basic.

9. Copy the App ID and the App Secret values so you can add them to the Okta configuration in the next section.

Note that there may be additional settings on the Facebook App Dashboard that you can configure for the app. The steps in this guide address the quickest route to setting up Facebook as an IdP with Okta. See the Facebook documentation for more information on additional configuration settings.

Add the identity provider in Okta

1. In the Okta Admin Console for your org, click Security > Identity Providers.
2. Click Add Identity Provider, then Add Facebook.
3. Fill in the details for your Facebook connection:
   • Name — Enter a name for this IdP configuration.
   • Client ID — Paste the generated App ID from your Facebook application.
   • Client Secret — Paste the generated App Secret from your Facebook application.
   • Scopes — Leave the defaults. By default, Okta requires the user's email attribute when creating and linking the user to Okta Universal Directory. For more information about these settings as well as the Advanced Settings, see Social Identity Provider Settings.
4. Click Add Identity Provider.
5. Click the arrow next to the IdP name to expand. Copy both the Authorize URL and Redirect URI values.

Create the authorization URL

When you created the identity provider in Okta, it generated an Authorize URL that contained several blank parameters to test the authorization flow when the user authenticates with Facebook.

Paste that Authorize URL to a text editor and replace the blank parameters with the following values:

• client_id — Use the Client ID value that you obtained from your Okta app integration. For example, 0oawjqpb2wcUAWM8C0h7. This value isn't the App ID from your Facebook application.

• response_type — Determines which flow is used. For the Implicit flow, set this to id_token. For the Authorization Code flow, set this to code.

• response_mode — Determines how the authorization response should be returned. Set this value to fragment.

• scope — Determines the claims returned in the ID token. Include the scopes that you want to request authorization for and separate each with a %20 (space character). You need to include at least the openid scope. You can request any of the standard OIDC scopes about users, such as profile and email, as well as any custom scopes specific to your IdP.

• redirect_uri — The location where Okta returns a browser after the user finishes authenticating with Facebook. This URL should start with https and must match one of the redirect URIs that you configured in your app integration.

• state — Protects against cross-site request forgery. This can be set to any value.

• nonce — A string included in the returned ID token. Use it to associate a client session with an ID token and to mitigate replay attacks. This can be set to any value.

For a full explanation of all of these parameters, see the /authorize request parameters.

An example of a complete URL looks like this:

https://myapp1.okta.com/oauth2/v1/authorize?idp=0oaqtill1MKXRE6Av4x6&client_id=0oawjqpb2wcUAWM8C0h7&response_type=id_token&response_mode=fragment&scope=openid%20email&redirect_uri=https%3A%2F%2Fexample.com%2Foauth2%2Fv1%2Fauthorize%2Fcallback&state=WM6D&nonce=YsG76jo

Test

To test your authorization URL, enter the complete authorization URL in a browser. Testing this link in your browser's privacy or incognito mode avoids false positive or negative results.

Alternatively, you can create a simple web page with a link that simulates the user sign-in attempt. The HREF value for that link is the authorize URL:

<a href="https://myapp1.okta.com/oauth2/v1/authorize?idp=0oaqtill1MKXRE6Av4x6&client_id=0oawjqpb2wcUAWM8C0h7&response_type=id_token&response_mode=fragment&scope=openid%20email&redirect_uri=https%3A%2F%2Fexample.com%2Foauth2%2Fv1%2Fauthorize%2Fcallback&state=WM6D&nonce=YsG76jo">Sign in with Facebook</a>

If everything is configured properly:

• After the user clicks the link, they get a prompt to sign in with Facebook.
• After successful authentication, the user is redirected to the redirect URI that you specified, along with an id_token= fragment in the URL. The value of this parameter is your Okta token.
• If something is configured incorrectly, the authorization response contains error information to help you resolve the issue.

This tests your authorization URL as an HTML link. For information on using the Okta Sign-in Widget, Okta-hosted Sign-in Page, or AuthJS to test your authorization, see Use the Identity Provider to sign in.

Related content

• Okta - Add an external Identity Provider
• Facebook - Facebook Login documentation

Support

If you need help or have an issue, post a question in our Developer Forum.