Loading ...

Facebook SSO | Axero Documentation

Home » axero documentation » Wiki » Documentation » Login » Single Sign-On (SSO) » Facebook SSO
Axero Documentation  Wiki
Public Space
Activity Stream Content
Version 27

Facebook SSO

0 
 /5
0 (0votes)

Axero supports Facebook integration for single sign-on (SSO) out of the box. This page covers how to configure a Facebook app, how to turn on Facebook Login in Axero, and what the Facebook login looks like.

Most of the work happens on Facebook's side. How long it takes depends on how quickly Facebook completes business verification and app review for your app, which is outside Axero's control. Once Facebook approves your app and you enter its credentials in Axero, Facebook Login will be active on your intranet. For help from the Axero team, submit a private case.

Features

  • Join the intranet using a Facebook account
  • Sign in to your intranet with a Facebook account
  • Link Facebook and existing Axero accounts

Before you start

  • Your intranet must be served over a secure (https) address. Facebook does not allow login from an insecure page.
  • You need a privacy policy page that Facebook can reach, and its address. Facebook requires one before it will approve your app.
  • Facebook Login is not available in the Axero mobile apps. The mobile apps sign people in with a username or email address and an Axero password, or through SAML single sign-on. Plan for that if most of your people work from a phone.

Configure Facebook App

