Setting Up SCIM

What is SCIM?

System for Cross-domain Identity Management, or SCIM for short, simplifies user management by allowing you to synchronize users between different applications using a standard protocol. This way, you can use a single application as your central source of information where you manage all your users. Examples of such identity providers include Microsoft Entra ID (formerly Azure AD), OneLogin, or Okta. From these, you can import users to awork or deactivate users from awork. Changes to user information - like name, timezone, or user role - are then automatically imported into awork.

This integration supports the current version SCIM 2.0.

Why should I use SCIM with awork?

Using SCIM with awork has many advantages. First, you don't have to worry about importing users to awork. When configuring SCIM, you choose which information should be synchronized with awork. The minimum setup includes first name, last name, and email. In addition to this information, you can also synchronize your preferred language, timezone, awork user roles, awork teams, absence region, and more.

Second, SCIM works best with Single Sign-On (SSO). This way, users only need to manage a single login for all their apps, don't set up potentially insecure passwords, and can use additional security features like multi-factor authentication (MFA). If you only have internal users in your workspace who are managed by your identity provider, you can disable all login options except SSO. If you also have external users in your awork workspace, you can still allow password-based login.

How does SCIM synchronization work?

SCIM synchronization only works in one direction - from your identity provider to awork. Information is sent to awork, but not back from awork to your identity provider. So if you manually change information in awork for a user who is synchronized via SCIM, those changes won't be synchronized back and might get overwritten the next time the user is updated from your identity provider.

To use SCIM synchronization, you typically create an app in your identity provider. In the configuration, you can specify which fields should be synchronized.

You also have control over which users should be synchronized with awork. This is done by adding user groups or individual users to the SCIM app in your identity provider.

Supported features

• Create user
• Update user
• Deactivate user
• Assign awork user roles
• Update awork team assignments
• Update awork absence region
• Update awork global permission role

Requirements

SCIM provisioning with awork requires:

• An active Enterprise subscription
• A configured SSO (OpenID Connect) integration

Note: For OneLogin, we have a pre-configured app that integrates SCIM and SSO (OpenID Connect) in a single app.

What happens to existing users in awork?

Once you enable SCIM at your identity provider, awork retrieves the existing users. They are then matched with existing users in your SCIM app using their email address.

☝️ Note: We use the account email of the user, which can only be changed by them through their profile, not the primary work email that can be configured in the user details.

Existing users who match by email are updated in awork, users who don't yet exist in awork are imported, and all other users in awork remain unchanged. This means you can use SCIM for only some of your awork users without affecting others.

When importing new users to awork, they don't receive an invitation to awork. You need to send them the link to your awork workspace once you've finished setting up. Users can then log in directly with SSO. You also need to make sure you have enough unused user licenses in awork for the user to be activated.

If you don't want to do this manually, we've created a workspace setting that allows new user licenses to be booked automatically. The invoice is generated 30 minutes after the first additional user is booked, so if you import multiple users at once, multiple invoices won't be created. You can find this setting in your awork workspace under Settings > General > Workspace Settings with the name Allow automatic user bookings via SCIM

☝️ Note: However, if a user is reactivated by an admin, that person receives an email notifying them about the reactivation.

☝️ Note: Currently, awork doesn't show which user was synchronized via SCIM. However, you can check the synchronization status at your identity provider.

Setting up SCIM for awork

Setting up SCIM involves three steps:

1. Prepare awork for SCIM
2. Set up awork at your identity provider
3. Configure the mapping

1. Prepare awork for SCIM

In this section, you'll be guided through the setup steps in awork.

1. Log in to your awork workspace.
2. Set up SSO for your workspace (if not already done).
3. Go to Settings (gear icon in the bottom left of the main menu) > Integrations.
4. Click Open Integration Library.
5. In the SCIM section, select the provider you want to connect.
   If your provider isn't in the list, you can choose the generic SCIM integration. If you need help with setup, feel free to contact our Support.
6. Confirm and set up the integration.
7. A popup appears with a Bearer Token. Copy this to your clipboard. You'll need it to grant your identity provider access to awork.
8. You should now see the new SCIM integration in the integrations list and a new client application below it 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 don't edit or delete this client application!

2. Set up awork at your identity provider

For OneLogin, Okta, and Microsoft Entra ID (formerly Azure AD), we provide additional information to guide you through the setup. Jump to the section for your provider for the next steps.

For OneLogin, we offer a pre-defined awork app that includes helpful default values and can also be used as an SSO app. So you only need one app for SSO and SCIM.

Okta

1. Go to Menu > Applications > Applications

2. Click Browse App Catalogue

3. Search for SCIM 2.0

4. Select SCIM 2.0 Test App (OAuth Bearer Token)

5. Click Add Integration

6. Enter an app label, e.g., awork SCIM integration, and click Next

