Set up SCIM user provisioning: OneLogin

These instructions explain how IT admins can set up SCIM user provisioning for their team. 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
• Remove JIT group synchronization and groups, if it was enabled in a previous setup. Follow the instructions in this article.
• SCIM provisioning with OneLogin is currently only available for SAML.

Set the SCIM configuration in OneLogin

We recommend to create a new SCIM Provisioner with SAML (SCIM v2 Core) application that handles both SSO and provisioning. If you want to enable SCIM without migrating to a new application by adding a separate, provisioning-only application, see Add SCIM without migrating to a new application. 

Create the application

1. In the OneLogin administration panel, go to the applications panel and click Add App
2. Search for and select the application named SCIM Provisioner with SAML (SCIM v2 Core)
3. Click Save

Configure the connection

1. Go to the Configuration tab
2. In the SAML Audience URL field, enter https://w.deepl.com/auth/realms/prod
3. In the SAML Consumer URL field, enter https://w.deepl.com/auth/realms/prod/broker/{your-sso-subdomain}/endpoint. Replace {your-sso-subdomain} with the domain name you supplied when you configured SSO on the DeepL SSO settings page. For more information, see this article. 
4. In the SCIM Base URL field, enter https://scim.deepl.com

5. In the SCIM JSON Template field, enter the following template:

   {
     "schemas": [
       "urn:ietf:params:scim:schemas:core:2.0:User"
     ],
     "userName": "{$parameters.scimusername}",
     "name": {
       "formatted": "{$user.display_name}"
     },
     "externalId": "{$parameters.externalId}",
     "active": "{$user.status}"
   }

6. Click Save

Enable provisioning

1. Go to the Provisioning tab
2. Select Enable provisioning
3. Ensure admin approval is required for all operations for now. This lets you test the connection with one or two users and groups before provisioning runs automatically.

4. Click Save

   

Configure the parameters

1. Go to the Parameters tab
2. Click the Groups field, select Include in User Provisioning, and click Save
   
3. Click the NameID field and set the value to OneLogin ID
4. Click the scimusername and set the value to Email
5. Click the plus icon to create a new parameter. Set the field name to firstName, select Include in SAML assertion, and click Save. Set the value to First Name and click Save.
6. Repeat the previous step to create the following parameters: 
   • lastName with the value Last Name
   • email with the value Email
   • externalId with the value OneLogin ID
     
7. Click Save. 

Add a group mapping rule

1. Go to the Rules page
2. Click Add Rule
3. In the Name field, enter a name for the rule. We recommend Role to Groups.
4. Leave the Conditions empty
5. Under Actions, set the first dropdown to Set Groups in <application name>, and set the radio buttons to Map from OneLogin
6. Set the next dropdown to role. In the text box, enter a regular expression to filter role assignments to those relevant to DeepL. For example, enter DeepL.* for roles starting with DeepL, or .* to match all roles.
   
7. Click Save, then save the application

Set the signature algorithm

1. Go to the SSO page
2. Change the signature algorithm to SHA-256
3. Click Save

Assign access

1. Go to the Access page
2. Select the roles that should be given access to DeepL
3. Click Save

Get Metadata URL

1. Select SSO from the left side menu
2. Copy the metadata URL from Issuer URL and use it to continue to set the SSO configuration in DeepL admin account. For more information, see Set the SSO configuration in DeepL account.
3. Check if SHA-256 or SHA-512 is selected under SAML Signature Algorithm
4. Save the changes

Set the SSO configuration in DeepL account

1. Go to the Settings tab in your DeepL admin account.
   Under Team and Single sign-on the SSO domain has the status Domain name approved.
2. Click Set up SSO next to Single sign-on.
   In the Set up SSO form select SAML as the Authentication type
