.. meta::
:robots: nosnippet
.. _facebook-authentication:
=======================
Facebook Authentication
=======================
.. default-domain:: mongodb
.. contents:: On this page
:local:
:backlinks: none
:depth: 2
:class: singlecol
Overview
--------
The Facebook authentication provider allows users to log in
with their existing Facebook account through a companion
Facebook application. When a user logs in, Facebook provides
Atlas App Services with an `OAuth 2.0 access token
`_ for
the user. App Services uses the token to identify the user and
access approved data from the Facebook API on their behalf.
For more information on Facebook Login, see `Facebook Login
for Apps
`_.
The following diagram shows the OAuth logic flow:
.. figure:: /images/auth-oauth-flow.png
:alt: OAuth flow diagram
:width: 350px
.. _auth-facebook-configuration:
.. _config-oauth2-facebook:
Configuration
-------------
.. tabs-realm-admin-interfaces::
.. tab::
:tabid: ui
You can enable and configure the Facebook authentication provider from the
App Services UI by selecting :guilabel:`Facebook` from the
:guilabel:`Authentication` page.
.. tab::
:tabid: cli
To enable and configure the Facebook authentication provider with
the {+cli-ref+}, define a :ref:`configuration
object ` for it in ``/auth/providers.json``.
Facebook provider configurations have the following form:
.. code-block:: none
:caption: /auth/providers.json
{
"oauth2-facebook": {
"name": "oauth2-facebook",
"type": "oauth2-facebook",
"disabled": ,
"config": {
"clientId":
},
"secret_config": {
"clientSecret":
},
"metadata_fields": [, ...],
"redirect_uris": [, ...],
"domain_restrictions": [, ...]
}
}
The Facebook authentication provider has the following configuration
options:
.. list-table::
:header-rows: 1
:widths: 15 30
* - Field
- Description
* - | :guilabel:`Client ID`
| *config.clientId*
- Required. The :guilabel:`App ID` of the Facebook app.
See :ref:`auth-facebook-app-setup` for information about setting
up your Facebook app and finding the :guilabel:`App ID`.
* - | :guilabel:`Client Secret`
| *secret_config.clientSecret*
- Required. The name of a :ref:`Secret ` that stores
the :guilabel:`App Secret` of the Facebook app.
See :ref:`auth-facebook-app-setup` for information about setting
up your Facebook app and finding the :guilabel:`App Secret`.
* - | :guilabel:`Metadata Fields`
| *metadata_fields*
- Optional. A list of fields describing the authenticated user that
your application will request from the :facebook:`Facebook Graph API
`.
All metadata fields are omitted by default and can be
required on a field-by-field basis. Users must
explicitly grant your app permission to access each
required field. If a metadata field is required and
exists for a particular user, it will be included in
their user object.
To require a metadata field from an import/export
configuration file, add an entry for the field to
the ``metadata_fields`` array. Each entry should
be a document of the following form:
.. code-block:: javascript
{ name: "", required: "" }
* - | :guilabel:`Redirect URIs`
| *redirect_uris*
- Required for web applications.
A list of allowed redirect :abbr:`URIs (Uniform Resource
Identifiers)`.
Once a user completes the authentication process on
Facebook, App Services redirects them back to either a
specified redirect URI or, if no redirect URI is
specified, the URL that they initiated the
authentication request from. App Services will only redirect
a user to a URI that exactly matches an entry in this
list, including the protocol and any trailing
slashes.
* - | :guilabel:`Domain Restrictions`
| *domain_restrictions*
- Optional. A list of approved :wikipedia:`domains `
for user accounts.
If specified, the provider checks the domain of a
user's primary email address on Facebook and only
allows them to authenticate if the domain matches an
entry in this list.
For example, if ``example1.com`` and ``example2.com``
are listed, a Facebook user with a primary email of
``joe.mango@example1.com`` would be allowed to log
in, while a user with a primary email of
``joe.mango@example3.com`` would not be allowed to
log in.
.. note::
If you've specified any domain restrictions, you
must also require the email address field in the
:guilabel:`Metadata Fields` setting.
.. _auth-facebook-app-setup:
Set Up a Facebook App
---------------------
The Facebook authentication provider requires a `Facebook
app `_ to manage
authentication and user permissions. The following steps
walk through creating the app, setting up Facebook Login,
and configuring the provider to connect with the app.
.. procedure::
.. step:: Create a Facebook App
Follow Facebook's `official guide
`_ to create a new
Facebook app.
.. step:: Enable Facebook Login
From the app's :guilabel:`Dashboard` view, find the :guilabel:`Facebook
Login` card and click :guilabel:`Set Up`. You should see a list of
quickstart guides for each platform. Follow the guide for your
platform to enable Facebook Login.
.. note::
App Services web applications do not require you to install the Facebook
SDK to use the Facebook authentication provider. If you are
incorporating Facebook Login into a web application you can skip
any steps in the quickstart related to setting up the Facebook SDK
for JavaScript.
.. step:: Add App Services as a Valid OAuth Redirect URI
When a user completes the login flow for your Facebook app they need
to be redirected back to App Services. Facebook Login will only allow users
to redirect to a pre-approved list of URIs.
From the :guilabel:`Facebook Login > Settings` page, add an App Services
authentication callback URL that corresponds to the :ref:`deployment
region ` of your application to
the list of :guilabel:`Valid OAuth Redirect URIs`.
The following table lists the callback URL for each region:
.. include:: /includes/deployment-region-auth-callback-urls.rst
.. step:: Configure the Facebook Authentication Provider
To connect your Facebook app to App Services, find your Facebook app's
:guilabel:`App ID` and :guilabel:`App Secret` values on the
:guilabel:`Settings > Basic` page and add them to your authentication
provider :ref:`configuration `.
.. _facebook-authentication-examples:
Examples
--------
For code examples that demonstrate how to register and log in using
Facebook authentication, see the documentation for the Realm SDKs:
- :ref:`C++ SDK `
- :ref:`Flutter SDK `
- :ref:`Java SDK `
- :ref:`Kotlin SDK `
- :ref:`.NET SDK `
- :ref:`Node SDK `
- :ref:`React Native SDK `
- :ref:`Swift SDK `
- :ref:`Web SDK `