SCIM is an enterprise feature and is currently in a pilot state. Contact us for more information.
What is SCIM?
System for Cross-domain Identity Management, short SCIM, makes user management easier by allowing you to move users from and to different apps using a standard protocol. This way, you can have one application of truth where you manage your users, like Azure AD, OneLogin or Okta, and import users to or deactivate users from awork. Changes to the user information, like name, timezone or user role, are then automatically imported to awork.
This integration supports the current SCIM 2.0 version.
Why should I use SCIM with awork?
Using SCIM with awork has many advantages. First, you don’t need to worry about importing users to awork. When configuring SCIM, you choose which information should be synced to awork. The minimal setup only includes the first name, last name and email. On top of this information you can also add your preferred language, timezone, awork user roles, awork teams and more.
Second, SCIM works best with using single-sign on (SSO). This way, employees only need to worry about one login to all their apps, don’t need to setup potentially insecure passwords and can use additional safety mechanisms like multi-factor authentication (MFA). If you only have internal users in your workspace that are managed by your identity provider, you can only allow SSO and deactivate all other login options. If you also have external users in your awork workspace, you still need to allow login via password.
How does the SCIM sync work?
The SCIM sync is a one-way flow. Information only gets pushed into awork, not back from awork into your identity provider. Usually, you configure an app in your identity provider. In this app, you setup a configuration that decides what fields get synced and when. Consequentially, if you change information in awork for a user that is synced via SCIM, these changes won’t get synced back. These manual changes will get overridden in awork once the user is updated the next time from your identity provider.
You also have control over which users should be synced to awork. This is done by adding user groups or individual users to the SCIM app in your identity provider.
Get awork user roles via /Groups feature
Update awork user role assignments via /Groups feature
Update awork team assignments via SCIM /User schema extension
SCIM provisioning with awork requires:
An active enterprise subscription
A configured SSO (OpenID Connect) integration
Note: For OneLogin we have a preconfigured app that integrates SCIM and SSO (OpenID Connect) into a single app. Apps for Okta and Azure AD are coming soon!
What happens to existing users in awork?
Once you activate SCIM in your identity provider, usually the existing users are fetched from awork. Then they get matched to your existing users in your SCIM app via their email.
Note: We use the account email of the user that can be changed only by the user via his/her profile, not the primary work email which can be configured in the user details.
Existing users that are matched will be updated in awork, users which don’t exist yet in awork will be imported, and existing users will not be updated. Therefore, you can only use SCIM for a subset of users and existing external users will not be affected.
When importing new users to awork, they won’t receive an invitation to awork. You need to send them the link to your workspace once you are finished with your setup, so the users can login with SSO. You also need to make sure that you have enough unused user licenses in awork so the user can be activated.
Note: Currently there is no flag in awork that indicates which user is synced via SCIM, so you need to check the sync status in your identity provider.
Set up SCIM for awork
The setup of SCIM includes three steps:
Preparing awork for SCIM
Setting up awork in your identity provider
Configuring the mapping
1. Preparing awork for SCIM
This section will guide you through the setup steps in awork.
Login into your awork workspace
Setup SSO for your workspace (if not done already)
Go to the Menu → Settings → Integrations
Click Open Integrations Library to open the library
In the SCIM section, select the provider you want to connect.
If you don’t find your provider in the list, you can choose the generic SCIM integration. If you need help with this setup, please feel free to contact our support.
Confirm and set up the integration.
A popup will appear with a Bearer token. Copy this to your clip-board. You'll will need it to grant your identity provider access to awork.
You should now see the new SCIM integration in the integrations list and a new client application in the list below named API access.
The client application is used to authenticate the SCIM client and can be used to regenerate the Bearer token, if you need to copy it again. Please do not edit or delete this client application!
2. Setting up awork in your identity provider
For OneLogin we provide a predefined awork app which includes convenient defaults and that can also be used as a SSO app, so you only need a single app for SSO and SCIM. Apps for Okta and Azure AD are coming soon!
(awork app coming soon to Okta app store)
Go to the Menu → Applications → Applications
Click on Browse App Catalogue
Search for SCIM 2.0
Select SCIM 2.0 Test App (OAuth Bearer Token)
Click on Add Integration
Set an application label, like awork SCIM integration and click on Next
Skip the Sign-on methods (as we don’t support SAML for SSO)
In the Credentials Details select Email in the dropdown
Click on Done
Go to the Provisioning tab and click on Configure API Integration
Check Enable API Integration
Enter https://app.awork.io/api/v1/scim in the SCIM 2.0 Base Url field
Copy the client secret from your awork SCIM integration into the OAuth Bearer Token field
Click on Save
Go to your OneLogin administration area and open Applications -> Applications
Click on "Add App" in the top right corner
Search for awork in the search field
Click on the awork.io app and hit Click in the top right corner
After the save, you can see some basic configuration that we already set up for you. You can edit this configuration to fit your personal use-case.
On the left, open the Configuration tab
In the field awork.io subdomain you need to put the link to your workspace before the awork.io, so for https://precious-asteroid.awork.io, it needs to be precious-asteroid
In the section API Status, you can simply click on Enable
In the section SCIM Bearer Token you can now paste the token you got when creating the SCIM integration in awork
In the field SCIM JSON Template you can define which information from OneLogin gets synced to awork. The default config only syncs the email, first and last name and looks like this:
You can extend this config to map additional user fields. You can find the available fields in the Mappings section. For every field you need to create a parameter in the Parameters tab on the left and map the value to some value from OneLogin. Contact us for more information.
Next, go to the Provisioning tab on the left
Under Workflow, you can enable the provisioning.
You can also decide, if you want to require admin approval before specific actions are done. We recommend only leaving these checked for initial setup/testing purposes.
In the Entitlements section click on Refresh to fetch the user roles from awork. Note: The guest roles does not get returned here as this one can only be used for external users.
If you want to configure default user roles for your users in awork, you can go to the Rules tab on the left
Click on Add Rule to add a new rule
Enter a name and add a condition for your rule, f.e. user is in group Admin
Now you can add actions, like set the group in awork. It's important that you did the entitlements refresh before to get all the user roles. You also need to select "From Existing" because you can only create/update user roles directly in awork. After selecting a role, do not forget to click on the Add button, else the group is not added. You should also only add a single group, as in awork you can only be in one user role at a time.
Click on Save
Repeat these steps for all your awork user roles.
Finalise your configuration by clicking on the Save button on the top right corner.
Attention: You made all the configurations to finally add users to your app. If you want to test the configuration to make sure all your fields get mapped correctly, we recommend adding a test user to the app, which can be done in the user details under Users -> Users -> select your test user -> Applications
In the last step you can finally add your users to the app. This is either done individually for each user or via policies (recommended).
For Policy based access to the app go to the Access tab on the left
Select the roles that should be added to the app.
For individual user assignments, simply go to the user details and the Application tab. Here you can add a new app by clicking the plus button on the top right
You can check your provisioning history under Users -> Provisioning
You can also find all events of the awork app under Activity -> Events
(description following soon)
3. Configuring the mapping
The awork user fields are mapped to the SCIM user resource. A list of the supported fields can be found here:
userContactInfos → type=email && subtype=work (primary user email)
this email is used to match awork user/account and users from your SCIM client
name → familyName
name → givenName
currently only supports de-DE or en-GB (other en- and de- prefixes will get converted to the supported default value)
The IANA timezone info (https://www.iana.org/time-zones)
SCIM User multi-value attributes
userContactInfos → type=email
the first work email is set to the primary email of the user
userContactInfos → type=phone
userContactInfos → type=address
multi value string array. Matching happens by name.
awork User role
If there are any fields that you would like to sync which aren’t shown in this overview, please let us know.
Note: awork supports team assignments via the external namespace
urn:ietf:params:scim:schemas:extension:Teams:2.0:User as a multi value string field. The team assignments get matched via the name of the team. Therefore, the name of the team in awork and your SCIM client need to match exactly.
Note: awork User roles are mapped to the SCIM /Groups feature for handling permissions. Please note, that an awork user can only have one user role at a time, therefore you need to make sure that you don’t assign more than one role via the group assignments as this limitation is not supported directly by SCIM.
Can I create/update user roles via SCIM?
No, you can only match roles. To create or update permission roles in awork navigate to Menu → Settings → Permissions.
Can I sync profile pictures via SCIM?
This is not supported right now from the providers OneLogin and Okta. We therefore don't offer this functionality yet.
What happens if I change the name of a permission role in awork?
After renaming the permission roles in awork, you need to refresh the groups in your SCIM client to show the correct names. The mappings should not change as this done by the identifier of the user role and not the display name.
What can I do if my SCIM integration is not working as expected?
Check the users that cannot be provisioned and check the corresponding error messages. Send our support team the trace id so we can check it for you. Make sure your client application is set up correctly and also the api access item (item in list below the integrations) is existent. Otherwise delete the integration in awork and try to set it up again.