How to integrate Azure Entra to DocuWare User provisioning

If your organization uses Azure Entra to manage employee access to tools and services, you can utilize Azure"Provisioning" feature to automatically provide your users with access to DocuWare via SCIM. This guide will walk you through the steps to configure both DocuWare and Azure Entra to set up provisioning for your organization.

The current version of UserSync (v3) supports the following provisioning features:

• Automatic User Creation: Users assigned to the Enterprise application in Azure are automatically created as users in DocuWare.

• Attribute Synchronization: Any updates to user attributes (userName, email, activeness) in Azure will be reflected in DocuWare.

• User Deactivation: When users are deactivated in Azure, they are marked as 'disabled' in DocuWre, preventing them from logging in.

Creating a new application in Microsoft Azure Entra

1. Login to the Azure portal via the following link - Home - Microsoft Azure

2. Go to Enterprise Applications page.

3. Click New Application:

4. Click Create your own application:

5. Choose a Name for your app and select the option Integrate any other application you don’t find in the gallery (Non-gallery):

6. After the creation click the Provisioning menu in the side bar and in the browser’s URL bar update the URL so that
   #view is replaced with ?feature.userProvisioningV2Authentication=true#view
   in order to see all authentication options in Admin Credentials > Authentication Method.

7. Select Provisioning Mode > Automatic.

8. Open Admin Credentials section.

9. Don’t close the Azure configuration. Switch to DocuWare Configurations.

Embedding the new Azure Entra application in DocuWare

1. Go to DocuWare Configuration > Integrations > App Registration.

2. In the App Registration plugin, select New app registration.

3. In the Create Application Registration pop-up, choose Web application, then click Continue

4. Enter a Name for the app registration, then:

   1. Add a Redirect URL with the value https://portal.azure.com/TokenAuthorize

   2. Select Grant type: Authorization Code

   3. Select Allowed Resources: User Provisioning

   4. Ensure Use refresh token is enabled

   5. Click Save.

5. From the just created app registration copy the values of

   1. Application (Client) ID

   2. Client secret

6. Switch to DocuWare Configurations > General > User Provisioning.

7. In the User Provisioning plugin, activate the option Enable User Provisioning.

8. In the dropdown Identity Provider select Azure Entra.

9. In the dropdown Application Registration select the previously created app registration - see also step 4.

10. Click the Save button.

11. After saving, two authentication methods are provided as options:
    OAuth2 Authorization Code Grant and Bearer Authentication.

12. The next steps depend on your authentication method choice:

    1. OAuth2 Authorization Code Grant

       • Copy the links Tenant URL, Authorization Endpoint, Token Endpoint.

       • Navigate back to Entra > your application > Manage > Provisioning > Admin Credentials.

       • Make sure that the OAuth2 Authorization Code Grant is selected in the Authentication Method dropdown.

       • Paste all the copied data from steps 5 and 10 in the appropriate fields there.

       • When all the required data is populated click the Authorize button.

       • Then Save the changes.

       • If an error is displayed in the top-right corner after saving, click the Save button again.
         

• Bearer Authentication

• Copy the link for the Tenant URL and the generated Bearer token.

• Navigate back to Entra > your application > Manage > Provisioning > Admin Credentials.

• Make sure that the Bearer Authentication is selected in the Authentication Method dropdown.

• Paste the previously copied link for the Tenant URL and the Bearer token.

• When all the required data is populated click on the Test Connection button.

• Then Save the changes.

Mapping the user attributes in Azure Entra and DocuWare

Map the Microsoft Azure Entra properties with the DocuWare properties, so that the users can be matched and synchronized.  

1. Open Azure Entra ID.

2. To map the users, choose Provisioning > Mappings > User mapping > Provision Microsoft Entra ID Users.

3. Set the attribute mappings:
   
   Required:

   1. userName: userPrincipalName

   2. active: Switch([IsSoftDeleted], , "False", "True", "True", "False")

   3. emails[type eq "work"].value: Coalesce([mail],[userPrincipalName])

   4. externalId: objectId
      

   Optional:

   1. name.givenName: givenName

   2. name.familyName: surname

Additional information for user mapping

1. For mapping the email attribute you will need first to update its configuration:

   1. Open for Edit Attribute the attribute: emails[type eq "work"].value

   2. Change the mapping type to Expression.

   3. Update the expression field to: Coalesce([mail],[userPrincipalName])

   4. Cick OK to save.

2. For mapping the externalId attribute properly you will also need to first update it’s configuration:

   1. Open for Edit the attribute: externalId: mailNickname

   2. Change the Source attribute to: objectId

   3. Click OK to save.

3. Delete all the extra mappings and Save.

   If the mappings are not deleted, it can cause errors when updated users are provisioned.

Provisioning users and groups

Navigate to the Overview page in your Entra application and click the Start Provisioning button:

Provisioning users

1. Click Manage > Users and Groups > Add user/group > Select the users you would like to provision > Assign.

2. After adding the desired users for provisioning, they will either be automatically provisioned after some time or you can choose to provision them on demand.

3. Navigate to DocuWare Configurations > General > User Management.

4. Check if the expected users are provisioned successfully there.

Provisioning groups

1. Click Manage > Users and Groups > Add user/group > Select a group for provisioning > Assign.
   Note: If you want to assign the members of the group on-demand, you must add them to the list as well.

2. After adding the desired groups and users for provisioning, they will either be automatically provisioned after some time or you can choose to provision them on demand.

3. Navigate to DocuWare Configurations > General > User Management.

4. Check if the expected groups and users are provisioned successfully there.

Additional information about the process of provisioning groups

1. Searching for Groups: The system first searches for an existing group using the given displayName. If a group with that displayName exists in DocuWare, the process moves to updating the group; otherwise, it proceeds to creating a new group.

2. Group Creation and Update Handling:
   a) Creating New Groups: When no existing group in DocuWare matches the displayName, the service creates a new group with the specified members.
   b) Updating Existing Groups: If a matching group is found, the service updates the group’s details and adds new members to the group. It ensures that existing members are not replaced but retained alongside the new members.

Once the groups are mapped after their first synchronization, future mapping is done using the ID attribute. For example, if you decide to change a group's name in Entra ID and then provision the updated group, the group will be mapped by its ID. The service will update the group's name in DocuWare accordingly without removing its members.

1. Member Management:
   a) Adding Members: When updating groups, any new members are added while keeping the current members intact.
   b) Preventing Duplicates: The system is designed to avoid adding duplicate members to groups, ensuring each member is unique within the group.