This article will detail the requirements and information needed to integrate the farmerswife (fw) Server app with "Microsoft Entra ID Connector" Single Sign On (SSO) conditional access with Multi Factor Authentication (MFA) by using "OpenID Connect".
NOTE: These instructions are created by using a basic Entra ID configuration. Do not use any of the example information. It's possible that in addition to these steps, there are other policies, etc. you might need to create or modify.
Requirements:
- To use the farmerswife (fw) Server-side "Entra ID Connector" and "OpenID Connect" integration does not need to be licensed. We kindly request to inform us of using it if you are self-hosting your farmerswife system. This will help us on supporting you using this integration.
- In order for the "Entra ID Connector" to work with "OpenID Connect", your farmerswife system needs to be running on v7.1 (7.1.1000-0- released 28th of August 2024) and later.
- The fw Server app must be configured to use the optional "server.cfg" (more info here) and use in HTTP_HOME https://dowmainname) and the field in farmerswife Server app > Setup > General > Url To Server must contain the info of the qualified domain name.
Creating the "Application" integration on Entra ID
On EntraID create a new App Registration and gather the information needed for the EntraID and OpenID Connectors configuration within the fw Server app.
Additionally you will need a user Group per each farmerswife Permission Profile and Web Permission Profile and the Group Name / Object ID of those Groups from EntraID.
In our experience it is best to first 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 EntraID.
Summary of needed info from EntraID and used on fw Server side
| From Entra ID | fw Server > Setup > User > MS Entra ID Connector |
| Group Name(s) | User Groups > Entra ID Group Name |
| Group Object ID(s) | User Groups > Entra ID Object ID |
| From Entra ID > App registrations | fw Server > Setup > User > OpenID Connect |
| Application ID: | Client ID: |
| Client Secret Value | Secret Key: |
| OAuth 2.0 authorization endpoint (v2) | Auth URL: |
| OAuth 2.0 token endpoint (v2) | Token URL: |
| Directory (tenant) ID | Userinfo URL: https://graph.microsoft.com/oidc/userinfo |
| - | Scope: openid profile email offline_access |
| Application ID: | Audience: |
| (App > Web Redirect URIs) | Local Target: "externalURL:ApiPort" |
1) Sign into: https://entra.microsoft.com/
Then go to Applications > App registrations and here create a new App.
Give it a Name.
Set the Redirect URI to Web.
And click on Register. 
2) Retrieve the info of the Application (Client) ID and Directory (tenant) ID:
And the OAuth 2.0 authorization endpoint (v2), OAuth 2.0 token endpoint (v2) under Endpoints:
3) On your freshly created app go to API permissions. Click on "+ Add a permission" select Microsoft Graph and add these 8 Permissions:
| 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 |
As the last step, you need to use the "Grant admin consent for MSFT" button (see above screen shot) to finish the API Permissions part to then look like this:
4) On your freshly created app go to Certificates & secrets. Click on "+ New client secret" set a Description and choose when it Expires.
IMPORTANT NOTE:
Since v701 it's now possible to update the Client Secret Value from the fw Client desktop app in Toolbox > Settings > Server Setup > Microsoft Entra ID Connector > "Setup" button > "Update Secret Key" button. This is very helpful when you have to work with Client Secrets which expire frequently.
From the new Client Secret Key save the Client Secret Value - you are only able to access this value on creation so be sure to copy it. Otherwise you need to create a new one:
5) Within Entra ID - 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. On the "Sync" with farmerswife these are then either created or modified to either become a Advanced User or Web User and then have the correct Permission or Web Permission Profile assigned to their user in farmerswife.
Make a note of the and Group Name(s) and Group Object ID(s) to be used for farmerswife.
6) Within Entra ID App registrations > your app > Authentication configure the Web Redirect URIs
The above marked field "Web Redirect URIs" needs to contain the counter part info of the "Local Target" field on the fw Server app-side, in this format:
https://fw-server-app-URL:ApiPort/oidc/callback
You need to change this according to your environment.
If your system is farmerswife cloud hosted, you will receive the needed Web Redirect URIs info from us.
Use the "Save" button to finish creating the "App registration" on Entra ID.
Configuring the farmerswife Server app:
The following info is needed for self-hosted farmerswife systems and parts of it for fw-cloud hosted farmerswife system.
If your system is cloud-hosted by farmerswife, you need to follow the above steps on Entra ID, and then provide the information marked below in yellow to your farmerswife Product Specialist, for this info to be populated on your system and to then schedule a remote session to verify the setup and test the sign-in.
VERY IMPORTANT: you MUST use the EXACT info as in the provided examples.
Go to the running farmerswife Server app > Setup > Users tab. There are two areas which require configuration:
1) The "Microsoft Entra ID Connector:" area:
Enabled: No (by default), change to Yes to configure.
Use OpenID Connect: No (by default), change to Yes to use EntraID with OpenID Connect.
User Groups:
Create here the needed Groups to map the fw Permission Profiles and Web Permission Profiles needed when users get "synced" (created & updated) from Entra ID.
Entra ID Group Name: The Group name on Entra ID.
Entra ID Object ID: The Object ID of that Group on Entra ID.
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.
IMPORTANT NOTE:
The list of Groups supports a "hierarchal" structure in descending order! This is needed to support "Groups inside of Groups".
The Group with the "highest Permission level" must get created 1st; and then the following Groups, which still need to be created in the correct order.
Strip Domain Name From Username When Creating: On EntraID the Usernames are Email Addresses.
This feature was on previous versions used, to avoid having to enter the complete email address when authenticating against EntraID (former Azure AD).
Now, with using OpenID Connect for MFA this setting can't be used. ... being verified.
Notes: we use UserPrincipalName + Entra connector sync user => username in fw ... authentication ... we delegate login by redirecting the user with a session identifier (namedsessionid) once the user has succesfully authencitact against entra is redirecting back to fw server with the session identifier ... and a authorisation code ... that fw can use to get an entra access token that fw will use, to get the user data from the openId userinfo endpoint sessionintifier linke to the userinof in entra to match the existing fw user.
Re-test.
MS Entra ID Extension Attribute ID to Import User Number: This is a setting for a specific custom work-flow.
It is used to map a certain Entra ID Extension Attribute ID to then populate or import the value into the "Number" field on the Modify User window in farmerswife.
"Test:" button gets used once you're done with the configuration, to test the Entra ID Connector config, which should then return this message "Windows Entra ID Connector Successfully Tested" if everything is correctly configured.
If not consult the returned error info.
maybe add image
"Sync Now:" button is used to manually trigger a sync of all users as per the added and configured user Groups on EntraID AND your farmerswife Server.
maybe add image
2) The "OpenID Connect:" area:
Go to your running fw Server app > Setup > General > Users tab > "OpenID Connect" section to populate these fields as per this example:
Enabled: "No" (default) / Set to "Yes" to enable this integration.
Provider Name: This is empty by default. The current options are:
- OpenID
- Entra ID
- Okta
Use here "Entra ID". This will then be displayed on the fw Client desktop app's Login window, the Web Clients Login page and the Mobile Web Clients Login page, where this button then opens the EntraID's sign-in web page, see the images below in the "Onboarding Entra ID users into farmerswife" section.
Client ID: Provided by Entra ID when a new "Integration App" gets created as per the above info.
Secret Key: Provided by Entra ID when a new "Integration App" gets created as per the above info.
Auth URL: Provided by Entra ID from the new created "Integration App" within the "Endpoints" tab in this format:
https://login.microsoftonline.com/yourApps-DirectoryTenantID/oauth2/v2.0/authorize
Token URL: Provided by Entra ID from the new created "Integration App" within the "Endpoints" tab in this format:
https://login.microsoftonline.com/yourApps-DirectoryTenantID/oauth2/v2.0/token
Userinfo URL: Keep this exact string in this field:
https://graph.microsoft.com/oidc/userinfo
Scope: Keep this exact string in this field:
openid offline_access profile email
Audience: Add here the same info as on above "Client ID".
Local Target: Enter here this info: "externalURL:ApiPort" or if an additional sub-domain is configured to ensure HTTPS via Port 443 traffic routing; e.g.:
demodummy-eu.cloud.farmerswife.com:25000
api.demodummy-eu.cloud.farmerswife.com
Optional Setting "Hide User/Password Login Form":
=> Please Rename to "Hide Username/Password/Login Button From Login Forms"?
Or "Only Show Login With External Provider".
... being verified
Since v7.1 there is also this new setting in fw Server > Setup Users at the bottom right hand side called "Hide User/Password Login Form". By default this is disabled., set to No.
Once this is set to Yes, then this will hide the farmerswife Username and Password fields from the Login windows/pages of the fw Client desktop app, iOS fw app (pending to verify on v0.8.???), Web Client and Mobile Web Client. See below images (pending to be added).
Onboarding Entra ID users into farmerswife
On the created / synced user(s) - Things to note on the Modify User window:
The Username in farmerswife IS the EntraID sign-in Name including the domain info.
This can be disabled so that it's username-only if desired, see above setting Strip Domain Name From Username When Creating). .. being verified.
The fields "Username", "Password" and "Email" are "blocked" on synced users from EntraID; note the white-ish color on those fields:
These 3 blocked fields can't be changed as long as on the "Microsoft Entra ID Connector" setting is set to one of the three "Enabled" options:
The option Enabled: Authenticate, Sync Profile and Possible Properties and the User License Type and Permission Profile match with what was configured on EntraID Connector > User Group window.
Access via fw Client desktop app on macOS and Windows
add image wip
Access via iOS fw app
add image wip
Access via Web Client
add image wip
Access via fw Mobile Web Client
add image wip