Requirements:
- To use the farmerswife (fw) Server-side "OpenID Connect" integration does not need to be licensed.
- In order for the "OpenID Connect" integration to work with "Okta Single Sign On", your farmerswife system needs to be running on v6.8 Service Pack 1 (released 24th of August 2022).
- The fw Server app must be configured to use the optional "server.cfg" (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 App Integration in Okta:
Go to https://www.okta.com/topic/single-sign-on/ and register a new "Free Trial" account, if you're evaluating this.
Or, use your Company's access credentials to log in to https://www.okta.com.
When logged into Okta enter the Admin console.
On the left menu go to Applications and the to the "Applications" sub-menu.
Then use the button "Create App Integration", see below:
On the next "Create a new app integration > Sign-in method" window, select the first option "OIDC -OpenId Connect", and then select again the first "Applicatoin type" option "Web Application", which will then look like this:
Use "Next".
The next window should like like this, where here all "Optional" not supported options have been cleared; this is how it should look on your side:
Use the "Save" button to finish creating the "App Integration" on Okta.
If you are using "Access Groups" in Okta, you can also set who will have access to the new application integration you are creating on the Okta "My Web App" page.
When Limit access to selected groups is selected, it will prompt you to select which "Groups" will be able to use this integration.
IMPORTANT: Any user in farmerswife needs to be "manually" onboarded (see more info below); an automated "user sync" is not supported; this is subject to purchased feature implementation.
Configuring the farmerswife Server app:
The following info is for self-hosted farmerswife systems. If you are cloud-hosted by farmerswife, you need follow the above steps on Okta, and then provide the information below to your farmerswife Product Specialist.
VERY IMPORTANT: you MUST use the EXACT info as provided below.
Go to your running fw Server app > Setup > General > Users tab > "OpenID Connect" section:
Most of the information in this section will be provided by Okta when a new application integration gets created.
"OpenID Connect" settings list:
Enabled: "No" (default) / Set to "Yes" to enable this integration.
Client ID: Provided by Okta when a new "Integration App" gets created as per the above info.
Secret Key: Provided by Okta when a new "Integration App" created as per the above info.
Auth URL: Provided by Okta in this format: https://sso.companyname.com/oauth2/default/v1/authorize ... i.e. you only need exchange this part "sso.companyname.com" to what you are using on Okta.
Token URL: Provided by Okta in this format: https://sso.companyname.com/oauth2/default/v1/token ... i.e. you only need exchange this part "sso.companyname.com" to what you are using on Okta.
Userinfo URL: Provided by Okta in this format: https://sso.companyname.com/oauth2/default/v1/userinfo ... i.e. you only need exchange this part "sso.companyname.com" to what you are using on Okta.
Scope: Keep this exact string in this field: openid offline_access profile email
Audience: This is the same info as on the above "Client ID:"
Local Target: Enter here this info: "externalURL:ApiPort"; e.g.: demo.farmerswife.com:25000
Getting the needed info from Okta:
When logged into Okta enter the Admin console.
On the left menu select the Applications tag under Applications. Select the application that was created for the farmerswife Integration. On the General tab, you will find the Client ID and Secret Key.
For the Authorize, Token, and Userinfo endpoint information, it will usually be a URL that is associated with your company's name (as seen in the example above).
Please also see and use the Okta endpoint documentation:
https://developer.okta.com/docs/reference/api/oidc/
Work-in-progress, adding missing topics, last updated 2023-07-06:
Onboarding Okta users into farmerswife
The "OpenID Connect" functionality in farmerswife does not support "syncing" users from Okta to farmerswife. It's designed for existing Advanced Users or Web Users and Contact type Resources to be able to authenticate against Okta as the "OpenID Provider".
Go to fw Client desktop app > main module bar Object Manager > and here search for each user separately, double click to then enable the "OpenID Connect Mode" via the Modify User window:
Access via fw Client desktop app on macOS and Windows
Access via iOS fw app
Access via Web Client
Access via fw Mobile Web Client
Conclusion:
These are the main steps needed to create the farmerswife/Okta integration.
Remember, in order to use this integration the properly configured fw server app must be running, to be able to handle requests for logins from Okta.