Documentation

Azure AD

Pre-requisites

  • Premium P1 subscription for all users who want to authenticate using Azure. This is required because ThoughtFarmer is a non-gallery application. The free model allows unlimited SSO applications but this applies only to Gallery Applications. 
    https://azure.microsoft.com/en-ca/pricing/details/active-directory/ .
  • If you plan to have a custom URL for your intranet, ensure this is in place before completing this setup.
  • To use multi-factor authentication you need to enable this on Azure before proceeding with the below setup.
  • If you already have active users in ThoughtFarmer and you're looking to switch them over to Azure AD, please contact ThoughtFarmer first. 

Azure AD app registration

  1. Sign in to Azure Portal
  2. Select Azure Active Directory and then App Registrations in the left menu
  3. Create a new registration by clicking New Registration at the top of screen
    1. Enter a name for the application
    2. Select single tenant option
    3. Redirect URI
      1. Select Web
      2. Enter your ThoughtFarmer URL
        1. If you have a custom url, please use that e.g. https://intranet.mycompany.com
        2. Otherwise use the base ThoughtFarmer URL e.g. https://intranet.thoughtfarmer.com
    4. Click Register


       
  4. Configure the app permissions by selecting API Permissions from the left menu
    1. Click Add a permission and select Microsoft Graph from the right menu
    2. Click Application Permissions then enter Directory.Read.All into the search box
    3. Enable the permission checkbox and click Add Permissions


       
  5. Grant admin consent to registered app 
    1. Update the following URL and send to the tenant admin
      1. https://login.microsoftonline.com/consumer_tenant_id/adminconsent?client_id=application_id

        1. Consumer Tenant ID: Azure AD > Properties > Directory ID
        2. Application ID
          1. Locate your app in the App Registrations view
          2. Note the Application (client) ID


             
      2. The tenant admin needs to visit the updated URL while logged in to the Azure account
         
  6. Gather values for ThoughtFarmer setup
    1. Client Secret
      1. Click Certificates & Secret in left menu
      2. Enter a name > Set Expires to "Never" > Click Add
      3. Note the value


         
    2. Client ID
      1. Locate your app in the App Registrations view
      2. Note the Application (client) ID


         
  7. Create a security group in Azure and add all users who you want to provide access to Thoughtfarmer (ex: "Thoughtfarmer_Users")

Set up user sync on ThoughtFarmer

  1. Create a new external store: In Thoughtfarmer, go to Admin panel > Employee Directory Connector Add new external store. Type a name for your external user store (ex: Azure AD). Choose the type "Azure Active Directory".


     
  2. For the ThoughtFarmer user you're currently logged in as, if you want that user to be an Azure user, you'll need to convert the account type to "External". Go to Admin Panel > User Management. Search for the user. On the right, click the gear icon > Edit Account. Change the type to "External", add the Azure username, choose your Azure AD in the drop down and save. Do the same for any other existing users in ThoughtFarmer that will come from Azure. If the Azure user doesn't have a ThoughtFarmer account yet, you can let the sync create the user. If you need help bulk changing many users at a time, contact ThoughtFarmer. 


     
  3. After you change the account type, you'll need to make sure you finish the authentication sections below, else, you won't be able to log back into the site after you're logged out. You could create a temporary regular user if you need to log out of ThoughtFarmer and log back in before finishing up the authentication steps. Then delete the regular user when you don't need it anymore.
  4. Go back to Admin Panel > Employee Directory Connector > [your Azure AD ] > Configuration tab. Enter the code below and update the values. Click Save when done

    {
      "domainGroup": "Azure_Security_Group",
      "tenant": "Tenant_ID",
      "clientId": "Client_ID",
      "clientSecret": "Client_Secret"
    }

    Azure_Security_Group: The Azure security group containing the users that will have access to ThoughtFarmer
    Tenant_ID: Azure AD > Properties > Directory ID
    Client_ID: Noted earlier
    Client_Secret: Noted earlier

  5. Field mappings: In ThoughtFarmer, go to Admin Panel > Employee Directory Connector > [name of your Azure AD] > Field Mappings tab. Add the field that you want to pull into user profiles. By default, only user names & email are synced. For the correct "External store field" values, refer to this document. Values are case-sensitive. If you are using non-standard fields, please reach out to your Azure administrator to verify the name of those fields.

  6. Test: Go to the "Synchronization Settings" tab and hit validate credentials. If everything is setup correctly you should see a green success message.
  7. Syncing user information: Under the "Synchronization Settings" tab, run an on-demand sync by checking all the boxes and hit "Synchronize now". You should also create a daily sync schedule so an automatic sync is run on a regular basis. You can look at the "Synchronization Logs" tab to check the status of this sync. Flip back and forth between "Synchronization Logs" and another tab for the sync status to change.

     

    After a sync has successfully completed, you can click "view details" to see the Azure users. Clicking on a specific user row will show you what info got pulled in for that user.

