Facebook

Overview

The Akeeba Social Login - Facebook integration plugin allows user on your site to use their Facebook account to login or register a user account on your site.

Setup on Facebook

DISCLAIMER: This part of our documentation describing the interaction with a third party service is for information purposes only. It should be treated as indicative and used at your own risk. Akeeba Ltd can only attest that this part of the documentation has been the faithful transcription of the steps we took at the time of its writing. We strongly recommend that you consult the documentation of the third party service for accurate instructions. Should the behavior of the third party service differ from what is published in our documentation you should consult the support of the third party service provider. Do not seek support from us for such matters; Akeeba Ltd cannot provide support for third party services, is not responsible for or notified about any changes in said services, nor is it obligated to update the documentation pursuant such changes.

Before you can use Facebook Login on your site you must create a Facebook App. Even though it sounds scary, a Facebook App is simply a way for you to get a set of access codes which let you identify your site on Facebook.

Start by visiting Facebook For Developers site and click My Apps, Add a New App next to the search at the top.

A popup opens. In the popup enter the following information:

• Display name: When the visitors to your site click on Login with Facebook they will be told that an app by that name requires permission to see their full name and email address. It's a good idea to put the name of your site here.
• Contact email: This is the email Facebook will use to contact you whenever there is an important reason. This is NOT visible to the visitors of your site. Enter the email address of the person who will be managing this site.

If you see the "Select a Scenario" page check the box next to "Integrate Facebook Login". The scroll to the bottom and click the blue Confirm button.

Click on the Settings, Basic link on the left hand sidebar.

In the App Domains page enter all of the domain names which are going to be used by your site. Please note that adding / removing the www. in front of the domain name counts as a different domain. So if your site is accessible as both http://example.com and http://www.example.com you must enter both domain names here, i.e. example.com and www.example.com. These domains must match the domain names of the Valid OAuth redirect URIs option you set up in the previous step.

After you're done click on the Save Changes button at the bottom of the page.

On the left sidebar there's a Products header with a plus sign in a circle next to it. Click on the plus sign to add a product to your app. Find the Facebook Login item and click on Set up.

Find the Valid OAuth redirect URIs option. You will need to enter a URL in the form http://www.example.com/index.php?option=com_ajax&group=sociallogin&plugin=facebook&format=raw replacing http://www.example.com with the real URL of your site.

Click on the Save Changes button to save the setup.

Click on the Settings, Advanced link in the sidebar again.

Scroll to the Security section, and make sure the Require App Secret toggle is disabled.

Now click on the Settings, Basic link in the sidebar again.

Note down the App ID. This is the Facebook Application ID you need to enter to the plugin on your site.

We need one more piece of information. Inside the App Secret area click on the Show button. Note that Facebook may ask you to enter your password. You will see your App Secret. Note it down. This is the Facebook Application Secret you need to enter to the plugin on your site.

Tip: You can always view the App ID and App Secret at any time by going to Faceboook for Developers and selecting your site's Facebook App.

As an optional step, we recommend adding an App Icon to your Facebook App, typically the logo of your site. This will be shown to your site's visitors and it's useful to let them understand that the login request does come from your site. It must be 1024 x 1024 pixels square. Click inside the App Icon image to select a new file. Finally click on Save Changes to save the new logo.

Making your application public

If you followed the instructions above you have a private application in "development" mode for testing by you and you only. Nobody else can use it to log in or create an account on your site. Before you can use it on your live site you need to make your application public.

Start by visiting Facebook For Developers site and click on the title of your app.

From the sidebar click on App Review.

Click the slider under "Make Your App Name public?" to the Yes position.

Once the app is public other people can use it to log into your site.

Useful information about the Valid OAuth redirect URIs

Facebook is looking for an exact match of the redirect URL being sent to it by your site. Here are some gotchas regarding this requirement and how to deal with them:

• If you have a site which is accessible through BOTH an http:// and an https:// URL you will need to enter both URL variations, with and without HTTPS. For example http://www.example.com/index.php?option=com_ajax&group=sociallogin&plugin=facebook&format=raw for the plain HTTP version of your site and https://www.example.com/index.php?option=com_ajax&group=sociallogin&plugin=facebook&format=raw
• If your site is accessible through multiple domain / subdomain names you will need to enter the URLs for each and every domain / subdomain. For example, if your site is available through example.com (without www in front!), www.example.com (with www in front) and www.example.net (different domain name, note it's .net instead of .com!) you will need to enter THREE URLs there, http://example.com/index.php?option=com_ajax&group=sociallogin&plugin=facebook&format=raw, http://www.example.com/index.php?option=com_ajax&group=sociallogin&plugin=facebook&format=raw and http://www.example.net/index.php?option=com_ajax&group=sociallogin&plugin=facebook&format=raw. Of course if you have HTTP and HTTPS on each domain you will need to also add the HTTPS versions of these three URLs for a total of six (6) URLs.
• If your site is installed in a subdirectory you must use the full path to your site. For example, if your site is installed in http://www.example.com/joomla the URL you need to enter here is http://www.example.com/joomla/index.php?option=com_ajax&group=sociallogin&plugin=facebook&format=raw
• You CAN set up localhost URLs here to test this feature on your local development site. For example, if your site is installed in http://localhost/joomla_test you need to enter here is http://localhost/joomla_test/index.php?option=com_ajax&group=sociallogin&plugin=facebook&format=raw
• Your site MUST NOT convert these callback URLs to SEF URLs. The plugin itself is designed to never do that but some overzealous SEF / SEO plugins may end up doing that. If you get a message from Facebook about the callback URL not being allowed try disabling all SEO / SEF plugins on your site. If that helped please ask its developer to add an exception for com_ajax URLs (URLs to com_ajax must NEVER be translated to SEF format).

App reviews and permissions

Akeeba SocialLogin requires both email and public_profile permissions to work; these are the default permissions granted to a Facebook application. Whenever there is an app review you will be asked to verify each permission separately. Make sure you verify both permissions.

If you are asked why these permissions are needed, here's why:

• email Joomla! requires an email address to be provided for all of its user accounts, and that it is unique (not used by any other Joomla! user account on the site). SocialLogin needs to read the email address during login with Facebook time to enable the "Allow social login to non-linked accounts" and "Create new user accounts" settings. The email address will be collected even when these features are disabled, as doing otherwise would invalidate the Facebook login of existing users whenever you changed those settings.
• public_profile is used to get the name of the user and their verification status, also used to enable the "Allow social login to non-linked accounts" and "Create new user accounts" settings. It's also what allows us to get a unique pseudonymous identifier which makes logging in with Facebook possible.

Plugin options

Facebook Application ID Enter the App ID for your custom Facebook application here. See the previous section for creating a Facebook App.

Facebook Application Secret Enter the App Secret for your custom Facebook application here. See the previous section for creating a Facebook App.

Allow social login to non-linked accounts When enabled allows users to log in despite not having linked their Facebook account to their site user account. Their Facebook account's email address must be the same as the email account they use on your site and they must have already verified it with Facebook.

Create new user accounts Creates a new Joomla! user when a user tries to log in via Facebook but there is no Joomla! user account associated with that email or Facebook User ID. If user registration is disabled no account will be created and an error will be raised. The new Joomla! user will have a username derived from the Facebook login, the same email address as the Facebook account and a long, random password (which the user can change once they have logged in). Set this to No to prevent creation of user accounts through Facebook login.

Ignore Joomla! setting for creating user accounts When both this option and the Create new user accounts option above are enabled a new user will always be created, even if you have disabled user registration in the options of Joomla's Users page. This is useful to prevent anyone from registering to your site unless they have a Facebook account.

Bypass user validation for verified Facebook users Only applies when creating new user accounts. If a Facebook user has verified their email address with the social network, this option is enabled and they try to use the Login with Facebook button without having a Joomla! user account with the same email address a new Joomla user account will be created AND it will NOT go through Joomla's account verification (over email or manual authorization by an admin). This means that no account activation email will be sent to the user or the administrators of the Joomla! site. The account will be immediately activated and logged in.

Button styling When enabled custom CSS for login, link and unlink button styling will be output to the page header. Disable this option if you intend to use your own CSS to style the buttons.

Icon class The icon CSS class to use in the login, link and unlink buttons. Useful to use an icon font such as FontAwesome or Glyphicons to render the logo. If it's left empty, a PNG image with the Facebook logo will be used instead.

Login buttons can be shown in In which part(s) of your site do you want to allow showing the Social Login buttons? For more information on how this feature works please consult the “Hiding in the frontend or backend” documentation page.