7. Skip the sign-on methods (since we don't support SAML for SSO)

8. Under Credentials Details, select Email from the dropdown

9. Click Done

10. Go to the Provisioning tab and click Configure API Integration

11. Enable Enable API Integration

12. Enter https://app.awork.com/api/v1/scim in the SCIM 2.0 Base Url field

13. Copy the Client Secret from your awork SCIM integration into the OAuth Bearer Token field

14. Click Save

OneLogin

1. Go to the OneLogin administration area and open Applications > Applications

2. Click "Add App" in the top right

3. Search for awork in the search field

4. Click the awork.com app and then click in the top right

5. After saving, you'll see a basic configuration that we've already set up for you. You can adjust this configuration to your use case.

6. Open the Configuration tab on the left

7. In the Login Url field, you can enter either "https://app.awork.com/login" or the link to your subdomain directly, for example "https://your-subdomain.awork.com/login" (preferred).

8. In the awork.com subdomain field, you need to enter the link to your workspace before awork.com, so for https://precious-asteroid.awork.com it would be precious-asteroid.

9. In the API Status section, you can simply click Enable.

10. In the SCIM Bearer Token section, you can now paste the token you received from the SCIM integration in awork.

11. In the SCIM JSON Template field, you can specify which information from OneLogin should be synchronized with awork. The default configuration synchronizes only email, first name, 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"
    }
    ]
    }

12. You can expand this configuration to map additional user fields. You can find the available fields in the Mappings section. For each field, you need to create a parameter in the Parameters tab and assign the value from OneLogin. Contact us for more information.

13. Then go to the Provisioning tab on the left

14. Under Workflow, you can enable provisioning.

15. You can also decide whether admin approval is required before certain actions. We recommend enabling these options only for initial setup and testing.

16. In the Entitlements section, click Refresh to retrieve the user roles from awork. Note: The guest role is not displayed here as it can only be used for external users.

17. If you want to set default user roles for your users in awork, go to the Rules tab on the left. Click Add Rule to add a new rule.

18. Click Add Rule to add a new rule.

19. Enter a name and add a condition for your rule, e.g., "user is in group Admin".

20. Now you can add actions, such as setting the group in awork. It's important that you first perform the Entitlements Refresh to retrieve all user roles. Also select "From Existing" because user roles can only be created/updated directly in awork. After selecting a role, don't forget to click Add, otherwise the group won't be added. Only add one group, as an awork user can only have one role at a time.

21. Click Save.

22. Repeat these steps for all your awork user roles.

23. Complete the configuration by clicking Save in the top right.

24. Attention: You've completed all configurations to add users to your app. If you want to test the configuration, we recommend adding a test user to the app (under Users > Users > Select Test User > Applications)

25. In the last step, you can add your users to the app - either individually or via policies (recommended).

26. For policy access to the app, go to the Access tab on the left, select the roles to be added to the app.

27. For individual assignments, go to the user details and the Application tab. Here you can add a new app by clicking the plus icon in the top right.

28. You can find the provisioning history under Users > Provisioning.

29. You can find all events for the awork app under Activity > Events.

Known Issues
If you encounter an error with the description "Invalid Accept Header Value", you can solve the problem by adding the following custom header in your SCIM application setup:

Accept: application/scim+json

Microsoft Entra ID (formerly Azure AD)

1. Go to Microsoft Entra ID

2. Go to Enterprise Applications

3. Create a new application

4. Click "Create your own Application" in the Entra ID Gallery

5. Enter a name, e.g., awork SCIM

6. Select "Integrate any other application you didn't find in the gallery"

7. Click "Create"

8. Go to the newly created app

9. Go to the Provisioning tab

10. Edit the provisioning

11. Set the Provisioning Mode to "Automatic"

12. 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 received from the SCIM integration in awork
    3. Test the connection to verify the secret is correct

13. Save the configuration. Two more sections will then appear

