Set Up SCIM

Automatically synchronize your awork users through an Identity Provider and manage user information centrally.

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 your Identity Provider as a central information source and automatically create, update, and deactivate users in awork from there.

Key Benefits and Use Cases

Using SCIM with awork brings many advantages:

• Simple user management: You don't have to worry about importing users. 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 synchronize preferred language, time zone, 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 mechanisms 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

Changes you make manually to synchronized users in awork won't be sent back to the Identity Provider and may be overwritten during the next synchronization.

Users are matched via userName

awork uses the SCIM attribute userName as the unique matching key. The value of userName must match the email address of the user's awork account.

externalId is not used for matching.

If userName differs from the user's existing awork account email address, the existing account won't be matched. Instead, an additional awork account may be created.

Example for Microsoft Entra ID:

• Use userPrincipalName for userName if userPrincipalName matches the email address of the awork account.

• If userPrincipalName doesn't match the awork email address, use mail or another attribute that contains the correct email address.

For other Identity Providers:

Map the source attribute containing the awork account email address to the SCIM attribute userName.

The Identity Provider is the authoritative source

The Identity Provider is authoritative for synchronized attributes. Non-empty values transmitted via SCIM will overwrite the corresponding values in awork during synchronization.

Empty values generally don't delete simple profile fields.

What data gets synchronized?

Beyond these, awork supports additional SCIM attributes and extensions for email addresses, phone numbers, addresses, teams, roles, and absence regions.

Email addresses, phone numbers, and addresses are synchronized as complete sets

Email addresses, phone numbers, and addresses are synchronized as complete sets.

This means entries manually maintained in awork will be removed if the Identity Provider doesn't provide them during the next synchronization.

Plan your mapping so that all entries you want to keep are provided by the Identity Provider.

Teams, roles, and SCIM groups are different concepts

awork teams and permission roles are different concepts:

• Teams are assigned via the custom teams extension as a comma-separated list of awork team names.

• A permission role can be assigned via the custom userRole extension.

• Where supported, SCIM groups represent awork permission roles, not awork teams.

• Each user can only have one permission role.

• Removing a user from a SCIM group doesn't remove or reduce their awork role. Instead, assign a different role or deactivate the user.

• Teams and roles must already exist in awork. SCIM doesn't create them automatically.

Names must match exactly

The values in teams, userRole, and absenceRegion must match exactly with the names already existing in awork.

Unknown team names cause provisioning to fail. These resources aren't created automatically.

Name matching is case-sensitive.

The following restrictions also apply:

• Guest roles cannot be assigned via SCIM.

• Archived roles cannot be assigned.

• The last administrator cannot be deactivated.

• A role cannot simply be removed.

• An absence region can be changed via the extension but cannot be removed.

Deactivation and reactivation

SCIM never permanently deletes an awork user.

A SCIM delete request or active=false deactivates the user. Their tasks, time entries, comments, and other data are retained.

If the Identity Provider later sends active=true, awork reactivates the existing account and sends the user an activation email.

Email addresses can be updated via SCIM

SCIM can update account information after the user has accepted the invitation to the workspace.

Users created via SCIM are automatically activated.

Changing an email address fails if the new address is already assigned to another awork account.

Licenses and automatic seat booking

A corresponding awork license is needed for each activated user.

If no license is available, provisioning will fail unless automatic SCIM seat booking is enabled.

When automatic SCIM user booking is enabled, awork automatically books the required seat. The associated invoice is created approximately 30 minutes later.

You can find this setting in your workspace under:

Settings → Workspace → Workspace Settings → Allow Automatic User Bookings via SCIM

External Users

awork Connect users are excluded from SCIM and remain managed through their own workspace.

This is different from classic guest users within a workspace. They can be affected by the workspace's login restrictions.

Check these users before enforcing SSO-only login and, if possible, migrate them to awork Connect users.

Prerequisites

SCIM provisioning with awork requires:

• an active Enterprise subscription

• a configured SSO integration via OpenID Connect

For OneLogin, awork provides a preconfigured app that integrates SCIM and SSO (OpenID Connect) in a single app.

You must also have sufficient unused awork licenses available unless automatic SCIM user booking is enabled.

What happens with existing users?

When you enable SCIM in your Identity Provider, existing users are matched against accounts in awork based on their userName value.

For an existing awork account to be recognized, userName must exactly match the user's account email.

• Existing users with matching userName are updated.
• Users that don't yet exist in awork are imported.
• Other users in awork who are not part of the SCIM synchronization scope are not changed.

SCIM can also be used for only some of the users. Users outside the synchronization scope remain unaffected.

Set Up SCIM for awork

Setup consists of three steps:

1. Prepare awork for SCIM

2. Set up SCIM in your Identity Provider

3. Configure the mapping

