SCIM / User Provisioning Setup & Configuration Guide

Lemontaps supports SCIM 2.0 for automated user provisioning and deprovisioning. This allows you to automate tedious manual tasks such as uploading new users, managing their contact information or removing leavers.

With our SCIM 2.0 integration, you can automatically:

• create new users
• update user attributes
• remove users
• add new units
• manage unit memberships
• remove units
• manage user roles

This allows you to automatically create digital business card profiles pre-filled with all relevant contact information and keep this information up to date at all times.

This massively reduces manual workload, as new users are correctly set up on registration. With SCIM enabled, on- and offboarding is entirely automated. This is why many companies use SCIM when possible.

TABLE OF CONTENTS

• General Setup
• Entra ID Setup
• Okta Setup
• How to Test
• After-Setup Checklist
• FAQ

Prerequisites

Only users from verified email domains can be provisioned. Before setting up SCIM, it is therefore required to verify the relevant set of email domains. Read the article about email domain verification for more information.

General Setup

We expose the standard SCIM 2.0 API routes protected via a Bearer auth token.

For configuring SCIM in your Identity Provider, all you need is our SCIM base URL and the Bearer auth token. You can find both by navigating to Team-Settings -> Integrations -> Identity Provider -> SCIM Provisioning. There you will be able to create a configuration showing you both these values.

When SCIM is active on the Lemontaps side, our API accepts incoming SCIM requests. You then need to configure your IdP to start provisioning.

In the sections below, we provide a general overview for the following topics: 

a) SCIM User Attributes 

b) SCIM Group Attributes 

c) Managing User Attributes 

d) User Roles

If you're using Entra ID or Okta, you’ll also find dedicated step-by-step setup guides tailored to each identity provider.

We recommend starting with the general information above, then continuing to the Entra ID Setup Guide or Okta Setup Guide for specific configuration steps.

a) SCIM User Attributes

Overview of the minimum recommended set of attributes:

The default configurations will mostly include more attributes, such as phone numbers, email addresses, physical addresses, position, company, etc.

b) SCIM Group Attributes

Groups will map 1:1 with Lemontaps Units.

SCIM group attributes should generally not be altered manually. The most relevant attribute is displayName which controls the name under which the unit will appear in Lemontaps.

c) Managing User Attributes

You can finetune the user attributes that should be included in the sync so that the provisioned profiles will have the correct profile attributes.

When a user is pushed from the IdP to Lemontaps, the information has to be transferred from the user in the IdP to the user in Lemontaps. The process looks like this: 

1. A mapping on the IdP-side maps user attributes from the IdP-user onto a SCIM user schema (as JSON)
2. This SCIM user schema is then sent to Lemontaps via the SCIM API
3. A second mapping on the Lemontaps-side then maps attributes from the SCIM user schema onto the Lemontaps user

If you want to remove an attribute from the sync, it is therefore enough to remove it from one of the mappings.

If you want to add an attribute to the sync, you must make sure that the attribute is covered in both mappings.

You can read the guide for managing the Lemontaps-side mapping below:
Lemontaps Mapping Guide → 

d) User Roles

Lemontaps supports three different user roles: Employee, Unit Admin, and Admin.

If you want to control roles via SCIM, you can add an attribute lemontapsPermissionLevel to the SCIM user attributes. It accepts either of the two following values: "lemontaps.admin" or "lemontaps.unit_admin". All other values will be interpreted as the Employee role.

If you do not provide this attribute at all, then you must manage user roles from within Lemontaps.

Entra ID Setup

The basic approach to SCIM in Entra ID is as follows:

1. Configure the SCIM base URL and Auth token
2. Customize the attribute mapping
3. Choose to only push users or also have Entra ID groups be mapped onto Lemontaps Units
4. Choose if you want to provision user roles via SCIM (can also be managed via Lemontaps)
5. Assign users to the enterprise app (either directly or via a group)
6. Start provisioning

Setup Guide:
SCIM setup Entra ID → 

Managing user attributes

Navigate to the respective enterprise application, where SCIM is configured, and open the Provisioning settings from the left pane. Go to Attribute Mapping -> Provision Microsoft Entra ID Users. There you will be able to configure the IdP-side mapping under Attribute Mappings. 

In order to add a new attribute to the mapping, you first have to edit the list of available attributes. For this, select Show Advanced Options at the very bottom of the page, and then Edit attribute list for customappsso. Now you can add new attributes of type String. This will be the name of the attribute sent to Lemontaps via the SCIM user schema.

Assigning User Roles

Here you can read our guide on how to assign user roles: Assigning user roles → 

Pushing Groups

Navigate to the respective enterprise application, where SCIM is configured, and open the Provisioning settings from the left plane. Go to Attribute Mapping -> Provision Microsoft Entra ID Groups and select whether you want to enable the provisioning of groups or not. It is enabled by default.
Even if groups are disabled, you can still assign a group to the application to manage access. The users of this group will still be provisioned.

Analyzing Errors

Navigate to the respective enterprise application, where SCIM is configured, and open the Provisioning settings from the left plane. Go to Monitor -> Provisioning Logs.

Okta Setup

The basic approach to SCIM in Okta is as follows:

