Microsoft Entra ID (formerly Azure AD)

• These steps are easiest to perform logged into Microsoft Entra ID as a Global Admin.
• If you plan to have a custom URL for your intranet, ensure this is in place before completing this setup.
• If you are going to use multi-factor authentication on Microsoft Entra ID, you need to enable it before proceeding with the setup below.
• If you already have active users in ThoughtFarmer and you want to switch them over to Microsoft Entra ID, please open a support request on our Helpdesk first.
• You have planned your field mappings and are aware of which fields are owned by which system. 

App registration

1. Sign in to the Microsoft Entra ID Portal.
2. Go to App Registrations.
3. Click New Registration at the top of screen
   
   1. Enter a Name for the application.
   2. Select the Single tenant option.
   3. Redirect URI:
      1. Select Single-page Application (SPA) from the dropdown.
      2. Enter your ThoughtFarmer URL.
         • If you have a custom URL, please use it. e.g. https://intranet.mycompany.com
         • Otherwise, use the base ThoughtFarmer URL e.g. https://intranet.thoughtfarmer.com
   4. Click Register.
      
      
4. Configure the app permissions:
   1. Select API Permissions from the left menu.
   2. Click Add a permission and select Microsoft Graph from the right menu.
   3. Click Application permissions then enter Directory.Read.All into the search box.
   4. To allow profile images to be synced, add the User.Read.All application permission.
   5. To allow write access for when ThoughtFarmer is the data owner add the User.ReadWrite.All application permission.
   6. Enable the permission checkbox and click Add Permissions.
      
      
5. Grant admin consent to registered app.
   • This step needs to be performed by an Admin. If you do not see the option to grant consent then you will need to contact a Microsoft Entra ID Admin to perform this step for you.
6. Gather values for ThoughtFarmer setup:
   1. Client Secret:
      • Click Certificates & Secret in left menu.
      • Enter a name > Set Expires to 24 Months > Click Add.
        • Microsoft Entra ID does not have the ability to send an alert when a secret expires but it could be retrieved via Microsoft Graph API, or a Powershell script. 
      • Note the value highlighted below. Please grab the value, not the GUID Secret ID, and save it in a Notepad file under "Secret Value"
        
        
   2. Client ID:
      • Locate your app in the App Registrations view.
      • Note the Application (client) ID and save it.
        
        
7. Create a security group and add all users that 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 the Admin panel: Users & security section > Employee Directory Connector > Add new external user store. Type a name for your external user store (ex: Entra ID User Sync). Choose the type Microsoft Entra ID in the dropdown.
   
   
   
   
2. Go to the Configuration tab. Enter the code below, updating the values with the information for your setup.
   • EntraID_Security_Group: The Entra ID security group containing the users that will have access to ThoughtFarmer

   • Tenant_ID: Entra ID > Properties > Directory ID

   • Client_ID: Noted earlier

   • Client_Secret: Noted earlier

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

   • Click Save when done.
3. Field mappings:
   1. Go to the Field Mappings tab.
   2. Click +Add and under the ThoughtFarmer field column, select a value from the dropdown. 
      1. Under the External store field column, add the field mapping that you want to pull into user profiles and select the Entra ID value for the Data Owner column.
         1. By default, only usernames & email are synced. For the correct "External store field" values, refer to this User resource type document. Values are case-sensitive. If you are using non-standard fields, please reach out to your Microsoft Entra ID administrator to verify the name of those fields.
            
            
   3. The following is a list of the accepted field mappings from Entra ID:
      
      

      givenName	sn	displayName	preferredName
      manager	jobTitle	streetAddress	city
      postalCode	country	image	businessPhones
      mobilePhone	department	officeLocation	mail
      state	homePhone	employeeType	extensionAttribute1 - extensionAttribute15

   4. If using custom extension attributes outside of Microsoft's fifteen extension attributes, use the configuration below.
      The appId can be found under App Registration by searching Tenant Schema Extension App.
      

      {
        "domainGroup": "{domain_group}",
        "tenant": "{tenant_id}",
        "clientId": "{client_id}",
        "clientSecret" : "[clientSecret]",
        "schemaExtensionConfig": [
          {
            "appId": "{app_id}",
            "attributeNames": [
              "{extension_appID_name_1}",
              "{extension_appID_name_2}",
              "{extension_appID_name_3}",
              "{extension_appID_name_4}"
            ]
          }
        ]
      }

      • Replace the {extension_appID_x} with the actual name of the extension property as it appears in the on-premise Active Directory. I.e: extensionAttribute2, countryCode.
        
        
