Setting Up SCIM

SCIM (System for Cross-domain Identity Management) simplifies user management. It lets you synchronize users between different applications using a standard protocol. You can use a central information source to manage all your users. Users can be imported from your identity provider into awork or deactivated from awork. Changes to user information like name, timezone, or user role are automatically applied in awork.

Key Benefits and Use Cases

Using SCIM with awork brings many advantages:

• Simple user management: You don't have to worry about importing users manually. When you set up SCIM, you choose which information should be synchronized. The minimal setup includes first name, last name, and email. In addition to this information, you can also sync your preferred language, timezone, awork user roles, awork teams, absence region, and more.

• SSO integration: SCIM works best with Single Sign-On (SSO). Users only need to log in once and can use 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 SCIM Works

If you manually change information in awork for a user synchronized via SCIM, those changes won't be synced back and could be overwritten as soon as the next update from the identity provider occurs.

To use SCIM synchronization, you need to create an app in your identity provider. There, you can configure which fields should be synchronized. You also control which users should be synchronized by adding user groups or individual users to the SCIM app.

Supported Features

• Create user
• Update user
• Deactivate user
• awork user role assignments
• 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

What Happens to Existing Users in awork?

Once you activate SCIM in your identity provider, existing awork users are retrieved and matched with the existing users in your SCIM app.

• Existing users who match by email are updated in awork.
• Users who don't yet exist are imported.
• All other users in awork are not updated.

When importing new users into awork, they don't receive an invitation to awork. You need to send the new users the link to your awork workspace so they can log in directly with SSO. Make sure you have enough unused user licenses in awork so the users can be activated.

If a user is reactivated by an admin, that person receives an email notifying them of the reactivation.

Setting Up SCIM for awork

Setting up SCIM involves three steps:

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

1. Prepare awork for SCIM

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.
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 in Your Identity Provider

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, for example awork SCIM integration, and click Next

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

8. Select Email from the dropdown in Credentials Details

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

For OneLogin, awork offers a pre-configured awork app that includes useful default values and can also be used as an SSO app. So you only need one app for both SSO and SCIM.

1. Go to the OneLogin admin 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 customize this configuration for 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 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 that 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 define which information from OneLogin should be synchronized with awork. The default configuration only synchronizes 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 extend 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 should be required before certain actions. We recommend enabling these options only for initial setup/testing.
16. In the Entitlements section, click Refresh to retrieve the user roles from awork. Note: The Guest role is not displayed here because it's only 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.
18. Click Add Rule to add a new rule.
19. Enter a name and add a condition for your rule, for example "user is in group Admin".
20. Now you can add actions, such as setting the group in awork. It's important that you've done the Entitlements Refresh beforehand to retrieve all user roles. Also, select From Existing, since 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, since 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 final 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 that should be added to the app.
27. For individual assignments, go to User Details and the Applications 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.

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, for example 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 that the secret is correct

13. Save the configuration. After that, two more sections will 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
       ​

    

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

16. 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 attributes are:

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

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

    3. mail > emails[type eq "work"].value

    4. preferredLanguage > preferredLanguage

    5. givenName > name.givenName

    6. surname > name.familyName

    7. Optionally, you can currently also map: jobTitle > userType (displayed as position in awork)

17. If you want to synchronize absence regions, user roles, and/or awork teams, you need to configure the awork SCIM user extension: Enable: "Show advanced options"

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

    • urn:ietf:params:scim:schemas:extension:awork.com:2.0:User:teams
    • urn:ietf:params:scim:schemas:extension:awork.com:2.0:User:absenceRegion
    • urn:ietf:params:scim:schemas:extension:awork.com:2.0:User:userRole
      ​

    

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

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

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

21. Save the user mappings

22. 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 number of users and typical group sizes.
    2. Enable Sync only assigned users and groups

23. Set the Provisioning status to On and save

24. Test provisioning for a single user

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

26. Select a single user by email

27. Click Provision

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

    

29. Add the groups/users that should use the app. Each new user requires an additional license - make sure you have enough awork licenses booked.

30. 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.

31. 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 that are not included in the mapping will not be overwritten in awork.
    ​

    

awork User Extension Attributes - Examples

Absence Regions

Absence region must be a string field that corresponds to the name of the absence region configured in awork.

User Roles

The global user role for workspace-wide permissions can be updated via the userRole extension.

• The name of the user role must match the configured name in awork.
• 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 you want to control what default permission a newly invited user should have.

Troubleshooting Entra ID SCIM Sync

If SCIM synchronization isn't working as expected, you can go to Enterprise App Provisioning Overview and click View provisioning logs. There you'll find information about synchronized users and their properties. If there are problems, the status will be set to Failure. Click the entry, go to Troubleshooting & Recommendations, and copy the error message. Then contact our support and send us 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.

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) that contains the name of the user role (preferred)
• Using the SCIM /Groups feature: First, the available user roles must be synchronized. This is usually done manually by retrieving the available groups and mapping them 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 restriction 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 re-synchronize 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 for login and SSO is updated via the userName attribute.

Limitations:

• If the user is in multiple workspaces, the account email cannot be changed. The user must update their email manually in the profile settings.
• If the email is already 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 who is connected to 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 this time.

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, since it's done based on the ID of the user role and not the display name.

What can I do if my SCIM integration isn't working as expected?

Check the users who can't be provisioned and look at their respective 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 that the API Access element (entry in the list below the integrations) is present. Otherwise, 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, since user creation automatically assigns the user role with the fewest permissions, which is not the guest role. If the user already exists in awork, the role will not be changed via SCIM integration unless this is explicitly configured via the SCIM Groups feature. Existing guest users can be synchronized via SCIM integration, but the SCIM Groups feature does not support assigning guest roles.