Prepare awork for SCIM

1. Log in to your awork workspace.

2. Set up SSO for your workspace if you haven't already.

3. Go to Settings (gear icon in the bottom left of the main menu) → Integrations.

4. Open the Integration Library.

5. In the SCIM section, select the provider you want to connect.

6. If your provider isn't listed, use the generic SCIM integration.

7. Confirm and set up the integration.

8. After setup, a Bearer Token is displayed. Copy it and store it securely. You'll need it to configure your Identity Provider.

9. Next, you'll see the SCIM integration in the integration list and a client application named API Access.

The client application is used to authenticate the SCIM client. A new Bearer Token can be generated through it if needed.

Set Up SCIM in Your Identity Provider

Okta

1. In Okta, go to Applications → Applications.

2. Click Browse App Catalog.

3. Search for SCIM 2.0.

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

5. Click Add Integration.

6. Give the app a label, for example awork SCIM integration, and click Next.

7. Skip the Sign-on settings.

8. For Credential Details, select Email.

9. Click Done.

10. Open the Provisioning tab and click Configure API Integration.

11. Enable Enable API Integration.

12. Enter the following URL as SCIM Base URL:

https://app.awork.com/api/v1/scim

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

14. Save the configuration.

User Mapping in Okta

Map the user fields so that userName contains the email address of the awork account.

For example:

You can add additional attributes according to the supported mapping.

Make sure the value used for userName matches the email address of the awork account.

OneLogin

For OneLogin, awork provides a preconfigured awork.com app that contains practical default values and can also be used for SSO. This allows you to set up both SCIM and SSO with a single app.

1. In the OneLogin admin area, open Applications → Applications.

2. Click Add App.

3. Search for awork.

4. Select the awork.com app.

5. Save the app.

6. Open the Configuration tab.

General Configuration

In the Login URL field, you can use either

https://app.awork.com/login

or preferably the login URL of your workspace subdomain, for example:

https://your-subdomain.awork.com/login

In the awork.com subdomain field, enter the part of your workspace URL before .awork.com.

Example:

https://precious-asteroid.awork.com

→ precious-asteroid

Next, enable the API in the API Status section.

Add the token you received from the SCIM integration in awork under SCIM Bearer Token.

SCIM JSON Template

With the SCIM JSON Template, you determine what information OneLogin sends to awork.

A minimal configuration might look 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"
    }
  ]
}

You can add additional user fields via mappings and additional parameters.

Roles in OneLogin

1. Open the Provisioning tab.

2. Enable provisioning.

3. Under Entitlements, you can use Refresh to fetch the available awork roles.

4. The guest role is not displayed here because it can only be used for external users.

5. Use Rules to assign users a permission role.

6. A user can only ever have one awork permission role.

If you map multiple roles in OneLogin, make sure a person isn't assigned to multiple awork roles at the same time.

Accept: application/scim+json

Microsoft Entra ID

1. Create an Enterprise Application

1. Open Microsoft Entra ID.

2. Go to Enterprise Applications.

3. Create a new application.

4. Select Create your own application.

5. Give it a name like awork SCIM.

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

7. Click Create.

8. Open the newly created application.

9. Go to the Provisioning tab.

10. Click Edit provisioning.

11. Set the Provisioning Mode to Automatic.

2. Configure Admin Credentials

Under Admin Credentials, enter the following:

Tenant URL

https://app.awork.com/api/v1/scim

Secret Token

Use the Bearer Token from your awork SCIM integration.

Then test the connection and save the configuration.

3. Disable Groups

Group provisioning in Entra ID should be disabled for awork.

Instead, use:

• the userRole extension to manage permission roles

• the teams extension to manage teams

This restriction applies specifically to the Entra configuration.

4. Configure User Mappings

In Target Object Actions, set at least:

• Create

• Update

• Delete

Delete unnecessary standard mappings so only the desired attributes are synchronized.

Recommended Standard Mappings

Important for userName: Only use userPrincipalName as the source for userName if userPrincipalName matches the email address of the awork account.

If these values differ, use mail or another Entra attribute that contains the correct awork account email.

Example:

• userPrincipalName: max.mustermann@company.de

• awork account email: max.mustermann@firm.de

In this case, userPrincipalName cannot be used for userName. Instead, you must map an attribute containing max.mustermann@firm.de.

5. Configure awork Extension Attributes

If you want to synchronize teams, roles, or absence regions, you must use the awork SCIM user extension.

To do this, enable Show advanced options and open Edit attribute list for customappsso.

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

Save the attributes and return to user mappings.

For each attribute you want to use:

1. Add a new mapping.

2. Select the corresponding Entra attribute as the Source Attribute.

3. Select the appropriate awork extension attribute as the Target.

4. Save the mapping.

