Set up SCIM user provisioning: Microsoft Entra ID

These instructions explain how IT admins can set up SCIM user provisioning for their team after setting up single sign-on (SSO). For more information about SCIM user provisioning, see this article. 

Limitations:

• Admins cannot be managed via SCIM. If a user is provisioned via SCIM and then promoted to admin, it won't be possible to continue managing that user via SCIM. 
• Existing accounts not associated with your organization cannot be imported into your organization during SCIM provisioning.
• Email update operations cannot be completed if used in conjunction with Email NameID policy format. This is only applicable to SSO configurations using SAML.

Prerequisites

• Admin access to DeepL
• Single sign on (SSO) is setup for DeepL. If you haven't set up SSO, follow the instructions.
  • OpenID Connect
  • SAML
• Remove JIT group synchronization and groups, if it was enabled in a previous setup. Follow the instructions in this article.
• If you're using the OpenID Connect protocol in your SSO setup, check if the application was created via the Enterprise application and not via the App registration. Follow the instructions in this article.

Enable SCIM in DeepL account

1. Go to the Settings of your DeepL account
2. In section Team and User provisioning configuration, click Manage user provisioning

3. Select Enable SCIM provisioning
   An SCIM admin API key is created. You need this API key for your configuration in Entra ID. 

   If you've previously set up JIT group synchronization, make sure to disable it to avoid any user provisioning issues. Before disabling JIT group synchronization, export your existing groups and users. 

Set the SCIM configuration in Entra ID

Create the connection

1. Go to your Microsoft Entra ID instance and the DeepL application under Enterprise applications.
2. Select Provisioning under Manage.
3. Click on New configuration. 
   
4. Enter the following information on the next page.
   • Tenant URL: https://scim.deepl.com
   • Secret token: SCIM API key
     You'll find your SCIM API key in your DeepL admin account under Admin keys. For more information, see this article.
5. Test the connection by clicking on Test connection
6. Once the connectivity was tested successfully, click Create
   The new connection is created. 
   

Assign users and groups

You can move to the next section, if you already assigned users and groups to the application during the SSO setup. 

1. In your application, select Users and groups under Manage
2. Click Add user/group
   
3. Click None selected
   
4. Select the groups containing the users for DeepL access. Click Select and in the last step Assign. 
   
   Users and groups are assigned to the DeepL application. 

Configure the provisioning scope

1. Select Overview in the left-side menu
2. Select the Properties tab
3. Click on the edit button, next to Basics
4. Select Synch only assigned users and groups under Scope
5. Click Apply
   

Configure the attribute mapping

1. Select Attribute mapping in the left-side menu
   There are two options to select from:
   • Provision Microsoft Entra ID Groups
   • Provision Microsoft Entra ID Users
2. First, select Provision Microsoft Entra ID Groups
   
3. Edit the displayName attribute mapping
   • Set Match object using this attribute to Yes

   • Set Matching precedence to 2

     

4. Edit the externalID attribute mapping
   • Set Match object using this attribute to Yes

   • Set Matching precedence to 1

     

5. Save the change
   
6. Select Provision Microsoft Entra ID Users
   

7. Keep the following attributes, delete all others, and save the changes

   • userName
   • active
   • preferredLanguage
   • name.formatted
   • externalId

   

8. The userName attribute value must match the email address attribute value set in the SSO configuration.

   Entra uses this userName to identify existing DeepL accounts in your organization. If SSO and SCIM are not aligned, accounts may be created in an unintended way. If you do change this mapping and are using SAML, you need to make the same changes in your email address mapping in your SAML configuration.
   OpenID ConnectSAML
   1. Click Edit next to the userName attribute
   2. Set the Source attribute to mail and confirm with Ok

   By default, Entra ID uses the user.mail property as the email address attribute in the SAML assertion. This can be configured at the application level. For the SCIM userName attribute mapping, we require the same value that is outputted by the SAML integration.

   The instructions for the default case are as follows:

   1. Click Edit next to the userName attribute
   2. Set the Source attribute to mail and confirm with Ok

   

If you accidentally delete a necessary attribute, you can discard the changes and start the attribute mapping process again. Alternatively, you can recreate the attribute based on the following table.

Switch([IsSoftDeleted], , "False", "True", "True", "False")

preferredLanguage

preferredLanguage

Join(" ", [givenName], [surname])

name.formatted

mailNickname

externalId

Test provisioning

Test your setup before starting the provisioning process.

1. Select Provision on demand from the left-side menu
2. Select a group and a user that has access to the DeepL SSO application
3. Click Provision

There are the two following outcomes. 

• Error: If you get an error, contact us. Include the full error message and especially the x-trace-id for troubleshooting and investigation. 
  
• Success: When the test was successful, you get a success message and groups and users are created in your DeepL admin account. 
  

Start provisioning

1. After successfully testing provisioning, go to Overview (Preview) and click Start provisioning.
   Groups and users are continuously provisioned. In Entra ID provisioning cycles happen every 40 min.

2. When groups and users are provisioned, each SCIM group is created in your DeepL admin account. Go to your DeepL admin account and open the Groups tab. 

   Groups are created with the same display name as their corresponding group records in Entra ID.
3. Link a subscription to each group created to give users product access. There is no need to link a subscription to the default group since it can be used for admins who don't need a license and for users who cannot be provisioned into their respective groups. For more information, see this article. 

Download provisioning logs

If you experience any provisioning issues, the DeepL Tech support team will ask you to provide provisioning logs in JSON format. To obtain these logs, follow these steps:

1. In the left-side menu, go to the Monitor section and select Provisioning logs
2. Select all statuses, including Success
3. Click Download and select JSON format
4. Send us the resulting file for analysis