• These steps are easiest to perform logged into Azure 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 Azure, 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 Azure AD, please open a support request on our Helpdesk first.

Azure AD app registration

1. Sign in to the Azure Portal.
2. Select Azure Active Directory and then App Registrations in the left menu.
3. Create a new registration:
   1. Click New Registration at the top of screen.
   2. Enter a name for the application.
   3. Select single tenant option.
   4. Redirect URI:
      1. Select Web.
      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
   5. 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. Enable the permission checkbox and click Add Permissions.
      
      
5. Grant admin consent to registered app
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.
        • Azure 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.
        
        
   2. Client ID:
      • Locate your app in the App Registrations view.
      • Note the Application (client) ID.
        
        
7. Create a security group in Azure 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 Admin panel: Users & security section > Employee Directory Connector > Add new external user store. Type a name for your external user store (ex: Azure AD). Choose the type Azure Active Directory.
   
   
   
   
2. If you want the ThoughtFarmer user that you are currently logged in as to be an Azure 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 Azure username, choose your Azure AD in the dropdown menu and click Save.
3. Repeat Step 2 for any other existing users in ThoughtFarmer that will come from Azure. If an 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, open a Support request on our Helpdesk. 
   
   
   
   
4. After you change the account type, make sure you finish the authentication sections below, otherwise you won't be able to log back into the site after you're logged out. (If you need to log out of ThoughtFarmer and log back in before finishing up the authentication steps, you could create a temporary regular user and then delete the regular user when you don't need it anymore.)
5. Go to the Admin Panel: Users & security section > Employee Directory Connector page. Click on your Azure AD, and go to the Configuration tab. Enter the code below, updating the values with the information for your setup.
   • 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

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

   • Click Save when done.
6. Field mappings: Go to the Field Mappings tab. Add the field that you want to pull into user profiles. 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 Azure administrator to verify the name of those fields.
   
   
   
   • The following is a list of the accepted field mappings from Azure:
     
     

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

     
     
     
   • Unsupported field attributes can be added via extensionAttributes. If using extension attributes, use the configuration below.
     The appId can be found under App Registration > Tenant Schema Extension App.
     

     {
       "domainGroup": "{domain_group}",
       "tenant": "{tenant_id}",
       "clientId": "{client_id}",
       "clientSecret" : "[clientSecret]",
       "schemaExtensionConfig": [
         {
           "appId": "{app_id}",
           "attributeNames": [
             "extensionAttribute1",
             "extensionAttribute2",
             "extensionAttribute3",
             "extensionAttribute4"
           ]
         }
       ]
     }

     • Replace the {extension_attribute_name_x} with the actual name of the extension property as it appears in the on-premise Active Directory. I.e: extensionAttribute2, countryCode.
       
       
7. Test: Go to the Synchronization Settings tab and click Validate credentials. If everything is set up correctly you should see a green success message.
8. Syncing user information: Under the Synchronization Settings tab, run an on-demand sync by checking all the boxes and clicking 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. Navigate back and forth between the Synchronization Logs tab and any other 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 was pulled in for that user.
   
   

Set up Azure authentication

Create an Azure AD Application

1. Log into Microsoft Azure using https://azure.microsoft.com/.
2. Go to your Azure Active Directory, click on Enterprise Application.
   1. Select New Application.
      
      
      
      
   2. Select Create your own application.
      
      
      
      
   3. Select the "Non-gallery" option 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 earlier (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:
   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 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 the Admin Panel: Advanced section > Configuration settings page. 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. 
   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 Azure Single sign-on page in the Enterprise Application you created previously. 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 Azure. 
   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 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.
      
      

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. Otherwise, you will be prompted for a password.
2. After your Azure AD users are synced and they're able to log in, you can deactivate any non-Azure AD 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.