Single Sign-On with Okta

This guide connects Okta to Workprentice for single sign-on and directory provisioning. You need to be an owner of the Workprentice organization and an administrator in Okta, and your email domain must already be verified by DNS.

Keep two tabs open: Organization settings → Single sign-on in Workprentice, with Okta chosen at the top, and the Okta Admin Console. The steps follow Okta’s console as its documentation describes it. Okta renames screens from time to time, so where a label differs, go by the field names in the tables.

Single sign-on

Create the application in Okta

1. In the Okta Admin Console, open Applications → Applications and choose Create App Integration.

2. Pick SAML 2.0 and choose Next.

3. Name the app Workprentice and choose Next.

4. Under Configure SAML, fill in these fields from the Workprentice page:

   Okta field	Value from Workprentice
   Single sign-on URL	Single sign-on URL
   Audience URI (SP Entity ID)	Audience
   Name ID format	EmailAddress
   Application username	Email

   Leave Use this for Recipient URL and Destination URL checked, and leave Default RelayState empty.

5. Choose Next, answer Okta’s feedback question, and choose Finish.

Okta’s defaults sign both the response and the assertion and encrypt neither, which is what Workprentice expects.

Bring Okta’s details back

1. On the app’s Sign On tab, open View SAML setup instructions.

2. Copy each value into Workprentice:

   Okta shows	Workprentice field
   Identity Provider Issuer	Issuer
   Identity Provider Single Sign-On URL	Sign-in URL
   X.509 Certificate	Signing certificate

3. Save in Workprentice.

Assign people and test

On the app’s Assignments tab, assign the people or groups who should have access. Then open a private browser window, go to the Workprentice sign-in page, enter your work email, and choose Continue with single sign-on.

The Workprentice tile on the Okta dashboard works too. No start URL is needed in Okta for it.

When it works, an owner signed in through Okta can require single sign-on.

Directory provisioning

Turn on SCIM for the app

1. In Workprentice, under Directory provisioning, choose Turn on directory provisioning, then create a token named Okta. Copy the token now; it is shown once.

2. In Okta, on the app’s General tab, choose Edit under App Settings, set Provisioning to SCIM, and save. A Provisioning tab appears.

3. On Provisioning → Integration, choose Edit and fill in:

   Okta field	Value
   SCIM connector base URL	SCIM endpoint from Workprentice
   Unique identifier field for users	userName
   Supported provisioning actions	Push New Users, Push Profile Updates, Push Groups
   Authentication Mode	HTTP Header
   Authorization	The token from Workprentice

4. Choose Test Connector Configuration, then Save.

Choose what Okta sends

On Provisioning → To App, choose Edit and turn on Create Users, Update User Attributes, and Deactivate Users. Deactivate Users is the one that removes a leaver from Workprentice, so do not skip it.

Okta sends each person’s Okta username as userName. If your Okta usernames are not email addresses, map the app’s userName to the person’s email on the To App attribute mappings.

Push groups

On the app’s Push Groups tab, choose Push Groups → Find groups by name, pick a group, and save. The group then appears in Workprentice under Group access, where you map it to a workspace and a role.

Okta recommends using one set of groups to assign the app and a different set to push, since a group used for both can fall out of step.

If something does not work

• Sign-in fails with “could not be completed”. Check that the certificate in Workprentice is the app’s current one, and that the two URLs in Okta match the Workprentice page exactly.
• Someone signs in at Okta but is refused. With provisioning on, they must be assigned to the app so Okta lists them. Their email must also be at a domain you have verified.
• A deactivated person is still a member. Confirm Deactivate Users is on, then check the app’s provisioning tasks in Okta for a failed request. An organization owner is never removed this way.