Skip to main content

Set up SCIM provisioning with OneLogin

Provision wxrks users from OneLogin with SCIM 2.0.

SCIM (System for Cross-domain Identity Management) keeps wxrks user accounts in sync with OneLogin. Once it's configured, your IT team creates, updates and deactivates wxrks users from OneLogin instead of a wxrks admin managing every account by hand.

Who is this for? Account Admins, working with the OneLogin administrator who manages your company's applications.

How SCIM provisioning works

SCIM provisioning is separate from wxrks Single Sign-On (SSO): SSO controls how a user logs in, while SCIM controls whether their wxrks account exists, and which role and Organizational Unit it starts in. You can use one OneLogin application for both (see Use one OneLogin application for both SSO and SCIM).

With SCIM provisioning on, OneLogin can:

  • create a wxrks account when a user is given access to the application;

  • update the user's name and email when they change in OneLogin;

  • add a wxrks role from the role value OneLogin sends;

  • deactivate the wxrks account when the user loses access, if you choose Delete as the deprovisioning action (see below).

⚠️ Warning — OneLogin adds roles but never removes them. When OneLogin sends a role value that has a Role Mapping row, wxrks adds the mapped role and keeps the roles the user already had. A value with no Role Mapping row leaves the user's roles unchanged. To take a role away from a provisioned user, remove it in People > Users.

For every attribute and operation wxrks accepts, see the SCIM user provisioning reference.

Prerequisites

  • Account Admin access in wxrks.

  • A OneLogin administrator account that can add applications and enable provisioning.

  • Every user in OneLogin has an email address. wxrks identifies users by email.

Find your SCIM credentials in wxrks

Go to Settings > Account Settings > Identity & Security, open the User Provisioning tab, and expand SCIM Provisioning.

Identity & Security > User Provisioning tab with a red box around the expanded SCIM Provisioning card: SCIM Base URL with its copy button, Secret Token with the Generate button, Role Mapping with Add Role Mapping, Default Organizational Unit, and Save SCIM Settings.

  • SCIM Base URL — copy it with the copy button.

  • Secret Token — click Generate, then copy the token immediately. It's shown only once, and generating a new one invalidates the old one.

  • Role Mapping — add one row per role value OneLogin will send (see Map OneLogin roles to wxrks roles).

  • Default Organizational Unit — every user OneLogin creates is placed here.

Click Save SCIM Settings, then click OK to confirm.

Configure SCIM in OneLogin

OneLogin renames screens from time to time. If a label below doesn't match your admin portal exactly, look for the closest equivalent.

Add the application

  1. In the OneLogin admin portal, go to Applications > Applications and click Add App.

  2. Search for SCIM Provisioner and select SCIM Provisioner with SAML (SCIM v2 Enterprise). The catalog lists several similar variants; pick the one with exactly this title.

  3. In Display Name, enter a name such as "wxrks", and click Save.

OneLogin Find Applications page searched for SCIM Provisioner, with a red box around SCIM Provisioner with SAML (SCIM v2 Enterprise), the connector to select among several similar variants.

Configure the connection

  1. Open the app's Configuration tab.

  2. SCIM Base URL: paste the SCIM Base URL from wxrks.

  3. SCIM JSON Template: keep the default template. It already sends what wxrks needs:

    • userName, taken from the SCIM Username parameter (set it to the user's email in step 6);

    • name.givenName and name.familyName (wxrks sets the name only when it receives both);

    • emails with the work email flagged "primary": true (wxrks ignores an email that isn't flagged primary).

    You add the role line later (see Map OneLogin roles to wxrks roles).

  4. SCIM Bearer Token: paste the Secret Token from wxrks.

  5. Click Save, then click Enable under API Connection. The status changes to Enabled.

  6. Open the Parameters tab, click SCIM Username, set Value to Email, and click Save. By default it sends the OneLogin username, which wxrks can't match to an email.

OneLogin app Configuration tab: badge 2 marks the SCIM Base URL field (value masked), badge 3 the SCIM JSON Template, badge 4 the SCIM Bearer Token field (value masked), and badge 5 the API Status showing Enabled.

Configure the Provisioning tab

  1. Open the Provisioning tab and select Enable provisioning.

  2. Clear the admin-approval options (Create user, Delete user, Update user) if you want changes to flow without manual approval.

  3. Under When users are deleted in OneLogin, or the user's app access is removed, perform the below action, choose Delete. wxrks never erases a user on DELETE: it deactivates the account, which blocks sign-in and keeps the user's history.

  4. Under When user accounts are suspended in OneLogin, perform the following action, keep Suspend. OneLogin then sends "active": false, which wxrks also treats as a deactivation.

  5. Click Save.

OneLogin app Provisioning tab: badge 1 marks Enable provisioning (checked), badge 2 the cleared admin-approval checkboxes, badge 3 the deletion action set to Delete, badge 4 the suspension action set to Suspend, and badge 5 the Save button.

Give users access in OneLogin

  1. Open Users, select a user, and add the wxrks app on the Applications tab. Alternatively, assign the app to a OneLogin role so every user with that role gets access.

  2. OneLogin provisions the user to wxrks. Check the app's Users tab for the provisioning status of each user.

Map OneLogin roles to wxrks roles

wxrks assigns roles from the roles value the IdP sends, matched against Role Mapping in wxrks.

  1. In the app's Parameters tab, click + to add a parameter. In Field name, enter wxrks_role, select Include in User Provisioning, and click Save. In the next dialog, leave Value as - No default - and click Save. Leave the built-in Groups parameter alone; wxrks doesn't support SCIM groups.

OneLogin Parameters tab with the New Field dialog open: badge 1 marks the Field name set to wxrks_role, and badge 2 the Include in User Provisioning flag, checked.

  1. On the Configuration tab, add this line to the SCIM JSON Template (for example, after the emails block) and click Save: "roles": [{"value": "{$parameters.wxrks_role}", "primary": true}],

  2. On the Rules tab, click Add Rule and name it, for example, "wxrks role: pm". Under Conditions, choose which users get this role (for example, a OneLogin role). Under Actions, choose Set wxrks_role in wxrks, select - Macro -, enter the value (for example pm), and click Save. Add one rule per value.

  3. For users who already have the app, apply the rules with More Actions > Reapply entitlement mappings.

  4. In wxrks, add a Role Mapping row for each value (for example pm → Project Manager, vendor → Vendor), click Save SCIM Settings, and click OK. The value must match the rule exactly, including case.

ℹ️ Note: A user created without a role value gets no role in wxrks. Assign one in People > Users until the mapping is in place.

Check that provisioning works

Give one test user access, then return to the SCIM Provisioning card in wxrks. Last user created at should show the current time, and the user should appear in People > Users in the Default Organizational Unit, with the mapped role. Then remove the test user's access and confirm their wxrks Status shows Disabled.

Use one OneLogin application for both SSO and SCIM

You can, and it's recommended: the SCIM Provisioner with SAML app also carries the SAML settings for login, so one app keeps access and accounts in sync. This guide covers provisioning only. For the SSO setup itself, see wxrks Single Sign-On (SSO).

Troubleshooting

API Connection won't enable. Check that the Base URL was pasted in full and that the token is the latest one generated.

The user wasn't created: "Email already exists". The email already belongs to a wxrks user, possibly in another account.

The user was created with no role. The rule doesn't apply to that user, or its value has no matching Role Mapping row in wxrks. For users who already had the app when you added the rule, run More Actions > Reapply entitlement mappings.

The user was created with no name. The template sent only one of the given and family names and no display name. Send both names.

Related articles

Related Articles
Did this answer your question?