14. Edit the mappings

    1. Click Groups. Disable this feature and save. Currently, awork doesn't support groups with Entra ID.
    2. Go back to the mappings and edit the Users mappings

    1. Set Target Object Actions to all: Create, Update, Delete

    2. The default list of mappings already contains the correct mappings for the required fields. The remaining mappings must be deleted so the synchronization works as expected. The required mappings from Entra ID Mapping to customappsso Attribute are:

    3. userPrincipalName -> userName (userPrincipalName must be set to the user's email)

    4. Switch([IsSoftDeleted], , "False", "True", "True", "False") -> active

    5. mail -> emails[type eq "work"].value

    6. preferredLanguage -> preferredLanguage

    7. givenName -> name.givenName

    8. surname -> name.familyName

    9. Optionally, you can also currently map:

    10. jobTitle -> userType (displayed as a position in awork)

    11. If you want to synchronize absence regions, user roles, and/or awork teams, you must configure the awork SCIM user extension:

    12. Enable: "Show advanced options"

    13. Click Edit attribute list for custommapsso. Add the following fields as strings:

        1. urn:ietf:params:scim:schemas:extension:awork.com:2.0:User:teams
        2. urn:ietf:params:scim:schemas:extension:awork.com:2.0:User:absenceRegion
        3. urn:ietf:params:scim:schemas:extension:awork.com:2.0:User:userRole

    14. Click Save at the top and go back to the mapping

    15. Add a new attribute for each extension you want to use

        1. As the source attribute, we recommend saving the value as a text field on the Azure user as a custom field and selecting it here, e.g., awork user role.
        2. Select the newly added extension field as the target, e.g., urn:ietf:params:scim:schemas:extension:awork.com:2.0:User:absenceRegion
        3. Click Ok to add the new attribute mapping

15. Save the user mappings

16. Edit the settings

    1. Enable "Prevent accidental deletion" if desired. This prevents many users from being deleted at once if, for example, the wrong group was removed. We recommend a number like 50, depending on your user count and typical group sizes.
    2. Enable "Sync only assigned users and groups"

17. Set the Provisioning Status to On and save

18. Test provisioning for a single user

19. Go to the Provisioning tab of the Enterprise Application and click "Provision on demand"

20. Select a single user by email

21. Click Provision

22. Check the validation results. Your user fields should now be updated in awork.

23. Add the groups/users who should use the app. An additional license is needed for each new user - make sure you have enough awork licenses booked.

24. Go to the Provisioning tab. Click Users and Groups and add the desired groups and users. Group assignments are only available with an Entra ID Premium P2 subscription.

25. Go to the Provisioning Overview and start the Provisioning Job. This runs every 40 minutes and synchronizes all changes between Entra ID and awork. Fields not included in the mapping won't be overwritten in awork.

awork User Extension Attributes - Examples

Absence Regions

Absence region must be a string field that matches the name of the absence region configured in awork. Note: The absence region cannot be removed via the SCIM integration, only updated. The name matching is case-sensitive.

User Roles

The global user role for workspace-wide permissions can be updated via the userRole extension. The user role name must match the configured name in awork. Note: The name matching is case-sensitive. The guest role cannot be assigned. A user can only have one role at a time. There must always be at least one admin user. The user role cannot be removed. Set a default value here if needed, if you want to control which default permission a newly invited user should have.

Troubleshooting Entra ID SCIM Sync

If SCIM synchronization is not working as expected, you can go to Enterprise App Provisioning Overview and click View provisioning logs. There you'll find information about the synchronized users and properties. If there are problems, the status will be set to Failure. Click on the entry, go to Troubleshooting & Recommendations, and copy the error message. Then contact our support and send the error message so we can take a closer look.

3. Configure the mapping

The awork user fields are mapped to the SCIM user resource. You can find a list of supported fields here:

If there are fields you want to synchronize that aren't listed here, please let us know.

Note: awork offers its own extension for team assignments, absence regions, and user roles via the schema urn:ietf:params:scim:schemas:extension:awork.com:2.0:User. The mapping is done via the name of the team and absence region, so they must match exactly in awork and your SCIM provider.

Note: awork user roles can be managed in two ways: either via the /Groups feature or the awork user extension.

• The awork user extension: For this, the extension attribute must be mapped to a text field of the user (or another field for SCIM sync) containing the name of the user role (preferred)
• With the SCIM /Groups feature: First, the available user roles must be synchronized. This is usually done manually by retrieving the available groups and mapping the groups based on defined rules. Note that an awork user can only have one user role at a time. So make sure you don't assign more than one role via group assignments, as this limitation is not directly supported by SCIM. If a role is renamed, a new role is added, or an existing role is deleted, you usually need to manually resynchronize the available groups.

FAQ

Can I create/update user roles via SCIM?

No, you can only assign roles. To create or update permission roles in awork, go to Menu > Settings > Permissions.

Can I update email addresses via SCIM?

Yes, updating account emails and user contact emails is supported via SCIM. The account email used for login and SSO is updated via the userName attribute. Limitations:

• If the user is in more than one workspace, we don't allow changes to the account email and the user must manually change their email in the profile settings.
• If the email is already being used by another account, an error is returned. To use the email, the existing account must be deleted. This is done by deleting the user associated with that account.

Can I synchronize profile pictures via SCIM?

This is currently not supported by OneLogin and Okta providers. Therefore, we don't offer this functionality at the moment.

What happens if I change the name of a permission role in awork?

After you rename the permission roles in awork, you need to update the groups in your SCIM client so the correct names are displayed. The assignment shouldn't change because it's based on the user role's ID, not the display name.

What can I do if my SCIM integration is not working as expected?

Check the users who cannot be provisioned and look at the respective error messages. Send the Trace ID to our support team so we can check it for you. Make sure your client application is set up correctly and that the API Access element (entry in the list under integrations) is present. If not, delete the integration in awork and try setting it up again.

Can guest users be synchronized via SCIM?

Guest users cannot be created via the SCIM integration because when a user is created, the user role with the lowest permissions is automatically assigned, which is not the guest role. If the user already exists in awork, the role is not changed via the SCIM integration unless explicitly configured via the SCIM groups feature. Existing guest users can be synchronized via the SCIM integration, but the SCIM groups feature doesn't support assigning guest roles.