Configuring Facebook Login as an OIDC Identity Provider for TechDoc 12

TechDoc's SAML authenticator has provided our users with a quick, easy, and unified Single Sign-On experience for years using the SAML (Security Assertion Markup Language) standard. As times have evolved, so has authentication. Over the last few years, the OpenID (OIDC) protocol has moved into the spotlight as the modern replacement for SAML. OIDC 1.0 is built upon OAuth 2.0 the current and mature version of the original OAuth 1.0 (Open Authorization) standard. TechDoc 12 now features a new OIDC authenticator that supports many of the current OIDC identity providers (IDPs) available including Facebook Login. Unlike most, Facebook Login only allows for shared secret-based authentication. In the steps below, we'll cover what's needed to configure both sides (TechDoc and Facebook Login).

Facebook Login Configuration

In order to provide Facebook Login on an external site or application like TechDoc, you must first create a Facebook App. Once the app has been created, the login and security can be set up, and then it will be ready for use by TechDoc.

Create a Facebook App

• Open a web browser and log into your account on Facebook developer account.
  
  https://developers.facebook.com/
  
  
  
  
• In the upper right-hand corner, click the My Apps link.
  
  
  
  
• In the upper right-hand corner, click the Create App link.
  
  
  
  
• On the Create an app screen, enter a name for the app that will be used for your TechDoc DM or SM instance. The app will also need a contact email; this defaults to the Facebook developer's email account but can be changed if needed. Click Next to continue.
  
  
  
  
• On the Uses cases screen, scroll down and check the box next to "Authenticate and request data from users with Facebook Login", and then click the Next button.
  
  
  
  
• On the Business screen, you can optionally select to connect the app to a business portfolio. For our example, we'll select "I don't want to connect a business portfolio yet.", and then click the Next button to continue.
  
  
  
  
• On the Publishing requirements screen, feel free to review the steps required to publish the app. This is just a test application so we won't be publishing this test app in our example, so click the Next button to continue.
  
  
  
  
• Finally, on the Overview screen, review all of the information you have selected, and then scroll to the bottom and click the Create app button to create the app.
  
  
  
  
• A popup screen will appear requesting your Facebook developer account password to complete the app creation. Enter your Facebook account password and then click the Submit button.
  
  
  
  
• The app has now been created and you will be presented with the dashboard for your app. Click the "Customize the Authenticator and request data..." link under the "App customizations and requirements" section.
  
  
  
  
• On the Customize use case screen, click the Add button to add the user's email address to the set of attributes to be returned; other attributes can be added if needed, but email will be the unique identifier that will be used to identify users within TechDoc.
  
  
  
  
• Next, click the Settings link in the left pane.
  
  
  
  
• On the Authenticator settings screen, scroll down the page. Into the Valid OAuth Redirect URIs field, enter the redirect URL for your TechDoc DM or SM. It should take the form of:
  
  https://YOUR_TECHDOC_INSTANCE_HERE/servlet/td.web.OIDCRedirector
  
  replacing YOUR_TECHDOC_INSTANCE_HERE with the fully qualified host name of your TechDoc DM or SM. After you have done all of this, click the Save Changes button.
  
  
  
  
• On the left side of the page, under App settings, click the Basic link.
  
  
  
  
• The basic settings screen contains the few pieces of information we'll need to configure the authenticator in TechDoc. Create a text file and first note down the App ID (shown in the orange box below). Next, click the Show button for the App secret (next to the blue box shown below). In order to view the shared secret for your Facebook app, you'll need to enter you Facebook account password again. Once you've done this, the App secret will be displayed. Double click the App secret, and then copy it and paste it into your text file. Save this text file for later.
  
  
  
  
• This completes the Facebook side of the configuration, but before we move on to the TechDoc configuration, we need to save a copy of the Facebook OIDC IDP metadata. Open a web browser and enter the following address into the address bar:
  
  https://www.facebook.com/.well-known/openid-configuration
  
  this should result in a screen that looks like this:
  
  
  
  
• Right click and select Save as... and save the metadata to a file in your TechDoc/etc folder; we named ours idp-metadata-facebook.json.

Setting up an OIDC Authenticator in TechDoc

• Open a web browser and navigate to your TechDoc DM or SM (we'll be using a DM for this example), log in as an Admin, and click on the Admin link on the top menu bar.
  
  
  
  
• On the Admin screen, click the Authenticator link under the Create... to start the creation of the TechDoc OIDC authenticator.
• On the Create Authenticator screen, enter a name for the authenticator and select OIDC from the drop down menu.
  
  
  
  
• For the service data, we'll need to specify the following:
  
  -mMETADATA_FILENAME_HERE -iAPP_ID_HERE -sAPP_SECRET_HERE -Thttps://graph.facebook.com/v11.0/oauth/access_token
  
  where
  • -m - specifies the name of the Facebook metadata file you saved into your TechDoc/etc folder. Replace METADATA_FILENAME_HERE with the name of the metadata file.
  • -i - specifies your client identifier; for Facebook this should be the App ID Identifier you noted in your text file. Replace APP_ID_HERE with your App ID Identifier.
  • -s - specifies the shared secret; for Facebook this should be the App secret you noted in your text file. Replace APP_SECRET_HERE with your App secret.
  • -Thttps://graph.facebook.com/v11.0/oauth/access_token - species the URL for the Token endpoint used to retrieve a user's token after authentication. Most OIDC IDP providers specify the URL of their token endpoint service in their metadata file however, Facebook is not fully OIDC/OAuth compliant and they openly state this. To obtain a token from them, we must specify the Token endpoint service manually.
• Once you've entered the service data for your authenticator, click the OK button to complete the creation.
  
  
  
  
• You may now click the Test link on the side menu, and then click the Test using... button to test your authenticator.
• You should see a list of user attributes returned that resembles the screenshot below. Make sure you see the entry named email. This claim is the default one that will be used to map the Facebook user account email address to a TechDoc account. If a different claim is to be used, make sure that claim appears in the list. You may need to add the -n switch to your authenticator to specify the name of the specific claim you wish to use to identify users.
  
  
  
  
• If everything looks good, your configuration is complete! You are free to begin creating users using this authenticator by selecting it from the list on the create/modify user screen and entering their Facebook user account's email address (their email or whatever other unique identifier you've chosen to use) in the field next to the authenticator.

One final note: If your plan is to migrate an existing SAML Authenticator to use OIDC, you can perform the following steps to transition the existing SAML authenticator over to using OIDC and all users assigned to that authenticator will now be using OIDC to access TechDoc.

1. Thoroughly try out the test OIDC authenticator that you set up above to make sure you're confident that it is working correctly.
2. Record the current SAML authenticator's settings somewhere; particularly the Service Data string.
3. Modify the current SAML authenticator, change its Service Name from SAML to OIDC, copy the Service Data string from the test OIDC authenticator that you set up to here, enter a reason, and click OK.
4. Now test your newly converted authenticator to make sure it's working properly as an OIDC authenticator.
5. If there are any problems, you can always modify the authenticator and change the Service Name back to SAML and change the Service Data string back to what you recorded in step 2.
6. Once happy with the SAML to OIDC migration, you can delete the test OIDC authenticator if you no longer want it around.