4. Test: Go to the Synchronization Settings tab and click Validate credentials. If everything is set up correctly you should see a green success message. 
   • If Validate credentials fails, see the Admin Panel: Logs & statistics section > System logs page for any messages. If you are not sure what the problem is after viewing the system logs page, please open a support request on our Helpdesk.
5. Syncing user information: Under the Synchronization Settings tab, run an on-demand sync by checking all of the boxes and clicking Synchronize now. You can 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. 
   1. If you do not wish to create users at this time, follow these steps:
      1. Select the "Bulk update users" checkbox
      2. Click Synchronize now.

This sync will pull your users from the Security Group you provided in the configuration and will allow you to see your user sync list without adding users. 

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

Set up Single Sign on 

Create an Entra ID Enterprise Application 

1. Log into Microsoft Entra ID.
2. Go to Enterprise Application.
   1. Select New Application.
      
      
      
      
   2. Select Create your own application.
      
      
      
      
   3. Select the "Non-gallery" option and give it a name.
      
      
3. Go to the Properties on the left and check that the Assignment required setting is properly set for your desired setup. For ease of configuration it is recommended to set this to No.  For details please see Microsoft Entra ID single sign-on "assignment required" setting.
   
   
   
   
4. Configuring Single sign-on parameters:
   1. Click Single sign-on on the side navigation and select SAML.
      
      
      
      
   2. Identifier: The default value is "thoughtfarmer". If this value is taken up by something else in your Microsoft 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 the Admin panel: Advanced section > Configuration settings page. Search for the config setting saml.service.provider.name. Make sure its value matches your Identifier in Microsoft. If not, change it in ThoughtFarmer and Save.
   3. 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 the Admin panel: Users & security section > Login provider page. Click Add new under External providers, choose Custom SAML and click Next.
   
   
   
   
2. Go back to the Microsoft Entra ID Single sign-on page in the Enterprise Application you created previously. You will find the required values under the Single Sign on section in the left-hand menu. You will 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, add the values from the previous steps for the fields described below. Then Save.
   1. Hostname: URL for your Thoughtfarmer site "yourSiteUrl.com". Make sure you select http or https.
   2. Login Hostname: Login URL from Entra ID. 
   3. External user store configuration: Pick the store you created above from the dropdown menu.
   4. Single Sign On Binding Type / Single Sign Out Binding Type: HTTP Redirect.
   5. Identity Provider Sign Out URL: Logout URL from Entra ID.
   6. Certificate: Download the "Certificate (Base64)" file from Entra ID. 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 Entra ID before it expires. If you change the Entra ID 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:  Identifier.
      
      

Test the connection

1. Before you change your account type, create a temporary regular user with Admin privileges and then delete the regular user when you don't need it anymore. This account can serve as a backup access method in the event that Entra ID authentication encounters issues.
2. If you want the ThoughtFarmer user that you are currently logged in as to be an Entra ID user, you need to convert the account type to External. To do this:
   1. Go to the ThoughtFarmer Admin panel: Users & security section > User Management page.
   2. Search for the user.
   3. On the right of the user entry, click the gear icon and select Edit Account in the dropdown menu.
   4. Change the Account type to External, add the Entra ID username, choose the Entra ID store in the dropdown menu and click Save.
3. Repeat Step 2 for any other existing users in ThoughtFarmer that will come from Entra ID. If an Entra ID 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, open a Support request on our Helpdesk. 
   
   
   
   
4. Log out of ThoughtFarmer and try to log back in. You should get redirected to the Microsoft login portal. If you are already signed into Entra ID, you should get signed in. Otherwise, you will be prompted for a password.
5. After your Microsoft Entra ID users are synced and they're able to log in, you can deactivate any non-Microsoft Entra ID users that you don't need anymore. Go to the Admin Panel: Users & security section > User Management page. Select the checkbox beside the user, and in the top dropdown menu, select Deactivate user and click Go.