SCIM provisioning: how it works

Your identity provider can create, update and deactivate people in MuchSkills over SCIM 2.0. This is the reference: the connection values, how authentication works, the supported operations, which fields MuchSkills uses, roles, and what to check when something goes wrong.

Updated

Connected on requestITAdmins and HR

Standard
SCIM 2.0, users only
Base URL
`https://app.muchskills.com/scim/v2`
Authentication
OAuth 2.0, client credentials or authorization code
Plans
Included in all plans

How it works

Your identity providerThe people you assign to the MuchSkills app
SCIM 2.0 over HTTPS: create, update, deactivate
MuchSkills receivesMatches people by email address and applies your field mapping
Each change
Your workspacePeople, roles, departments and managers, kept current

Your identity provider pushes changes to MuchSkills. When you assign someone to the MuchSkills app, the provider creates them. When their details change, it sends an update. When you unassign or disable them, it deactivates them. MuchSkills never writes anything back to your identity provider.

Before you start

  • In MuchSkills: the Owner or Admin role.
  • In your identity provider: an administrator who can set up provisioning for an app.
  • SCIM credentials from MuchSkills. We create an OAuth 2.0 client ID and client secret for your organisation. The secret does not expire. Keep both in your password manager.
  • Single sign-on first. We recommend it, so provisioned people can log in straight away. Your identity provider may let you add provisioning to the same app.
  • Email addresses. The userName you send must be the email address each person uses for MuchSkills.
  • Start small. Assign a handful of people first, check the result in MuchSkills, then assign the rest.

Steps

In MuchSkills

  1. Ask support for SCIM credentials. Email support@muchskills.com or use the chat, and say which identity provider you use. We create a client ID and client secret for you and send them through a secure channel. Until provisioning is set up, Team/Org › Settings › Security & SAML says SCIM provisioning is available for your organisation. See the setup guide for next steps.

In your identity provider

  1. Open the provisioning settings of your MuchSkills app. Microsoft Entra ID and Okta have their own guides: Microsoft Entra ID: SCIM provisioning and Okta: SCIM provisioning.
  2. Enter the connection values.
SettingValue
SCIM version2.0
Base URL (also called Tenant URL or SCIM connector base URL)https://app.muchskills.com/scim/v2
Unique identifier for usersuserName
AuthenticationOAuth 2.0, with the client ID and client secret from MuchSkills
Grant typeClient credentials (preferred) or authorization code
Token endpointhttps://app.muchskills.com/oauth2/token
Token lifetimeAccess tokens last one hour. Refresh tokens (authorization code flow) last 90 days and rotate on every use
  1. Choose what the provider may do. Turn on creating users, updating user attributes and deactivating users. Leave group push, group import and user import off.
  2. Check the attribute mapping. userName must carry the email address. Map as many of the fields in the table under Important to know as your provider holds.
  3. Test the connection. Most providers have a Test Connection button or similar. It succeeds when the base URL and credentials are right.
  4. Assign a few people and push them. Check them in MuchSkills, then assign the rest.

Back in MuchSkills

  1. Check the people who arrived. Team/Org › Members lists them, with the roles you sent.
The Security & SAML screen in MuchSkills with the SCIM provisioning line and its setup guide link shown under Email domains

The SCIM line on Security & SAML links to this guide.

Check it worked

  • Your identity provider's provisioning log shows the users as created without errors.
  • Team/Org › Members lists the people you assigned, with the right names, titles, departments and managers.
  • In the member list, a sync icon next to each provisioned person shows User profile is currently syncing via SCIM. when you point at it.
  • Team/Org › Settings › Security & SAML says SCIM provisioning is enabled for your organisation.

What you get

  • Joiners and leavers handled for you. People get a MuchSkills account when you assign them, and are deactivated when you remove them.
  • One place to manage access. Your identity provider stays the source of truth for who uses MuchSkills and with which role.
  • Tidy people data. Names, titles, departments and managers arrive ready for filters, reports and My Circle.

Important to know

Supported operations. All paths start with https://app.muchskills.com/scim/v2.

MethodPathWhat it does
GET/UsersLists users. Supports pagination and filtering on userName
GET/Users/ followed by the user's idReturns one user
POST/UsersCreates a user
PUT/Users/ followed by the user's idReplaces a user's attributes
PATCH/Users/ followed by the user's idUpdates some of a user's attributes
DELETE/Users/ followed by the user's idRemoves the user from your organisation. As with every leaver, MuchSkills deactivates the person and keeps their history

Filtering and pagination. Filters support eq on userName, for example filter=userName eq "anna.berg@example.com". Pagination uses startIndex and count.

Groups are not provisioned. MuchSkills accepts users only. Leave group push off. Assigning groups in your identity provider still works for choosing who is provisioned.

What syncs. Only email and name are required. Send as many of the other fields as you can, because each one makes MuchSkills more useful.

