Navigation

Facebook Authentication

Facebook authentication allows users to log into a MongoDB Stitch application with an existing Facebook profile. This is accomplished by adding Facebook Login to your client application, and configuring it to work with MongoDB Stitch’s authentication framework.

Create OAuth Client ID Credentials

Follow the directions in Facebook - Add a New App to create a new Facebook app that you’ll associate with your MongoDB Stitch application.

  • Once created, go to the + Add Product view for your application. Click Set Up for Facebook Login. The screen should display the Quickstart instructions. To incorporate into your application, follow the Quickstart instructions for your platform.

  • When finished, in the Facebook Login > Settings, add the following entry in Valid OAuth redirect URIs:

    https://stitch.mongodb.com/api/client/v2.0/auth/callback
    
  • Go to the Dashboard view for your application. Make note of the App ID and App Secret, which you will need to configure the Facebook authentication provider in MongoDB Stitch.

If you are building a mobile client application, follow the additional steps below for your specifc platform:

Additional Steps For Android Applications

Additional Steps For iOS Applications

Enable and Configure Facebook Authentication in MongoDB Stitch

Once you have the App ID and App Secret, use the following procedure in the MongoDB Stitch admin console to enable and configure the Facebook authentication provider:

  1. Click Authentication. The page displays the Authentication Providers.

  2. For Facebook, click the Edit button.

  3. In the Edit Provider dialog,

    1. Switch Facebook to enabled. If enabling Facebook authentication for the first time, ignore this step.

    2. Enter values for the following fields as appropriate:

      Field Description
      Client ID Required. The App ID of the Facebook app you’re associating with your MongoDB Stitch application.
      Client Secret Required. The App Secret of the Facebook app you’re associating with your MongoDB Stitch application.
      Redirect URIs

      Required for web applications. These are the URIs that MongoDB Stitch is allowed to redirect the end user to after completing the authentication step. If a redirect URL is specified in the authentication process and it’s not an exact match with one of the URIs specified in this configuration setting, there will be an error.

      For example, if MongoDB Stitch needs to redirect to http://myapp.example.com/ after authentication, you must specify the URI exactly in this list, including the http and the trailing slash.

      Domain Restrictions

      Optional. If specified, accounts can only be created in MongoDB Stitch through this authentication provider when the primary email address of the Facebook address has one of the domains specified here.

      For example, if mycompany.com and mycompany.org are specified here, Facebook accounts where the primary email address is jane@mycompany.com or john@mycompany.org would be permitted, whereas emails like bob@gmail.com would be restricted.

      If you’ve specified any domain restrictions, you must also expose the email address field in the Metadata Fields setting.

      Metadata Fields

      Optional. The fields selected here will determine which fields from the user’s Facebook profile are exposed in the data field of the user in MongoDB Stitch.

      If you’ve specified any domain restrictions, you must at a minimum expose the email address field.

    3. Click Save.

Incorporate into a Client Application

In web applications, the Facebook authentication provider works by redirecting the user to a Facebook webpage that handles authentication, and then redirecting the user back to your application with a MongoDB Stitch session. You can use either the default redirect URL for your application or a specific redirect URL.

In the JavaScript SDK, you can call the authenticate() method on the StitchClient with the "facebook" argument to trigger this authentication flow.

import { StitchClientFactory } from 'mongodb-stitch';
const stitchClientPromise = StitchClientFactory.create('<your-app-id>');

stitchClientPromise.then(stitchClient => {
   stitchClient.authenticate("facebook");
});

No redirect URL is specified here, so by default, the end user will be redirected back to the current root URL after they complete the Facebook login. The current root URL is the current URL, minus any fragment identifiers.

For example, if the current page is http://myexample.com/dashboard/#login, the default redirect URI will be http://myexample.com/dashboard/.

If you would like to specify a specific URL to redirect to, you can call the authenticate method on the StitchClient with an additional options argument that specifies the redirectUrl.

stitchClientPromise.then(stitchClient => {
   stitchClient.authenticate("facebook", { redirectUrl: "<your-redirect-url>" });
});

If the redirect URL (default or otherwise) is not in the list of valid redirect URIs specified when you set up the Facebook authentication provider, the login flow will not successfully complete.

In mobile applications, this redirect step is not necessary. The Facebook Login is handled by the Facbeook SDK for your specific platform, and you provide it with callbacks (via delegates in iOS and intents in Android) that will call the authentication methods in your platform-specific MongoDB Stitch SDK.

Wherever the Facebook SDK handles a successful login for your app, you must call the StitchClient’s login method with the Facebook authentication provider. The provider object will need to be initialized with an access token you can retrieve from the Facebook SDK. Additionally, you should log out your user from MongoDB Stitch when they log out of Facebook.

Tip

In Android, you can get the access token by calling getAccessToken().getToken() on the LoginResult object returned on a successful login.

In iOS, you can get the access token from the authenticationToken property on the token property in the LoginResult enum returned on a successful login.

Tip

If you are having trouble getting the SDK to authenticate with MongoDB Stitch using the Facebook authentication provider, ensure that when logging in with the Facebook Login SDK, you are requesting permission to access all the metadata that you’ve configured Stitch to request in the admin console.

See this page in the Facebook Login Android documentation, or this page in the Facebook Login Swift documentation for details on how to do this. A list of available permissions available can be found here.

For detailed examples of how to incorporate Facebook authentication in a client application, each of the ToDo sample apps contain code for authenticating with Facebook.