Set up Azure authentication

Create an Azure AD Application

  1. Log into Microsoft Azure using https://portal.azure.com.
  2. Go to your Azure Active Directory, click on Enterprise Application. Add a new application. Select "Non-gallery application" and give it a name.

  3. On the side navigation of your new app page, click "Users and groups". Click "Add user" and add the security group you created at the beginning of this doc (step 2 under the "Set up user information sync from Azure" section). This provides the group with permission to access this application.

       
     
  4. Configuring Single sign-on parameters:
    Click "Single sign-on" on the side navigation and select "SAML"

    1. Identifier: default value is "thoughtfarmer". If this value is taken up by something else in your Azure organization, you can use a different value. If you use a different value, you need to change the value configured in ThoughtFarmer too. The configured value in ThoughtFarmer is in Admin Panel > Configuration Settings. Search for the config "saml.service.provider.name". Make sure its value matches your Identifier in Azure. If not, change it in ThoughtFarmer and save. 
    2. Reply URL: "<YOUR_SITE_URL>/auth/saml/assertionconsumerservice". If you are a cloud client proceed with this step only after we have set up a custom url for your site.

Create an external custom SAML login provider in Thoughtfarmer

  1. Go to Admin panel Login provider > Add new under External providers > Choose Custom SAML and hit next.


     
  2. Go back to your Azure "Single sign-on" page for your ThoughtFarmer app, the same page in step 4 above. You'll need the SAML Signing Certificate and Set up values for the next step.


     
  3. On the ThoughtFarmer external login provider page that you just created, use some of the values from the previous step for these fields. Then save.
    1. Hostname: URL for your Thoughtfarmer site "yourSiteUrl.com". Make sure you select http or https.
    2. Login Hostname: Login URL from Azure. 
    3. External user store configuration: Pick the store you created above from the drop-down.
    4. Single Sign On Binding Type / Single Sign Out Binding Type: HTTP Redirect
    5. Identity Provider Sign Out URL: Logout URL from Azure.
    6. Certificate: Download the "Certificate (Base64)" file from Azure. Open the certificate using notepad. Copy the whole value including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----. Please ensure there are no line breaks in the middle of the private key.
      • *Certificate Expiry - You also need to open it as a .cer file. Keep track of the expiry date. Make sure to renew your certificate in Azure before it expires. If you change the Azure certificate, it should be updated in the Certificate field in the ThoughtFarmer login provider page.
    7. Configuration options: Check the box next to "Want Assertion Signed".
    8. Issuer URL / Name: Azure AD Identifier.

      Azure%20AD%20Login%20Provider.png

Test the connection

  1. Log out of ThoughtFarmer and try to log back in. You should get redirected to the Azure login portal. If you are already signed into Azure you should get signed in. Else, you will be prompted for a password.
  2. After your Azure AD users are synced in and they're able to log in, you can deactivate any non-Azure AD users that you don't need anymore. Go to Admin Panel > User Management. Check off the user, at the top drop down, select "Deactivate user" and hit Go.