• Configure the SCIM base URL and Auth token
• Enable provisioning
• Customize the attribute mapping
• Choose to push only users or also have Okta groups be mapped onto Lemontaps Units
• Choose if you want to provision user roles via SCIM (can also be managed via Lemontaps)
• Assign users and/or groups to the app and thereby start the provisioning

Setup Guide: SCIM Setup Okta → 

Managing user attributes

In the Okta application, navigate to the "Provisioning" tab. There you will be able to customize the IdP-side mapping.

Pushing Groups

In the Okta application, navigate to the "Push Groups" tab. There you will be able to assign groups either explicitly or via a rule.

Analyzing Errors

In the Okta Admin navigation, go to Reports -> System Logs.

How to Test

You can test with a few users first to make sure that the provisioning works as expected. You can also use these users to optimize the mapping in order to have the correct contact attributes included in the sync.

After-Setup Checklist

• The SCIM base URL and authentication are correctly configured
• Provisioning has been tested with a few test users
• The IdP-side mapping as well as the Lemontaps-side mapping are customized resulting in only relevant attributes being included in the sync.
• A decision about whether or not to provision Lemontaps Units has been made
• A decision about whether or not to control user roles via SCIM has been made

FAQ

Are profile pictures supported?

Currently, profile pictures are unfortunately not supported.

Does the synchronization happen in real-time?

This depends on the identity provider. E.g. Entra ID has a synchronization interval of 40 minutes. In Okta synchronization will be instant, with only slight delays.

What happens to users that existed before provisioning was enabled?

In Lemontaps, a user always has one of two control states: "manual" or "scim". When the control state is "manual", the user can be manually edited and deleted from within Lemontaps. When a user is provisioned via SCIM (i.e. the user did not exist before), then the control state is "scim" and the user will be deleted via SCIM if they are moved out of the provisioning scope in the identity provider.

When a user is provisioned via SCIM and already exists in Lemontaps, a matching process based on the email address is performed. The user's control state will then change to "scim" and the user will be automatically deleted when moved out of the synchronization scope in the identity provider.

How do I disable provisioning?

You can always stop provisioning in your IdP settings and re-start it when you want.

We recommend that you do not delete the configuration in Lemontaps. Otherwise you will need to re-configure SCIM in your identity provider when you want to re-start provisioning.

Can I generate a new access key for SCIM?

Yes, in Lemontaps, open the IdP settings page and locate the SCIM settings card. In the three-dots-menu you will find an option to generate a new access key.

Note that when you do this, the old access key won't work anymore.

Something is not working as expected. Where should I go for debugging?

You can always find all provisioning logs in your identity provider.

Can I automatically send out invites once a new user is provisioned?

Yes. You will find a toggle to enable this on the SCIM settings card on the IdP-settings page in Lemontaps.

We recommend to do the initial provisioning without automatic invites enabled. Afterwards, you can verify the created accounts and then trigger invitation emails from the accounts table. You can then enable automatic invites for user provisioning.

I want to remove an attribute from the Sync. How do I do this?

You have two options. You can either remove the attribute from the mapping in your IdP, or you can remove the attribute from the mapping in Lemontaps. Both will have the same effect.
For more information about the mapping configurations, please read this guide: Mapping Guide → 

I want to add a new attribute to the Sync. How do I do this?

You need to add this new attribute to the mapping in your IdP, as well as to the mapping in Lemontaps.

For more information about the mapping configurations, please read this guide: Mapping Guide → 

I removed an attribute from the configuration, but it is still disabled for editing for some users.

Just remove the attribute from the mapping in Lemontaps and users will be allowed to edit it again.

For more information about the mapping configurations, please read this guide: Mapping Guide → 

Which SCIM version do you support?

Our SCIM API supports SCIM 2.0.

Which identity providers are supported?

Since SCIM is an open standard, all IdPs that support SCIM should work. This includes e.g. Entra ID or Okta.

How do I remove a user who was provisioned via SCIM?

Users who were provisioned via SCIM cannot be deleted from within Lemontaps. Instead, they have to be removed from the provisioning scope within your IdP.

I don't want to push groups in Entra ID, but only users. Is this possible?

Yes. Navigate to the responsible enterprise application, where SCIM is configured, and open the Provisioning settings from the left plane. Go to Attribute Mapping -> Provision Microsoft Entra ID Groups and select "Enabled - No".
If you assign a group to the application, its members will still be provisioned, but the group itself won't be.

I want users to be created or updated, but not deleted. Is this possible?

You can usually configure this in the SCIM settings in your IdP. Note that disabling the "Create" operation and only having "Update" or "Delete" enabled is not supported.

For Entra ID: Navigate to the responsible enterprise application, where SCIM is configured, and open the Provisioning settings from the left plane. Go to Attribute Mapping -> Provision Microsoft Entra ID Users and select the Target Object Actions you wish to support.

For Okta: In the Okta application, navigate to the "Provisioning" tab. There you will be able to deselect the "Update" or "Delete" operation.

Glossary

IdP - Identity Provider (e.g. Okta or Entra ID)

SCIM - System for Cross-domain Identity Management

Provisioning / Sync - Used synonymously, refers to the goal of SCIM (automatic user provisioning and synchronization)