Okta: sync users
Bring people into MuchSkills from the Okta groups you choose, and keep them up to date. You create an API service app in Okta with a key pair, give it read-only access, and select groups in MuchSkills. Single sign-on with Okta is set up separately.
- Who
- A MuchSkills Owner or Admin, with an Okta Super Administrator
- How it connects
- Self-serve, in Settings › Integrations
- Sync
- Every 5 hours, or on demand with Sync Now
- Access
- Read-only
How to
Before you start
- In MuchSkills: the Owner or Admin role.
- In Okta: a Super Administrator. Only that role can grant Okta API scopes to an app.
- Decide who to sync first. The Okta sync works by group. Plan a group with five to ten people for the first sync. You can add people or groups afterwards.
- Tell people first. Starting the sync invites everyone in the selected groups to create their MuchSkills profile.
- Check email addresses. The email in Okta should be the address each person uses to sign in to MuchSkills.
Steps
In MuchSkills
- Open the Okta connector. Go to Team/Org › Settings › Integrations and click Connect on OKTA. Keep this tab open: you paste three values into it as you go. Do not click Connect on the form until step 10.
Team/Org › Settings › Integrations › OKTA.
In Okta
- Create an API service app. In the Okta Admin Console, go to Applications and Resources › Applications (Applications › Applications in some orgs) and click Create App Integration. If Okta offers a choice, pick Classic experience. Choose API Services as the Sign-in method and click Next. Name the app MuchSkills and click Save. Okta's guide to service apps
- Copy the Client ID and your domain. On the app's General tab, copy the Client ID into Client ID in MuchSkills. Then click your username in the upper-right corner of the Admin Console: your Okta domain appears in the menu, for example yourcompany.okta.com. Paste it into Domain. Okta's guide to finding your domain
- Switch to a key pair. In the Client Credentials section of the General tab, click Edit and choose Public key/Private key as the Client authentication method. Keep Save keys in Okta and click Add key.
- Generate the key and copy the private key. Click Generate new key. Okta shows the private key in JWK format. Leave it in JWK, without switching to PEM, click Copy to clipboard and paste the whole key, including the opening and closing braces, into Private Key (JWK) in MuchSkills. Okta shows the private key only once. Click Done, then Save, and confirm.
- Turn off proof of possession. Under General Settings, click Edit. If Require Demonstrating Proof of Possession (DPoP) header in token requests is ticked, clear it, then click Save. Okta's guide to DPoP
- Grant the read scopes. Open the Okta API Scopes tab and click Grant next to okta.users.read and okta.groups.read. It can take a few minutes before the grants take effect.
- Assign a read-only admin role. Open the Admin Roles tab and click Edit assignments. Under Role, choose Read-only Administrator, then click Save Changes. Okta asks you to authenticate. Okta's comparison of admin roles
- Create the group. Go to Directory › Groups, click Add Group, name it MuchSkills and click Save. Assign the people you want in MuchSkills to the group, starting with five to ten. Okta's guide to groups
Back in MuchSkills
- Connect. With all three values pasted in, click Connect. The status changes from Waiting for credentials to Api Connected.
The OKTA connector after connecting: 1 Client ID, 2 Private Key (JWK), 3 Domain, 4 Update Credentials. Identifying values blurred.
- Choose the groups. Sync by group lists the groups MuchSkills found in Okta. Type in Filter groups to find yours, then click a group to select it. Only people in the selected groups are synced. The sync options appear once at least one group is selected.
Sync by group: the groups MuchSkills found in Okta.
- Start the sync. MuchSkills shows how many employees will be synced and invited. Click the number to see their names, email addresses and groups. When the list looks right, click Start Sync.
Check it worked
- The connector shows Data is synced every 5 hours, with Last successful sync and Next scheduled sync.
- On Team/Org › Settings › Integrations, the OKTA tile shows Connected.
- Team/Org › Members lists the people you synced.
- The people you synced have an invitation to create their profile.
Benefits
What you get
- No manual upkeep. People you add to or remove from the selected groups in Okta follow in MuchSkills on their own.
- Your directory decides. Group membership, which your IT team already manages, controls who is in MuchSkills.
- Ready for single sign-on. The same people can log in with their Okta account once you add Okta single sign-on.
Important to know
Important to know
What syncs. Only email and name are required. Sync as many of the other fields as you can, because each one makes MuchSkills more useful.
| Field in MuchSkills | Needed | Used for |
|---|---|---|
| Name | Required | Profiles, search, every view |
| Required | Matching and sign-in | |
| Job title | Recommended | Profiles, roles, Discover |
| Department | Recommended | Departments and filters |
| Manager | Recommended | Reporting lines, My Circle, reports |
| Country | Recommended | Filters. Needs a custom attribute, see below |
| Profile photo | Recommended | Profiles and the org chart. Needs a custom attribute, see below |
Custom attributes. The default Okta profile has no photo, and stores country as a two-letter code. To sync a full country name, add a custom attribute with the variable name country to the Okta user profile in Directory › Profile Editor. A photo also needs a custom attribute: ask support@muchskills.com for the variable name before you add it.
Groups decide who syncs. Only people in the groups you select are synced. Select or clear groups at any time on the connector.
How often. Every 5 hours. Sync Now runs it immediately and Pause Sync stops it until you start it again.
Profile photos. Photos are saved when an account is created and are not updated by the automatic sync. Click Sync Now to pull in changed photos.
Leavers are deactivated, not deleted. When someone is deactivated in Okta, or drops out of the selected groups, MuchSkills deactivates them at the next sync. Their project history and certificates stay on record, which matters for audits.
No time off from Okta. Okta does not hold absence data, so availability in Team Builder and My Circle does not come from this connector.
Replacing the key. Generate a new key on the app in Okta, paste it into Private Key (JWK) and click Update Credentials. Once the app has Okta API scopes, only a Super Administrator can rotate its keys.
One people sync at a time. If another HR connector is already syncing, Start Sync asks Are you sure? and warns This action will stop your current integration sync. Click Yes, connect only if you want Okta to take over.
This is not single sign-on. This page covers the user sync. To let people log in with Okta, follow SAML/SSO setup with Okta.
Common errors
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| Invalid Credentials | A value is wrong: the private key was copied in PEM format or only in part, or the domain is not your Okta domain | Generate a new key, copy the whole JWK, check the domain from your username menu, then click Update Credentials |
| Invalid Credentials, although every value is right | The app still requires proof of possession (DPoP) | Repeat step 6, then click Update Credentials |
| We were not able to access your OKTA Groups. Please make sure you have granted the required permissions: 'okta.groups.read' and 'okta.users.read'. | The scopes are not granted, or the app has no admin role | Repeat steps 7 and 8, wait a few minutes, then click Update Credentials |
| No Start Sync button after connecting | No group is selected | Select at least one group under Sync by group |
| A new group is not in the list | The group was created after you opened the connector | Reload the connector page |
| Missing Attributes in API | Some users in the selected groups lack a required value, usually email | Fill in the missing values named in the message in Okta, then click Sync Now |
| Authentication failed multiple times. Please verify your OKTA credentials and permissions are correctly configured. | The key was deleted or replaced, the scopes were revoked, or the app was deactivated in Okta | Check the app in Okta, paste in a working key and click Update Credentials |
| A photo has not changed | Automatic syncs do not update photos | Click Sync Now |
Frequently asked questions
Is this the same as Okta single sign-on?
No, they are set up separately. This page brings people into MuchSkills from Okta groups. Single sign-on lets them log in with their Okta account, and has its own guide: SAML/SSO setup with Okta.
Which Okta roles do we need?
A Super Administrator, because only that role can grant Okta API scopes to an app. The service app itself gets the read-only administrator role. In MuchSkills you need the Owner or Admin role.
Why a private key and not a client secret?
Okta only gives access tokens with Okta API scopes, such as okta.users.read, to service apps that authenticate with a public and private key pair. A client secret does not work for this.
Can we start with a few people before syncing everyone?
Yes, and we recommend it. Put five to ten people in a MuchSkills group in Okta and select only that group. Check the result in MuchSkills, then add people to the group or select more groups.
Can we use groups we already have?
Yes. Sync by group lists the groups MuchSkills can read in your Okta org. Select one or more of them. A dedicated group makes it easy to see who is in MuchSkills.
How often does the sync run?
Every 5 hours. An Owner or Admin can run it at any time with Sync Now on the connector.
What happens when someone leaves?
When a person is deactivated in Okta, or removed from the groups you selected, MuchSkills deactivates them at the next sync. They disappear from everyday views, and their project history and certificates stay on record. Nothing is deleted.
Does MuchSkills change anything in Okta?
No. The app only has read scopes and a read-only role. MuchSkills reads the people in the selected groups and never changes anything in your Okta org.
Do employees get an email when we start?
Yes. Starting the sync invites everyone in the selected groups to create their MuchSkills profile, so tell people about MuchSkills before you click Start Sync.