https://learn.microsoft.com/en-gb/entra/fundamentals/new-name)
The "Microsoft Azure Active Directory Connector" v1 integration was built to sync users and authenticate depending on user's settings, through the by now deprecated "MS Azure AD GRAPH API Endpoint"; this was implemented since v6.3 (November 2016).
With the farmerswife v6.8 Release (June 2022), the "Microsoft Azure Active Directory Connector" v2 has been implemented, which adds support for the new "MS GRAPH API Endpoint" to replace the deprecated "MS Azure AD GRAPH API Endpoint".
Known wish-list:
- Add support for MFA via "MS GRAPH API Endpoint".
- Add support for the "Oauth 2.0 (v2) Token Endpoint".
NOTE: These instructions were created by using a basic Azure Active Directory configuration. It's possible that in addition to these steps, there are other policies, etc. you might need to create or modify.
Create a new application in AzureAD
You will need to create a new App Registration within AzureAD and gather the information needed for the Connector configuration on the fw Server app. Additionally you will need a user Group per each farmerswife Permission Profile and the Group Name / Object ID of those Groups.
Best Practice is to create the app, add the needed API Permissions and as the final step add a new Client Secret Key to the freshly created app on AzureAD.
Needed info summary:
- Application ID
- Client Secret Value
- Endpoint - OAuth 2.0 (v1) Token Endpoint
- Directory (tenant) ID
- Group Name(s)
- Group Object ID(s)
Additionally once the app is created you will need to add the appropriate API Permissions, more info below.
1) On Mircorsft Azure Create a new applications under App registrations
2) Make a note of the Application (Client) ID, Directory (tenant) ID as well as the OAuth 2.0 token endpoint (v1) under Endpoints:
3) Add the appropriate API permissions onto the application. As a note, more permissive permissions may be needed depending on your organizations configuration. From the left hand side select API permissions, then at the bottom of the list you will find Azure Active Directory Graph. We need to add 4 permissions each under delegated and application respectfully. Once added then grant admin consent for all of the permissions.
Permissions to add:
| Application | Delegated |
| Application.Read.All | Group.Read.All |
| Directory.Read.All | User.Read |
| Domain.ReadWrite.All | User.Read.All |
| Policy.Read.All | User.ReadBasic.All |
Correctly Configured Permissions:
4) Create a new Client Secret Key and make a note of the Client Secret Value - you will only be able to access this value on creation so be sure to copy out.
5) Within Active Directory - access (or create) any relevant groups for farmerswife users. Groups are used to be able to map different farmerswife Permission or Web Permission Profiles to specific groups of users.
Per each "group of users" needed to be mapped, create a Group and make note of the Object ID and Group Name:
Configure the farmerswife Server application
With all of the information configured and collected on Azure AD you can now configure the connection on the farmerswife Server app.
# Involved farmerswife-side settings:
- fw Server > Setup > Users > Microsoft Azure Active Directory Connector.
- fw Server/Client > Modify User > Microsoft Azure Active Directory Connector.
- fw Client > Toolbox > Settings > Server Setup > Microsoft Azure Active Directory Connector.
On the fw Server app click on Setup > Users > and go to the Microsoft Azure Active Directory Connector area.
Then input all of your information created while following the above Azure AD configuration steps:
- Enabled: No (by default), change to Yes to configure. Then change to No, if only Exchange365 is to be used.
- App Client Id: Use the above links to the Azure AD documentation on how to create these on your side.
- App Secret Key: Use the above links to the Azure AD documentation on how to create these on your side.
- Oauth 2.0 (v1) Token Endpoint: Use the above links to the Azure AD documentation on how to create these on your side.
- MS GRAPH API Endpoint: https://graph.microsoft.com
- Strip Domain Name From Username When Creating: On Azure the Usernames are Email Addresses. To avoid having to enter the complete email address when logging in, this setting is the tool to be used.
- MS Azure Extension Attribute ID to Import User Number: This is used to map a certain MS Azure Extension Attribute ID to then populate or import the value into the "Number" field on the Modify User window in farmerswife.
This is an example of a working demo configuration from v6.8 SP3:
User Groups are added by clicking on the green "+" plus icon, which then opens the User Group window:
Azure AD Group Name: Group name from Azure AD.
Azure AD Object ID: The Object ID of that Group from Azure AD.
User License Type: The farmerswife User License Type "Advanced User" or "Web User" to be used for this Group.
Permission Profile: The farmerswife Permission Profile or Web Permission Profile to be used for this Group.
Division (if licensed): The farmerswife Division the members of this Group will belong to.
NOTE: A best practice is, to create an AD SSO type category to make troubleshooting easier between users.
Once configured, use the Test button to test the Connector, which should then return this message "Windows Azure Connector Successfully Tested" if everything is correctly configured. If not consult the returned error info:
Then use the Sync Now button to trigger a sync of all users as per the added User Groups:
On the created user(s) - Things to note:
The Username is their AD Username with domain (this can be disabled so that it's username-only if desired, see above setting Strip Domain Name From Username When Creating), the Microsoft Azure Active Directory Connector is set to Enabled: Authenticate, Sync Profile and Possible Properties and the License Type and Permission Profile match with what was configured on Azure AD > User Group window.
You should now be able to log in with the sync'd user(s) to farmerswife.
Once syncing between Azure AD and farmerswife is active, you can manage sync intervals ("Sync Time") as well as add or modify User Groups (via the "Setup" button) directly from the fw desktop Client app without touching the fw Server app > Setup:
