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.
TABLE OF CONTENTS
- Creating the App Integration in Okta
- Configuring the farmerswife Server app
- Onboarding Okta users into farmerswife
- Conclusion
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 this, where here all "Optional" not supported options have been cleared; this is how it should look on your side:
This field on the above page "Sign-in 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.
Use the "Save" button to finish creating the "App Integration" on Okta.
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 to follow the above steps on Okta, and then provide the information marked below in yellow 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 is 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.