Skip to content

External User Integration

Businesses often have an elaborate range of applications they have to work with. In order to keep user management manageable, they want to centralize it. Microsoft Entra (formerly known as Azure AD) is a frequently used tool for this purpose. Google is another example of a tool which can be considered as an identity provider to synchronize with. The first thing to do is setting up a configuration for connecting with the external service. Instructions on how to configure applications in Microsoft Entra can be found here

Working with Directory Services

In AERO a new concept is introduced: the Directory Service. A directory service represents an external identity provider. In other words, it refers to another tool or application to which AERO can delegate the user management process. Partner consultants can configure directory services in the partner console.

Configuring a Directory Service

To add a new directory service, open the partner console, click Directory Services and click the + New button.

When you save a new directory service, or change the Directory Url or Synchronization Application ID of an existing one, Aero first asks Microsoft Entra for a token with these settings and the client secret. If Entra rejects them, or cannot be reached, nothing is saved and you see why.

Label (Required)
The readable label of the Directory Service. This is what administrators will see when setting up an external user integration in their environment.

Organization (Required)
The organization for which this directory service is available. Any environment within the selected organization will be able to connect to this directory service.

Directory Service Type (Required)
The application Aero will be connecting with. Currently, only Microsoft Entra is available.

Directory Url (Required)
The URL of the identity provider you want to integrate with.

Synchronization Application ID (Required)
Refers to the application Aero will connect with to synchronize users.

Client Secret (Required)
The client secret of the application Aero connects with to synchronize users. After saving, the secret is only shown masked: its first three characters followed by asterisks. To change it, use Replace client secret (see below).

Secret Expiry Date (Required)
The expiry date of the client secret.

Expiry Notification Address (Required)
An email address to send emails to whenever the client secret is about to expire or has expired.

Expiry Warning Period (days)
The number of days before the secret expires from which warning emails are sent, between 1 and 30. Leave empty to use the default of 10 days. A warning email is sent every day from the start of the warning period until the secret is replaced, also after it has expired.
Field Group Properties

Replacing the Client Secret

A client secret in Microsoft Entra expires. Replace it before it does, otherwise user synchronization stops working. Organization administrators replace it in the setup section under Setup > Organization: the Directory services grid lists every directory service of the organization, with its masked client secret, its expiry date and the environments that use it. Select a directory service and click Replace client secret. Partner consultants can do the same in the partner console, on the organization page or by opening the directory service and clicking Replace client secret.

To replace the client secret:

  1. Create a new client secret for the synchronization application in Microsoft Entra and copy its value.
  2. In the Replace client secret dialog, paste it into New client secret. Use the eye button to check what you pasted.
  3. Fill in the Secret expiry date of the new secret. It must be after today. The dialog shows the expiry date of the current secret and how many days are left.
  4. Check the Expiry notification address and the Expiry warning period, which are filled in with the current values.
  5. Click Save. Save is only available when all required fields are filled in correctly.

Before saving, MetaCom checks the new secret with Microsoft Entra. When Entra accepts it, the secret is stored, a confirmation is shown and the grid shows the new expiry date. When Entra rejects it or cannot be reached, nothing is saved and the dialog stays open with the error, so you can correct the secret and try again. Cancel closes the dialog without saving.

Delete the old secret in Microsoft Entra only after saving the new one, so user synchronization keeps working in the meantime. The client secret is never shown in full after saving, only masked.

Connect your environment to a directory service

Once a directory service has been created, environments can connect to it. Note that only partner consultants can create directory services, and that only directory services in the same organization can be connected with. To connect an environment to a directory service, first go to the setup section. Expand the Environment item in the sidebar menu. Then click External User Integration.

In the External User Integration page all existing connections to directory services are displayed in a grid. You can easily add a new connection by clicking the + New button. In the newly created line you can configure the following properties:

Property Required Purpose
Directory Service Yes The directory service to connect to. Note that only directory services beloning to the same organization can be selected.
Groups to Synchronize Yes The groups at the external identity provider to synchronize users from. Multiple groups can be configured. These should be separated by a comma. Note that it is important that the names of the groups are exactly as you enter them in this field.
Groups No User groups selected here will automatically be assigned to all synchronized users. BizzStream will not remove users from groups that are not selected here.
Menus No Menus selected here will automatically be assigned to all synchronized users. BizzStream will not remove users from menus that are not selected here.
Periodically Synchronize Users No Indicates whether user synchronization should be executed every 15 minutes.

Synchronize users

When an environment is successfully connected to a directory service, users can be synchronized between BizzStream and the external identity provider. Synchronization is the process of registering and updating external users in BizzStream. Users can be synchronized manually by checking the line of the directory service for which users should be synchronized, and clicking the Synchronize button. Alternatively, the checkbox Periodically Synchronize Users can be checked to synchronize users automatically every fifteen minutes.

In both cases:

  • Non existing users will be added to the current environment. It is important to realize that a user can have access to multiple environments. If a user already exists the user will be modified in a way that environment access will be added to the existing users.
  • Personal settings (like name or email) will be overridden by the settings acquired from the external environment.
  • An existing user will be deactivated when:

  • It has been removed from a group in the external environment that has been assigned to a particular BizzStream environment;

  • The user group of the user has been removed from the BizzStream environment;
  • If the user is deactivated in the external identity provider.

Management of the external user profile is the responsibility of the external environment. This means that the external identity provider is completely responsible for the settings activation and group memberships.

Aforementioned also implies that the reset password functionality does not apply to external users. Any reset of the password should be done in the external identity provider. Since the user is only external in the context of one environment, it is possible that a user still has access to other environments using a password.

User authentication - the login process

External users can log in with their external user environment credentials. In other words; the username and password specified at the external identity provider. The start of the login process is identical for all users. Every user starts by entering their username or email address and clicking Continue. After doing so, one of the following scenarios will take place:

  1. The user is not synchronized from an external identity provider. In this case the password field appears. The user enters their password and clicks Login to complete the login process
  2. The user is synchronized from an external identity provider, and only has access to the environment from which they were synchronized. In this case, a new window will open. In the new window, the login flow of the external identity provider will start. Once that is finished, the window will close again, and the user will be logged in.
  3. The user is an external user in at least one environment, but also has access as a 'regular' user to at least one environment. The user has to select the environment they want to log into from a combobox. After doing so, either the password field appears, or a new window is opened to start the login flow of the external identity provider.

Note If a user logged in using their external identity provider credentials, they can only access environments connected to the directory service connected to that identity provider. If they want to access other environments they have access to, they should log out, and log in again with their BizzStream credentials.