Facebook changes this part of its site from time to time, so a button may sit somewhere slightly different from what is described here. The settings themselves are stable.

  1. Go to the Facebook apps page and start creating an app for your intranet.
  2. Enter a name for the app and a contact email address.
  3. When you are asked to choose what the app is for, select Authenticate and request data from users with Facebook Login.
  4. Choose whether to connect a business portfolio. You can connect one later if you are not ready.
  5. Finish creating the app to reach its dashboard.
  6. Open Settings > Basic.
  7. Fill in Privacy Policy URL and choose a Category.
  8. In App Domains, enter the domain of your intranet (for example, myintranet.com). This restricts which sites can sign people in using your app.
  9. Add the Website platform and enter the address of your intranet (for example, https://myintranet.com).
  10. Save your changes, then copy the App ID and the App Secret from this page. You will paste both into Axero.
  11. Open the Facebook Login settings for the app.
  12. Set Login with JavaScript SDK to Yes. Axero signs people in through Facebook's JavaScript tools, so login will not work without this.
  13. In Allowed Domains for JavaScript SDK, add the domain of your intranet.
  14. Save your changes.

Request access to email addresses

Axero matches a person's Facebook account to their Axero account by email address, so your Facebook app needs permission to read it. Facebook treats the two pieces of information Axero asks for differently.

  • Public profile is granted to every app automatically. There is nothing to request.
  • Email address starts out restricted. Until you request wider access, only people who have a role on the Facebook app itself can share their email address with your intranet.

This is the step most often missed, and skipping it looks like a working setup. Facebook login works for the administrator who built the app, but for nobody else at your organization.

  1. Open the Use cases page for your app and click Add next to the email permission. The public_profile permission is required for every use case and is already included.
  2. Go to App Review > Permissions and Features and request advanced access for email.
  3. Complete business verification if Facebook prompts you for it.
  4. Answer Facebook's data handling questions.
  5. Provide the usage description and screen recording Facebook asks for, then submit for review.
  6. Once the review is approved, switch the app out of development mode using the app mode control at the top of the dashboard.

Those two permissions are the only ones Axero requests. It does not ask for friend lists, posts, or anything else a person shares on Facebook, and it cannot post on their behalf. People see exactly this on the Facebook confirmation screen when they sign in.

You can return to your app's settings at any time at https://developers.facebook.com/apps.

Enable Facebook Login in Axero

  1. In Axero, click the gear icon > Control Panel > System > General Settings.
  2. Expand the Social Integration Settings section.
  3. Check Enable 3rd party login. This is the master switch for all social logins, so leave it on if you already use another provider.
  4. Enter the App ID in the Facebook API key field.
  5. Enter the App Secret in the Facebook Secret field.
  6. Check Integrate with the Facebook platform. This checkbox stays grayed out until both the API key and Secret fields have a value in them.
  7. Click Save System Settings.

What Axero copies from Facebook

When someone joins using their Facebook account, Axero fills in their name and email address and uses their Facebook profile photo as their Axero profile picture. Everything else on their profile starts empty, which is why they are asked to complete any required fields on the way in. When they return, they can sign in with Facebook again.

People can uncheck the email address on the Facebook confirmation screen before they continue. When Facebook supplies no email address, Axero falls back to a placeholder in the form username_no_email@temp.com. An account with a placeholder address cannot be matched to an existing member. It also will not receive email from your intranet until someone corrects the address, so check new members for those addresses.

Note: an existing member is linked to their Facebook account only if the email address on their Axero account is the same as the email address on their Facebook account. If the two differ and they sign in with Facebook, Axero adds them as a new member instead of linking. Once the two accounts have been linked the first time, the link holds even if the member's email address changes later.

Login via Facebook

  1. On the login page, click the Facebook icon under Social logins.

    The Axero login page, with the Facebook icon highlighted in the Social logins section below the sign-in form

  2. Enter your Facebook login information if you are not already signed in, then confirm that your intranet may receive your public profile and email address.

    The Facebook confirmation screen showing that the intranet will receive the person's public profile and email address, with the Continue button highlighted

  3. Set your username, then click Update. Axero suggests one based on your Facebook first name.

    The Choose your username screen with a suggested username filled in and the Update button highlighted

  4. Fill in any profile fields your intranet marks as required, then click Save.

    The Edit Profile page after signing in with an external account, with the missing required fields highlighted

If your intranet requires an administrator to approve new members, the account is created but stays inactive until someone approves it.

Troubleshooting

Only the people who built the Facebook app can sign in successfully.

Until Facebook approves advanced access for the email permission, it will not release email addresses to anyone who does not have a role on your Facebook app. Everyone else either cannot get past the Facebook screen or arrives as a brand-new account that is not matched to their existing intranet account. Complete Request access to email addresses above.

Exception: "UserCreateStatus status: InvalidUserName" when someone new tries to sign in.

Axero builds the new username from the person's Facebook first name, and that name has to fit your intranet's username rules. Two things can break it.

If the name is too short or too long:

  1. Go to Control Panel > System > General Settings > Advanced Settings.
  2. Set Minimum length for username to a lower value.
  3. Set Maximum length for username to a higher value.
  4. Click Save System Settings.

If the name contains accented or non-Latin characters, no length setting will help. Usernames accept only unaccented letters, numbers, and four punctuation characters: hyphen, underscore, period, and comma. That is the default rule, and an administrator can replace it with a different pattern. Instead, have Axero generate a neutral username:

  1. Go to Control Panel > System > System Properties.
  2. Search for UseGenericSSOUsernames and edit it.
  3. Set the value to true and click Save.

New members then receive a generated username such as user004821, which they can change on the Choose your username screen. Make sure your minimum and maximum username lengths allow 10 characters.

Exception: "UserCreateStatus status: InvalidPassword" when someone new tries to sign in.

People signing in with Facebook never type an Axero password, so Axero generates one for them. It is 13 characters long, and it has to fit your intranet's password rules.

  1. Go to Control Panel > System > General Settings > Advanced Settings.
  2. Set Minimum length for password to 13 or lower.
  3. Set Maximum length for password to 13 or higher.
  4. Click Save System Settings.

These two settings apply to everyone on your intranet, not only to people signing in with Facebook, so weigh the change against your own password policy before you make it.

Exception: "UserCreateStatus status: EmailDomainNotAllowed" when someone new tries to sign in.

Your intranet restricts which email domains may register, and the address on the person's Facebook account is not on the list.

  1. Go to Control Panel > System > General Settings > Site Settings.
  2. Add the domain to Allowed email domains for user registration, or clear the field to allow any domain.
  3. Click Save System Settings.

Alternatively, have the person change the email address on their Facebook account to one that is already allowed.

Wiki Index

Pages