Set up single sign-on with Okta

This article is for administrators who may change settings, such as the Tenant administrator. In Okta you need an administrator role that can create app integrations, such as Application Administrator or Super Administrator.

Before you start

1. In FairPro, open Security and choose Add an identity provider.
2. Keep that page open. The panel What your identity provider needs shows the values you copy into Okta: Entity ID (audience), Reply URL (ACS) and Email attribute.

If the page says single sign-on is not switched on for this site yet, FairPro support can tell you when it is.

Make the application in Okta

1. In the Okta Admin Console, go to Applications, then Applications, and choose Create App Integration.
2. Choose SAML 2.0 and choose Next.
3. Name it FairPro. Tick Do not display application icon to users, then choose Next. FairPro accepts only sign-ins that start on its own sign-in page, so a tile on the Okta dashboard would not work.
4. Paste FairPro’s Reply URL (ACS) into Single sign-on URL, and keep Use this for Recipient URL and Destination URL ticked.
5. Paste FairPro’s Entity ID (audience) into Audience URI (SP Entity ID).
6. Set Name ID format to Persistent. FairPro’s sign-in service asks for this format, and Okta refuses the sign-in when the application is set to another.
7. Set Application username to Custom and type user.getInternalProperty(“id”). Okta then sends the person’s Okta user ID as the NameID, which never changes, unlike their email address.

If FairPro’s page asks you to send the email address as the NameID instead, choose Email as the application username.

Send the email address

Under Attribute Statements, add these, each with Name format set to URI Reference:

• Name http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress with Value user.email. This is FairPro’s Email attribute, and FairPro refuses a sign-in without it.
• Name http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name with Value user.firstName + “ “ + user.lastName. FairPro uses it as a new person’s name when it adds people on their first sign-in.

Choose Next, answer Okta’s question about the app and choose Finish.

Give FairPro the metadata

1. In Okta, on the application’s Sign On tab, find Metadata details and copy the Metadata URL.
2. Back in FairPro, fill in Name, such as Okta, and your Email domains, such as example.com.au.
3. Paste the address into Metadata address and choose Add identity provider.

Prove your domains and connect

1. FairPro shows a TXT record. Add it to the DNS of each email domain.
2. Choose Check DNS records. A new record can take a while to show up.
3. When the domains are proved, choose Connect. Where there is no Connect, FairPro connects it within a few minutes; refresh the page to see.

Let people in and test it

1. In Okta, on the application’s Assignments tab, choose Assign, then Assign to People or Assign to Groups. Only people assigned there can sign in through it.
2. In FairPro, invite the same people under People with the same email address, or choose Add people on first sign-in on the identity provider’s page. They start with no role and see nothing until you give them one. Okta can also add people for you; see the guide on SCIM.
3. Test it yourself: on FairPro’s sign-in page, type your work email and choose Sign in with single sign-on.
4. When it works, choose Require it on the identity provider’s page if everyone at those domains should sign in through Okta. Administrators can still sign in with their password by adding ?method=password to the sign-in page’s address, so a broken identity provider cannot lock you out.

People who sign in through Okta are not asked for a FairPro authenticator code or passkey. Ask for a second factor in Okta instead, with an authentication policy for the application.