Connection Modes User Guide

Modes

The DAZZM platform supports 3 connection modes:

Multiple Modes

The platform supports the activation of multiple modes simultaneously. As shown in the example below, all 3 modes can even be available at the same time:

Configuration via Account

It is in the Account application that you can configure the authentication modes for your application. Each environment must be configured individually. For example, the production environment might use "Username and password," while the development environment could use "Unique connection link received by email."

Here’s how this is presented in Account. As shown, two modes are active, while one mode is not.

To activate a mode, simply configure its options, which can be done by clicking on its tile.

Mode: Unique connection link received by email

This is a platform-specific mode, also known as "Magic Link."

Available Options

In addition to its basic functionality, the following options are available:

Session expiration, forcing the user to reconnect after a certain number of minutes. Although expressed in minutes, setting a higher number, such as 4 hours is more common.
Second-factor authentication via SMS (MFA). An SMS is sent after using the link received by email, and the user must enter the code.

Notes

Although it is referred to as a "connection link," the experience on mobile sends a "code" rather than a hyperlink because, in the context of a mobile app, clicking a link in the email would open the browser on the phone instead of reactivating the tab from which the user started the session.
On mobile, if the second-factor authentication via SMS is enabled, the user will first receive a code via email, then a second code via SMS.

Here are the configuration options for this mode:

Prerequisites

This mode only requires the "email" field, which is under the "User" Aggregate by default.
To enable second-factor authentication via SMS, a field must be created under the "User" Aggregate to store mobile numbers. The name of the field is not fixed. Once created, you can enable this second factor by selecting the field in Account.

Mode: Username and password

A traditional mode where a username and password are assigned to the user.

Available Options

In addition to its basic functionality, the following options are available:

Password complexity control.
Session expiration, forcing the user to reconnect after a certain number of minutes. Although expressed in minutes, setting a higher number, such as 4 hours is more common.
Second-factor authentication via SMS (MFA). After using the password to log in, an SMS is sent, and the user must enter the code.

Here are the configuration options:

Prerequisites

-This mode requires a few prerequisites. To simplify the process, we have created a feature that will generate them automatically. Just click on "Install requirement".

This action will:

• Add the "username" and "password" fields to your "User" Aggregate

• Create a "changeCredentials" command ¹

• Create a "Password changed notification" workflow

-To enable second-factor authentication via SMS, a field must be created under the "User" Aggregate to store mobile numbers. The name of the field is not fixed. Once created, you can enable this second factor by selecting the field in Account.

¹This command can be deleted if the client does not need this case. This case is only necessary if end users have no access to email, which is a possible scenario, among others, in the healthcare field.

Configuration

This authentication mode supports several "user stories":

As a user, I want to log in with my username and password.
As a user, I want to reset my password.
As an administrator, I want to set the username for a new user and send them an email invitation to create their password.
As a user, I want to create my password after receiving an invitation.
As an administrator, I want to set a temporary username and password for a user, because the user does not have access to an email account to receive an email.

After installing the minimum requirements, the solution creator must modify their application.

Here are the steps to follow for "user story" #3:

-The administrator must assign a username when creating a new user's profile. Here are the 2 configuration options:

Option 1: Add the "username" field as required in the "create" command.
Option 2: If you prefer to use the user's email as the "username" rather than having a separate field, then you need to delete the "username" field that was created for you, and recreate it as a "computed field" returning "data.email".

-Next, you must add a button and associate it with the "Send Password Invite" behavior. This will allow sending an email with a "Magic Link" to the user so they can set their password. This "Magic Link" will be valid only once.

To prevent another employee from modifying the "username" and/or email and then being able to change the password via a "magic link," it will be important to make these fields (or the page) accessible only to administrators and potentially to the "current user" using CanAccess.

Here are the steps to follow for "user story" #5:

-First, you need to add a button and associate it with the "Execute a Command" behavior using the "changeCredentials" command. This will allow an admin to assign the username and initial password to a new user.

The administrator will provide the login details in person or verbally, as the user does not have an email.

It will be important to make this button or the employee detail page accessible only to administrators and the "current user" using CanAccess, to prevent an employee from modifying someone else's login credentials.

Demo

Once these configurations are in place, the functionality is ready to be used. Here are some screenshots demonstrating the functionality:

Mode: Connection with a Microsoft Account

