User synchronization

When a connection to Microsoft Entra ID is created and authorized, you can set up user synchronization to Sofa.

Sofa allows setting up synchronization of users and groups from various sources. The synchronization service takes care of all operations related to synchronizing the identity data between the local environment and Active Directory (in this case, Microsoft Entra ID).

Synchronization settings are available from the Administration window by clicking the Sofa 365 Bridge button and selecting User synchronization.

The Synchronization window lists all existing synchronizations (if there are any).

Creating a new synchronization

To create a new synchronization, the Synchronization window provides the button + Add Entra ID (Azure AD) synchronization.

Select the button to open the New synchronization window, which is composed of several tabs. Select a tab title to switch between them.

The tabs also contain buttons to move to the next or previous tab and a button to save the entered details.

Connection overview

The Connection tab displays details from the settings in the Connection window (ADMINISTRATION > Sofa 365 Bridge > Connection). They are the connection name and identifier, a note and the tenant ID. Details on this tab are read-only, displayed to indicate that the synchronization will be created for this connection.

The Tenant ID term is explained in chapter Key concepts.

If the other tabs are not available, the connection is probably not authorized or tested (see chapter Editing the Microsoft Entra connection.

Select Next: Parameters> to continue to the Parameters tab.

Parameter settings

Use the Parameters tab to set up the synchronization parameters.

Enter a unique name for the synchronization in the Name field; this field is mandatory. The name will be used with the synchronization entry in the list of synchronizations. The name is only used internally in Sofa.

You can create more than one synchronization, but only one can be active at a time.
The string entered in Identifier is automatically generated based on the Name, but you can edit it.
You can enter any text in the Note field to describe the purpose of the synchronization. This text is optional and intended for the administrator’s overview and information.

To synchronize users at all, they need to be added to a group (or more groups). In the field Remote groups whose members will be synchronized, select groups from Microsoft Entra, whose members will be transferred to Sofa as its users. Click the field to display the list of remote groups of the selected tenant. You can select more than one item from the list.

Members of subgroups will not be included. If a selected group contains groups, the members of the subgroups will not be automatically synchronized. To synchronize a subgroup, add it separately.

Use the Run period section to set when to run the synchronization process. When setting up the run period, consider how often Microsoft Entra ID settings change and how fast the users need to be updated.
In Time, set the hour and minute when to run the synchronization, and check the boxes for the days of the week when to apply this setting. To set up a more complex synchronization schedule, click Add a row to insert another set of controls.
If you keep the Enable synchronization box checked, the synchronization will run as scheduled. The schedule will be active as soon as the synchronization is saved.
Check Send an e-mail if synchronization fails to enable a notification e-mail if the scheduled synchronization fails. The reason for failure can be for example a connection error. The notification will be sent to Sofa users in Administrator and Subject manager roles, regardless whether the synchronization was run manually or automatically.
If Send e-mail to the new user is checked, a welcome message will be sent to the e-mail address of users newly created by the synchronization.
If Send a link for setting the password to the new user is checked, a link to their password will be sent to the e-mail address of users newly created by the synchronization. Only use this option if you want users to log in to Sofa using a name and a password. If you want users to only log in using SSO (Single Sign On), do not check this field. In general, we recommend not to check, which will allow combining local and Microsoft-Entra-based user authentication.
To remove already existing synchronized user accounts in Sofa when activating a new account, check Disable Sofa accounts that used to be synchronized. This only applies to synchronized accounts in Sofa; if a previously synchronized user from a group in Microsoft Entra is removed, the account will be automatically disabled. Manually created users are not disabled this way.

Select Next: Mapping user attributes> to continue to the Mapping user attributes tab.

Setting up user attribute mapping

The tab Mapping user attributes is used to create a schema for mapping entries that describe a synchronized user with entries that describe the user in Sofa.

To create a user correctly, only the following need to be mapped:

E-mail – map to the Mail attribute.
Name – map to GivenName.
Surname – map to Surname.

To use SSO (Single Sign On), the following need to be mapped:

ADFS Ident – map to Id.

To use Signer with SSO login, the following needs to be mapped:

Fixed AD ID – map to OnPremisesImmutableId.

The other attributes do not need to be mapped to Sofa; you can map them as you see fit. These attributes can be used for example in user lists or in some processes.

Select Next: Mapping extending attributes of the user> to continue to the Mapping extending attributes of the user tab.

Setting up the mapping for extending user attributes

This tab can be used to map another fifteen user-defined (extending) user attributes, which are not included on the previous tab.

All these attributes are optional.

Select Next: Mapping group memberships to continue to the Mapping group memberships tab.

Setting up group membership mapping

The tab Mapping group memberships is used for mapping groups from the remote (external) company described in Microsoft Entra to groups in Sofa. Select the groups using the options Group in Sofa and Remote groups.

To map more than one group, click the button Add a row to open more option pairs.

This mapping is optional and can be used to distinguish process groups.

Select Next: Mapping role membership to continue to the Mapping role membership tab.

Setting up role membership mapping

The tab Mapping role membership is used to map roles in Sofa to users in remote (external) company groups.

Roles are important in Sofa for example when using or managing certificates. If synchronized users need to use certificates in Sofa, you need to create a suitable Microsoft Entra group, assign the users to it and map the group to a matching Sofa role (Certificate users). The same procedure can be applied for other roles, such as Certificate managers or Administrators.

Generally speaking, you can, but not need to, use the same group as when selecting the group to synchronize on the Parameters tab. You can also map more than one Microsoft Entra group to a single role.

Select the entries to map using the options Role in Sofa and Remote groups. To map more than one role, click the button Add a row to open more option pairs.

Roles that need to be filled:

Administrators.
Certificate managers.
Certificate users.

All other roles are optional, and you can choose to fill them or leave them empty based on Sofa features and settings.

Select Next: Logging to continue to the Logging tab.

Logging level setting

The Logging tab is used to set up how much information is logged during synchronization. In Logging level, select one of the levels Debug (debugging data), Information and Warning.

Warning is the lowest logging level – only warnings, errors and critical errors will be logged.
Information is the medium logging level – information, warnings, errors and critical errors will be logged.
Debug is the highest logging level – all previous messages are logged in addition to debugging information. It is used as a basis to solve issues.

Saving the synchronization setup

Click Save synchronization to save the synchronization description.

Testing the synchronization

A saved synchronization description is displayed as a row in the list in the Synchronization window.

Click anywhere in the row to select it and at the same time display a toolbar with several buttons in the upper part of the window.

We recommend testing the created synchronization by running it manually. Click Run synchronization on the toolbar. When you confirm the following query Are you sure you want to run the synchronization outside of the schedule?, a green stripe with the message The synchronization has been started is displayed.

The synchronization process itself takes a few moments. To check the result, select the toolbar button *Display the logs* to view the log entry.

Each logged operation is written to a separate row, starting with the date and time it was run. Use the triangle buttons at the beginning of each entry to expand (or hide) a list of individual actions that took place during the synchronization.

Note the third column with four graphical symbols. They indicate the operation result. Their meanings are, from left to right: Error – Critical error – Information – Warning.

If you have set up notifications on the Parameters tab, you will be notified by e-mail when any of the synchronization tasks fails.

Users assigned to administrator roles will always receive a message when a synchronization fails.

Editing the synchronization settings

Select an entry in the list of synchronization settings to display a toolbar and use its buttons to edit the synchronization details.

Click Edit synchronization to open a window where you can edit the properties of the selected synchronization. The window consists of seven tabs, just like the New synchronization window. Use the tabs to edit or add the synchronization parameters.
You can click Delete synchronization to completely remove the whole synchronization setup. You will need to confirm the deletion in the following dialog with the query Are you sure you want to delete the synchronization?
Or you can click Disable synchronization to stop the selected synchronization from running temporarily, without deletion. After you confirm the query Are you sure you want to disable the synchronization?, the Run period column displays Inactive.
The button Disable synchronization changes to Enable synchronization for this entry. You can use it later to enable the synchronization again.

When the synchronization is set up, the synchronized users can log in to Sofa using their Microsoft Entra account. https://testsofa.602.cz/aad