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.

Supported features

Create users
Update users
Deactivate users
Get awork user roles via /Groups feature
Update awork user role assignments via /Groups feature
Update awork team assignments via SCIM /User schema extension

Requirements

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, Okta and Azure AD we provide additional information that walk you through the setup flow. Jump to the section of your provider for the next steps.

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!

Okta

(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.com/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

OneLogin

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
1. 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
1. In the field Login Url you can put either "https://app.awork.com/login" or the link directly to your subdomain, so "https://your-subdomain.awork.com/login" (preferred).
2. In the field awork.com subdomain you need to put the link to your workspace before the awork.com, so for https://precious-asteroid.awork.com, it needs to be precious-asteroid
3. In the section API Status, you can simply click on Enable
4. In the section SCIM Bearer Token you can now paste the token you got when creating the SCIM integration in awork
5. 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:
```
{
  "schemas": [
   "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "userName": "{$parameters.scimusername}",
  "name": {
    "givenName": "{$parameters.firstname}",
    "familyName": "{$parameters.lastname}"
  },
  "emails": [
    {
      "value": "{$parameters.email}",
      "primary": true,
      "type": "work"
    }
  ]
}
```
6. 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
1. Under Workflow, you can enable the provisioning.
2. 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.
3. 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
1. Click on Add Rule to add a new rule
2. Enter a name and add a condition for your rule, f.e. user is in group Admin
3. 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.
4. Click on Save
5. 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).
1. For Policy based access to the app go to the Access tab on the left
  1. Select the roles that should be added to the app.
2. 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

Azure AD

Go to Azure Active Directory
Go to Enterprise Applications
1. Create a new Application
2. In the Azure AD Gallery, click on "Create your own Application"
3. Set a name, like awork SCIM
4. Check "Integrate any other application you didn't find in the gallery"
5. Click on "Create"
Go to the newly created app
1. Go to the Provisioning Tab
2. Edit the provisioning
3. Set the Provisioning Mode to "Automatic"
4. Set the admin credentials
  1. Set the Tenant URL to: https://app.awork.com/api/v1/scim
  2. Set the Secret token to the token, you get when creating the SCIM integration in awork
  3. Test the connection, to see if the secret is correct
5. Save the configuration. After that two other sections will appear
6. Edit the mappings
  1. Click On the Groups. Disable this feature and save. Currently, awork does not support Groups with Azure AD.
  2. Go back to the mappings and edit the Users mappings
    Set Target Object Actions to all: Create, Update, Delete
    The default list of mappings already has the correct mapping for the required fields. The rest of the mappings need to be deleted, so that the Sync works as expected. The required mappings from Azure Active Directory Mapping to customappsso Attribute are:
    userPrincipalName -> userName (the userPrincipalName needs to be set to the email of the user)
    Switch([IsSoftDeleted], , "False", "True", "True", "False") -> active
    mail -> emails[type eq "work"].value
    preferredLanguage → preferredLanguage
    givenName → name.givenName
    surname → name.familyName
    Optionally you can currently also map:
    jobTitle → userType (This is shown as the Position in awork)
7. Save the user mappings
8. Edit the Settings
  1. Enable "Prevent accidental deletion" if you wish. This prevents the deletion of many users at the same time if you f.e. removed the wrong group. We recommend a number like 50, depending on your number of awork users and typical group sizes.
  2. Check "Sync only assigned users and groups"
9. Turn the provisioning status to On and save
Test provisioning for a single user
1. Go to the Provisioning Tab of the Enterprise Application and click on "Provision on demand
2. Select a single user via email
3. Click on Provision
4. Check results of the validation. Your user fields should now be updated in awork.
Add the groups/users that should use the app. For every new user added, an additional license is needed, so please make sure to have enough awork licenses booked.
1. Go to the Provisioning Tab. Click on users and groups and add the groups and individual users you want to add to awork. Group assignments are only available with a Azure AD Premium P2 subscription.
2. Go to the provisioning overview and start the Provisioning Job. This job runs all 40 minutes and sync all changes between Azure AD and awork. Fields that are not included in the mapping will not be overridden in awork.

Troubleshooting Azure AD SCIM Sync

In case the SCIM sync is not working as expected, you can go to the Enterprise App Provisioning Overview and click on View provisioning logs. In the provisioning logs you can find informations on the synced users and properties. In case something something failed, the status of the entry will be set to Failure. Please click on that entry and go to the Troubleshooting & Recommendations page and copy the error message. Please then contact our support and pass the error message, so we can take a closer look.

For more infos on the Azure side of the SCIM integration, you can find more infos in the Azure docs here: How Application Provisioning works in Azure Active Directory

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:

SCIM field	awork field		Note
SCIM user	awork user	awork account
id	id
userName	userContactInfos → type=email && subtype=work (primary user email)	Email	this email is used to match awork user/account and users from your SCIM client
name → familyName	LastName	LastName
name → givenName	FirstName	FirstName
title	Title
userType	position
preferredLanguage	language		currently only supports de-DE or en-GB (other en- and de- prefixes will get converted to the supported default value)
timezone		timezone	The IANA timezone info (https://www.iana.org/time-zones)
active	isDeactivated
SCIM User multi-value attributes
email	userContactInfos → type=email		the first work email is set to the primary email of the user
phoneNumbers	userContactInfos → type=phone
addresses	userContactInfos → type=address
urn:ietf:params:scim:schemas:extension:Teams:2.0:User
teams	userInTeams		multi value string array. Matching happens by name.

SCIM Group	awork User role
id	id
displayName	name
members	userInRoles

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.

FAQ

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.

Can guest users be synced via SCIM?

Guest users cannot be created via the SCIM integration, because the user role with the least permissions that is not the guest role is automatically assigned on user creation. If the user already exists in awork, the role does not get changed via the SCIM integration, unless explicitly configured via the SCIM Groups feature. Existing guest users can be synced via the SCIM integration, but the SCIM Groups feature does not support assigning guest roles.

awork in larger teams

Release history

Set up calendar integrations

Set up Single Sign-On (SSO)

Microsoft Calendar integration