The simplest approach is to store the values for teams, roles, and absence regions in a separate text field of the Entra user.

6. Manage Teams, Roles, and Absence Regions in Entra

Teams

The attribute

urn:ietf:params:scim:schemas:extension:awork.com:2.0:User:teams

expects a comma-separated list of awork team names.

Example:

Marketing, Sales, Product

The team names must already exist in awork and match exactly.

Permission Roles

The attribute

urn:ietf:params:scim:schemas:extension:awork.com:2.0:User:userRole

expects the name of an existing awork permission role.

A user can have only one permission role.

Absence Region

The attribute

urn:ietf:params:scim:schemas:extension:awork.com:2.0:User:absenceRegion

expects the name of an existing absence region.

An absence region can be changed via SCIM but cannot be removed.

7. Provisioning Settings in Entra

Under Settings, you can enable Prevent accidental deletion.

This setting can help prevent accidental deactivation of many users at once if there's a misconfiguration. Choose a threshold that fits your user count and typical group size.

Also enable: Sync only assigned users and groups

Then:

1. Set the Provisioning Status to On.

2. Save the configuration.

3. Test provisioning first for a single user.

8. Test Provisioning

Use the Provision on demand feature in Entra.

1. Select a single test user.

2. Start Provision.

3. Check the validation results.

4. Then verify the user in awork.

Check at least:

• Email address

• First name

• Last name

• Position

• Language

• Time zone

• Permission role

• Teams

• Absence region

• Activation status

Only when the test is successful should you enable provisioning for the full user base.

9. Assign Users and Groups

Next, add the users and groups that should use the Enterprise Application.

New users require an awork license. Make sure you have sufficient licenses available or automatic SCIM user booking is enabled.

Under Provisioning → Users and Groups, you can define the synchronization scope.

The provisioning used by Entra will then automatically synchronize changes.

Mapping Reference

The following attributes are supported by awork:

Migration Checklist

Before you enable SCIM for many users, we recommend the following checks:

1. Export or compare the user lists from awork and your Identity Provider.

2. Make sure the chosen source for userName exactly matches the awork account email for every user.

3. Fix any discrepancies before enabling provisioning.

4. Create all required roles, teams, and absence regions in awork first.

5. Test provisioning first with a user who is not an administrator.

6. Check email address, profile, role, teams, and activation status.

7. Test deactivation and subsequent reactivation.

8. Expand the assignment scope in your Identity Provider only after successful testing.

9. Keep at least one awork administrator active throughout the rollout.

Troubleshooting

If SCIM synchronization doesn't work as expected, first check the provisioning or synchronization logs of your Identity Provider.

Pay special attention to errors in:

• userName

• unknown roles or teams

• unavailable licenses

• invalid SCIM extension attributes

• multiple assigned roles

• deactivation of an administrator

If an error persists, send the awork support team the relevant error message and, if available, the Trace ID of the failed synchronization operation.

FAQ

Can I create user roles via SCIM?

No. Via SCIM, you can assign existing awork permission roles to users. Roles themselves must be created in awork first.

Can I create teams via SCIM?

No. Teams must already exist in awork. SCIM assigns users to existing teams.

Can email addresses be updated via SCIM?

Yes. SCIM can update the account email and additional contact email addresses. The account email is controlled via userName. For an existing account to be correctly recognized, userName must first contain its current awork account email. Changing an email address fails if the new address is already assigned to another awork account.

Is externalId used for user matching?

No. awork uses userName as the unique matching key. The value must match the user's account email.

What happens if I delete a user via SCIM?

A SCIM delete doesn't permanently delete the user. The user is deactivated. Tasks, time entries, comments, and other data are retained.

What happens with active=false?

The user is deactivated. Their data is retained.

What happens with active=true?

awork reactivates the existing account and sends the user an activation email.

Can I manually edit a user in awork?

Yes, you can make changes manually. However, for synchronized attributes, these changes may be overwritten by Identity Provider values during the next synchronization.

What happens with manually maintained email addresses, phone numbers, and addresses?

These attributes are synchronized as complete sets. An entry that the Identity Provider doesn't send may be removed from awork during the next synchronization.

Can guest roles be assigned via SCIM?

No. The guest role cannot be assigned via SCIM.

Can I remove a user's permission role?

No. A permission role cannot simply be removed. Instead, assign a different role or deactivate the user.

Can the last administrator be deactivated?

No. There must always be at least one active administrator.

Can an absence region be removed?

No. An absence region can be changed via SCIM but cannot be removed.

What happens if a team or role is renamed in awork?

The values in your Identity Provider must continue to match exactly the names in awork. Therefore, after renaming, update the corresponding values in your Identity Provider.

Can awork Connect users be managed via SCIM?

No. awork Connect users are excluded from SCIM and are managed through their own workspace.