This mode delegates the entire authentication process to Microsoft. It is advantageous because it provides the client with many options regarding policies. For example, it is in the Azure Active Directory configuration where the client controls MFA options, including SMS, Microsoft Authenticator, and others. The client also controls session expiration times, which can even vary depending on user groups or whether the connection is internal or external.

Options

In addition to the configurable options in Azure Active Directory, this mode offers two options:

Force User to Reconnect is configured in Azure Active Directory. If this option is disabled, sessions will not expire, even if the configuration in Active Directory indicates that they should. It is strongly recommended not to disable session expiration unless specifically requested by the client.
Create Unknown Microsoft User: with this option, there is no need to create users in advance. When a user logs in for the first time, Azure Active Directory returns the user's minimal information, and the application automatically creates a record for that user.

Here are the 2 options, as seen from the Microsoft dialogue:

Prerequisites

This mode requires that an "email" field and a "createFromOpenID" command exist under the "User" Aggregate. By using "install requirements," these prerequisites will be automatically set up for you.

Configuration

Link between your application and the client's Azure AD environment

To enable this connection mode, the client must first authorize the application to use their "Azure Active Directory" by adjusting the configuration on their side. To do this, you need to provide the client with the URL of your application. The administrator on the client's side will use this in their configuration.

In return, the administrator on the client's side will give you two "IDs" that you will configure on this screen:

Customization of the "createFromOpenID" Command

If you have enabled the option "Create unknown Microsoft user when they connect," then when a new user logs in, the system will call the "createFromOpenID" command.

This command should not be placed in the screens, as it is part of the Microsoft account connection mechanism; however, you may need to modify it.

In your application, your "users" may have fields that you consider mandatory, such as the "role" field. Normally, the fields required to create a new user will be both on their profile page and in the "create" command, and/or you have assigned default values.

In the case of automatic creation, you need to customize the "createFromOpenID" command so that it also initializes the essential fields. For example, if you have a "role" field, you need to determine with the client which role to assign when a user is created automatically. To do this, you should add an appropriate "mutation field."

Be careful not to modify the "parameters" of this command—only the "mutation fields." Modifying the parameters will break the functionality.

Demo

Once these configurations are in place, the functionality is ready to use. Here’s the functionality:

How to Deploy a New Mode

Step 1: In a Development Environment
1 – Create a development environment.
2 – Enable the mode in Account for your development environment.
3 – Modify the application if needed (the screen and/or the "User" aggregate).
4 – Push the changes.

Step 2: In the Production (or QA) Environment
1 – Deploy the application.
2 – Reapply the same authentication mode configurations in Account.

Caution: The period between Step 1 and Step 2 may leave the application in a potentially inconsistent state. For example, your User screen may show an "Send invitation" action, even though you have not yet enabled the "Username and password" mode. Nothing serious will happen, but it is better to perform both actions quickly.

Step 3: Adjust the Configuration in Dev for a Simpler Mode
Once you have deployed your changes to production, you may decide to modify the configuration in Account. For example, if in production the application only supports "Username and password," you can disable this mode in your development environment and only enable "Magic link obtained by email." Your subsequent "pushes" will not affect the production environment.

If you do this, there could be some inconsistency in your environment. For example, your User screen might show an "Send invitation" action, even though you have disabled the "Username and password" mode. This is not a problem. The key point to remember is that the configuration in your environment is "local," and you won’t affect other environments by modifying the options in yours.

Configuration of Azure Active Directory by the Client

This section provides a high-level overview of the actions to be taken by the Azure Active Directory Admin at the client. It is not intended to be a guide for the client, as Azure Active Directory configuration is too variable for us to offer support on the specifics. Instead, this serves as an overview, allowing solution creators to have a general understanding of the changes that need to be made and explaining how the application's URL, the "Application ID," and the "Tenant ID" are used.

In these screens, "Octopus-ITSM.com" is shown as the company. This represents the owner of the "Azure Active Directory" environment. When the client performs their own configuration, they will see the name of their organization. So, here, we show how the Azure Active Directory domain admin of "Octopus-ITSM.com" authorizes a DAZZM application to use their authentication services.

1 – Register the application by giving it a name, specifying who can connect to it, and entering the application’s URL.

2 – Enable "ID tokens (used for implicit and hybrid flows) in the Authentication section."

3 – Send the Application ID and Directory ID to the solution creator.