SCIM attributeNeededUsed in MuchSkills forNotes
userNameRequiredEmail and loginMust be a valid email address: the one the person logs in with
emailsRequiredEmailThe primary email must match userName
displayNameRequired, or the two name partsNameThe name shown everywhere in MuchSkills
name.givenName, name.familyNameRecommendedNameUsed to build the name when displayName is missing
titleRecommendedJob titleProfiles, roles, Discover
enterprise extension: departmentRecommendedDepartmentCreated in MuchSkills if it does not exist yet
enterprise extension: managerRecommendedManagerThe manager's MuchSkills user id or email address. Reporting lines and My Circle
addressesRecommendedLocationBuilt from the work address as "City, Region", or "City, Country" when there is no region. Street and postal code are not stored
rolesOptionalRoleThe primary value sets the role: Admin, Member or Analyst
activeRecommendedStatusfalse deactivates the person and keeps their history
photosOptionalProfile phototype photo or thumbnail. MuchSkills stores the image from the URL
idSet by MuchSkillsUser idReturned when the user is created. Your provider uses it for later updates

MuchSkills also has its own user extension with a profilePicture field, a simpler alternative to photos. Ask support for its schema name if you want to use it.

Roles. Send one role per person in roles, marked as primary. Valid values are Admin, Member and Analyst. Other values are ignored, and people without a role join as Member. The Owner role cannot be set over SCIM.

Example user. A create request from your identity provider looks like this:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "userName": "anna.berg@example.com",
  "active": true,
  "displayName": "Anna Berg",
  "name": {
    "givenName": "Anna",
    "familyName": "Berg"
  },
  "emails": [
    { "value": "anna.berg@example.com", "type": "work", "primary": true }
  ],
  "title": "Senior Consultant",
  "roles": [
    { "value": "Analyst", "primary": true }
  ],
  "photos": [
    { "value": "https://example.com/photos/anna-berg.jpg", "type": "photo" }
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "department": "Advisory",
    "manager": { "value": "erik.lund@example.com" }
  }
}

Leavers are deactivated, not deleted. Whether your provider sends active set to false or a DELETE request, the person leaves everyday views and their project history and certificates stay on record, which matters for audits.

No allow list needed. SCIM requests go from your identity provider to MuchSkills, so you do not need to allow MuchSkills addresses for them.

Email addresses are managed by your provider. People provisioned over SCIM cannot change their email address in MuchSkills. In Profile Settings › Account, they see Managed by automated provisioning under Your email.

Data MuchSkills does not accept. Age or date of birth, salary or other compensation data, performance ratings, and political, religious or health data are blocked when data arrives and never stored.

Troubleshooting

What you seeWhyWhat to do
Requests fail with 401 UnauthorizedThe client ID or client secret is wrong, the token endpoint is wrong, or an access token older than one hour was reusedCheck the values against what we sent you, and let your provider fetch a new token. Ask support for new credentials if you are unsure
The connection stops after about three months (authorization code flow)The refresh token was not used for 90 days and expiredReconnect the app in your provider to get a new refresh token
Creating a user fails with 409 ConflictA user with that email address already existsCheck whether the email is already in use in MuchSkills, and that userName is a unique email address
Users do not appear in MuchSkills after a pushThe request was rejected, often because userName is not a valid emailCheck your provider's provisioning log for the error and the userName format
Changes in your provider do not reach MuchSkillsProfile updates are switched off in your providerTurn on updating user attributes, then check that PUT or PATCH requests succeed in the log
Error invalid_filter when your provider looks up usersThe provider filters on an attribute other than userName, or uses an operator other than eqSet userName as the unique identifier or matching attribute
Error user not found when updating or deactivatingThe user id in the request does not exist in MuchSkillsLook the user up with GET /Users and a userName filter, then retry from your provider
500 Internal Server ErrorAn unexpected error on the MuchSkills side, sometimes caused by an unusual payloadContact support with the time of the request and the user's email address
Which identity providers work with MuchSkills SCIM?

Any provider that supports SCIM 2.0 user provisioning. Microsoft Entra ID and Okta have their own step-by-step guides. OneLogin, JumpCloud and others use the values on this page.

Where do we get the SCIM credentials?

MuchSkills creates them for you: a client ID and a client secret. Email support@muchskills.com or use the chat, and say which identity provider you use.

Which OAuth 2.0 flow should we use?

Client credentials where your identity provider supports it: the provider exchanges the client ID and secret for a token on its own. The authorization code flow works too. MuchSkills does not issue static tokens.

Do the credentials or tokens expire?

The client secret does not expire. Access tokens last one hour, and your identity provider fetches new ones on its own. With the authorization code flow, the refresh token lasts 90 days and is replaced with a new one each time it is used.

Do groups sync to MuchSkills?

No. MuchSkills accepts users, not groups. You can still assign groups in your identity provider to decide who is provisioned.

What happens when someone leaves?

When your identity provider sends active set to false, or removes the user, MuchSkills deactivates the person. They leave everyday views, and their project history and certificates stay on record. Nothing is deleted.

Can we set roles from our identity provider?

Yes. Send the roles attribute with Admin, Member or Analyst as the primary value. Anything else is ignored, and people without a role join as Member.

Which fields are required?

Only the email address and the name. Send as many of the other fields as you can, because each one makes MuchSkills more useful.

Do we need single sign-on as well?

It is not required, but we recommend setting up single sign-on first. Then people created over SCIM are sent to your identity provider to log in, instead of being asked to set a MuchSkills password.

Is SCIM included in our plan?

Yes. All MuchSkills plans include SCIM provisioning and single sign-on (SAML).

Checking Daniel’s calendar...

Ask us anything

A real person replies, usually the same working day.

Live webinar

Register for our next webinar