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:

  1. Preparing awork for SCIM

  2. Setting up awork in your identity provider

  3. Configuring the mapping

1. Preparing awork for SCIM

This section will guide you through the setup steps in awork.

  1. Login into your awork workspace

  2. Setup SSO for your workspace (if not done already)

  3. Go to the Menu → Settings → Integrations

  4. Click Open Integrations Library to open the library

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

  6. Confirm and set up the integration.

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

  8. 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)

  1. Go to the Menu → Applications → Applications

  2. Click on Browse App Catalogue

  3. Search for SCIM 2.0

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

  5. Click on Add Integration

  6. Set an application label, like awork SCIM integration and click on Next

  7. Skip the Sign-on methods (as we don’t support SAML for SSO)

  8. In the Credentials Details select Email in the dropdown

  9. Click on Done

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

  11. Check Enable API Integration

  12. Enter https://app.awork.io/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 on Save

OneLogin

  1. Go to your OneLogin administration area and open Applications -> Applications

  2. Click on "Add App" in the top right corner

  3. Search for awork in the search field

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

  5. On the left, open the Configuration tab

    1. In the field Login Url you can put either "https://app.awork.io/login" or the link directly to your subdomain, so "https://your-subdomain.awork.io/login".

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

    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.

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

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

  8. Finalise your configuration by clicking on the Save button on the top right corner.

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

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

  11. You can check your provisioning history under Users -> Provisioning

  12. You can also find all events of the awork app under Activity -> Events

Azure AD

(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:

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.

Did this answer your question?