Before proceeding, please have a look at the Facebook API changes which apply to every app created after March, 2018.
Table of contents
- How to enable the provider
- Sync data
- Facebook User Experience Design compatibility
- Frequently Asked Questions
- Common error messages
How to enable Facebook login in WordPress
1. Create a Facebook App
To be able to log in via Facebook you must create a Facebook app first.
- Navigate to https://developers.facebook.com/apps/
- Log in with your Facebook credentials if you are not logged in
- Click on the “Add a New App” button
- If you see the message “Become a Facebook Developer”, then you need to click on the green “Register Now” button, fill the form then finally verify your account.
- Fill “Display Name” and “Contact Email”. The specified “Display Name” will appear on your Consent Screen!
- Click the “Create App ID” button and complete the Security Check.
- At the “Add a Product” panel find “Facebook Login” and click “Set Up”
- Select “Web” and enter the url of your site to the “Site URL” field.
- Press “Save”
- Click on the “Settings” option what you find on the left side, under “Products – Facebook Login”
- Add the following URL to the “Valid OAuth redirect URIs” field: https://yoursite.com/wp-login.php?loginSocial=facebook where the yoursite.com is your domain. Please note that since March, 2018 you can only use https domains to log in with Facebook. Learn more
- Click on “Save Changes”
- On the top left side, click on the “Settings” menu point, then click “Basic”
- Enter your domain name to the “App Domains” field.
- Select a “Category”, an “App Icon” and pick the “Business Use” option that describes your the App best, then press “Save Changes”
- Your application is currently private, which means that only you can log in with it. In the top bar click on the switch next to the “In development” label, then click the “Switch Mode” button.
- At the top of the page you can find your “App ID” and you can see your “App secret” if you click on the “Show” button. These will be needed in plugin’s settings.
2. App setup
Once your Facebook app is ready you’ll need to copy and paste the App ID and App secret to the Facebook provider’s Settings tab. You can find the information at your Facebook app’s Settings which you can reach from the left sidebar.
Once your App ID and App secret has been added you need to verify the setup first. This verification helps you identify possible problems with the app.
The App ID of your Facebook app. You can find it at your App → left menu: Settings.
The App Secret of your Facebook app. You can find it at your App → left menu: Settings.
Username prefix on Register
Whenever a new user registers with their Facebook account they can get a custom prefix so you can easily identify them.
Fallback username prefix on register
Whenever a new user registers with their Facebook account and we can not generate a valid username from the first name or last name, a random username will be generated. With this option they can get a custom prefix so you can easily identify them.
Terms and conditions
This option can only be seen, if Terms and conditions is set to Show in Global Settings → Privacy tab. Here you can set custom Terms and Conditions for users who register with Facebook. For more information please read our GDPR documentation.
By default Nextend Social Login stores the first name, last name, email, avatar url and access token if it is possible, however some additional information can also be retrieved and stored.
When an option is checked, that field will be stored in a meta key with the specified name. The fields are stored in the wp_user_meta table.
NOTE: To use these fields, your app needs an App Review by Facebook, as of Facebook updated their App Review process and API permissions model. More information can be found on the Facebook App Review page.
It determines when the synchronization shall happen.
- Register: whenever a new user registers with a provider, their data will be retrieved and stored.
- Login: whenever user logs in with a provider, their data will be retrieved and stored.
- Link: whenever user links and existing WordPress account with a provider, their data will be retrieved and stored.
Stores the age range of the user, according to Facebook Age Demographic.
Stores the user’s birthday.
Stores a link to the users’s Timeline.
Stores the users’s hometown.
Stores the users’s current location which entered by them on their profile.
Stores the gender of the user.
Facebook User Experience Design compatibility
According to the User Experience Design, the button need to comply with some requirements. At the buttons tab of the Facebook provider there are predefined skins, which comply with those requirements.
Frequently Asked Questions
Why can’t I get the user’s email address when they register via Facebook?
There are certain cases when Facebook does not return the user’s email address:
- The user didn’t give permission for the App to access their email
- No Email address on account
- No confirmed email address on account
- No verified email address on account
- User entered a security checkpoint which required them to reconfirm their email address and they have not yet done so
- Users’s email address is unreachable
The problem is described in an official Facebook post. We also set up a test page where you can test whether the user is supposed to get email address. This code is from the official Facebook graph without any changes.
If you feel the email address should be fetched upon registration but it’s not, you should open an official bug report at Facebook.
Common error messages returned by Facebook during verification
Can’t load URL
Can’t load URL: The domain of this URL isn’t included in the app’s domains. To be able to load this URL, add all domains and sub-domains of your app to the App Domains field in your app settings.
The problem is that the App domains field does not contain your site’s current domain. Check the 14th steps of the App setup to fix the problem.
In some rare cases the problem can happen because of poorly written 3rd party social plugins, so you could also try disabling your other plugins and see if the verification process works. Then when you find the plugin that causes the problem, you should contact its developers to get their plugin fixed.
URL blocked: This redirect failed because the redirect URI is not white-listed in the app’s client OAuth settings. Make sure that the client and web OAuth logins are on and add all your app domains as valid OAuth redirect URIs.
The problem is that the entered Valid OAuth redirect URIs field is not correct for your app. Check the 11th step of the App setup to fix the problem.
Error validating verification code
Error validating verification code. Please make sure your redirect_uri is identical to the one you used in the OAuth dialog request
The problem is that the entered Valid OAuth redirect URIs field is not correct for your app. Check the 15th step of the App setup to fix the problem.
Invalid App ID
Invalid App ID: The provided app ID does not look like a valid app ID.
Client secret error
Error: Error validating client secret
The App secret you copied from the Facebook app is invalid. Make sure the correct one was copied.
Unable to validate CSRF state
Error: Unable to validate CSRF state
The problem is related to the server’s cookie related caches. Some servers only accept special cookie name as the caching server allows only these special cookie names. You should get in touch with your host and ask them about their cookie related caches.
If you’re using Pantheon server, update your Nextend Social Login version to 3.0.6 or greater where the error should be fixed.
Appsecret proof error
Error: API calls from the server require an appsecret_proof argument
The problem is that the appsecret_proof argument got turned on at your API. You should turn it off.
Nextend Social Login currently does not use appsecret_proof as it does not need it, but it will support this setting from version 3.0.10.
App not set up
App not set up: This app is still in development mode, and you don’t have access to it. Switch to a registered test user or ask an app admin for permissions.
The problem is that the Facebook app wasn’t switched to live. Check the 17th step of the app configuration to learn how to switch your app to live.