3. Select Import from URL paste the Metadata URL from OneLogin. For more information, see Get Metadata URL. 
4. Set NameID policy format to Persistent
5. Enter the following
   • Assertion attribute: First name = firstName
   • Assertion attribute: Last name = lastName
   • Assertion attribute: Email address = email

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

   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. 
4. Go to your OneLogin SCIM application
5. Go to the Configuration page
6. In the SCIM Bearer Token field, enter your SCIM API key. You will find your SCIM API key in your DeepL admin account under Admin keys. For more information, see this article.
7. Click Save

Test provisioning

1. Go to the Configuration page and click Enable under API Connection. OneLogin now collects users and roles but will not provision them without admin approval.
2. Test the connection with one or two users and groups
3. Once you tested the connection, go to the Provisioning tab. Under Require admin approval before this action is performed, clear the operations that no longer require approval, and click Save.

After groups are provisioned, link a subscription to each group to give users product access. For more information, see this article.

Migrate with existing SAML SSO setup 

If you're an existing customer and already have setup SSO using the SAML protocol but don't see any options to configure SCIM in OneLogin, migrate with the following steps. If you're a new customer without a previous SSO setup continue with Enable and test provisioning. 

1. Go to the Configuration page and check under API Connection that Disabled is selected
2. To minimize disruptions, check that all access permissions are the same as those in the existing SSO configuration
3. Go to the Settings of your DeepL account
4. Click Edit next to Single sign-on (SSO)
5. Go to OneLogin and get the metadata URL on the SSO tab for the registered application that you have created with the steps under Create the application. Add the URL to the Single sign-on (SSO) settings in your DeepL account and click Confirm. 
   The new application registration is now in use for SSO login. Ensure that it is working correctly before continuing with Enable and test provisioning.

Add SCIM without migrating to a new application

You can enable SCIM without migrating to a new application by adding a separate, provisioning-only application. Keep the following trade-offs in mind before you choose this approach.

• You take on the additional overhead of maintaining a second application for provisioning with DeepL
• Role management and access become more complex, because actions must be duplicated between the two applications
• Discrepancies between the two applications can create confusion and undesirable outcomes, and such discrepancies are easy to create

1. Follow the steps under Create the application but ensure that Visible in portal is disabled, because this application is used for provisioning only and not for authentication. Click Save.
   
2. Go to the Configuration tab
3. In the SCIM Base URL field, enter https://scim.deepl.com
4. In the SCIM Bearer Token field, enter your SCIM API key. You will find your SCIM API key in your DeepL admin account under Admin keys. For more information, see this article.

5. In the SCIM JSON Template field, enter the following template:

   {
     "schemas": [
       "urn:ietf:params:scim:schemas:core:2.0:User"
     ],
     "userName": "{$parameters.scimusername}",
     "name": {
       "formatted": "{$user.display_name}"
     },
     "externalId": "{$parameters.externalId}",
     "active": "{$user.status}"
   }

6. Click Save
7. Go to the Parameters tab
8. Click the Groups field, select Include in User Provisioning, and click Save
   
9. Click scimusername. The value here must match the value of the EmailAddress parameter in your SSO application configuration. If you use SAML and these values do not match, duplicate accounts may be created for a user. If you use OIDC, set the value to OneLogin ID. Click Save.
10. Click the plus icon to create a new parameter. Set the field name to externalId and select Include in User Provisioning. Set the value to OneLogin ID and click Save.
    
11. Add the group mapping rule described in Add a group mapping rule, then save the application
12. Select the roles for provisioning, as described in Assign access , and click Save
13. Test the connection as described in Enable and test provisioning

Download provisioning logs

To troubleshoot provisioning issues or verify successful operations:

1. In your OneLogin admin console, go to Activity > Reports.
2. Create a report that filters by your DeepL application and provisioning events.
3. Click on individual events to view detailed information.
4. To export logs, click Download CSV or use the OneLogin API to retrieve logs in JSON format.

For more information about OneLogin provisioning logs, please see OneLogin's own documentation.