Purpose:

This module provides the reactive web blocks to build a login workflow that uses Microsoft services to authenticate the user and grant roles.

Microsoft Login Connector Package:

The Microsoft Logon Connector (hereafter MLC) can only be used when the required components are installed. These are;

• Microsoft Login Connector Core (Mandatory)
• Microsoft Login Connector Management (Mandatory)
• Microsoft Login Connector Reactive (Optional)
• Microsoft Login Connector Web (Optional)

You either need to install MLC Reactive or MLC Web

What is the Microsoft Login Connector

All Microsoft Cloud Services including Office 365, Dynamics 365, Sharepoint among others, are protected by an OAuth authentication from Microsoft Entra ID (previously know as Azure Active Directory). Entra ID is the identity provider, responsible for verifying the identity of users and applications that exist in an organization’s directory, and ultimately issuing security tokens upon successful authentication of those users and applications. Each external application needs to be register on Entra ID to be request an OAuth access token that will be included on each REST API request. This connector tries to abstract the complexity of the OAuth authentication needed in the authorization process to all other REST APIs from Microsoft.

Configuration

To make use of the MLC you need to perform a few steps in Azure and in the MLC Management application. When this is done you can then add authentication to your application.

The steps, in order, are;

1. Registering Connector Application on Entra ID or Office 365
2. Adding the Entra ID application to the MLC Configuration
3. Configuring authentication in Reactive application

Registering Connector Application on Azure and Office 365

To register the connector application on open up your azure portal at https://portal.azure.com. If you have an office 365 package you can login to azure using your office 365 admin credentials. In the search bar at the top of the screen type in 'App Registration' and select. You should see the below screen.

NB in the screen shots below use the callback https://<YourOutsystemsServer>/MicrosoftLoginConnectorReactive/CallbackPage rather than https://<YourOutsystemsServer>/MSLoginConnector/CallbackPage

Select New registration indicated by the plus symbol, getting the below (obviously with your organization being shown where Davies March is showing)

Provide a name, maybe something like 'Microsoft Auth for OutSystems' and set a redirect URI as https://<your outSystems Server>/MicrosoftLoginConnectorReactive/CallbackPage.

and hit register giving a record like the below

The client ID you will need to enter into your application is just below the display name.

To generate the secret, select certificates & secrets in the second menu from the left.

Select new client secret

Select how long you want the secret to last for and give it a name. This will generate the secret you need to add into your application.

Make sure you copy or note your secret as it will be stared out the next time you return to it and will need to generate a new one.

Adding the Entra ID application in the MLC Configuration:

The first step you need to do if give yourself the Administrator role of the Microsoft Login Connector Management application. You can do this via the OutSystems users application.

When this done you can log into the application via https://<OutSystems environment URL> /MicrosoftLoginConnectorManagement. You should see the following screen after authentication.

Follow these steps to add the Entra ID application created in the first step;

1. Click on New in the Application section
2. In the sidebar that has opened we will fill in the following details on the Details Tab. All these details can be retrieved from the created Entra ID application;
   - Tenant Id
   - Client Id
   - Client Secret
3. We also fill in a Description
4. Click on SAVE
5. Open the Espace tab
6. Select all the espaces / components that will be authentication with this Entra ID application.
   Note: An espace can only be attached to one Entra ID application

This concludes this step.

Configuring authentication in Reactive application:

To configure your Reactive application to make use of the MLC follow these steps;

* Add from Microsoft Login Connector Reactive the client and server actions

* Add from Microsoft Login Connector Core

Then

1. Open the Login screen
2. Remove the container containing the following fields
   - Username
   - Password
   - Remember me
   - Forget password?
   
3. Open the Login action from the Login screen and perform the following actions;
   a. Remove the actions “DoLogin and FeedbackMessageClose from the flow
   b. Add the client action GetOAuth2AuthenticationURL from the MicrosoftLoginConnectorReactive component into the flow
   c. Fill in at least the following details in this action;
   -- EspaceName. This needs to be the name of the current component.
   -- oAuthProviderId. Entities.OAuthProvider.AzureAd in this example.
   -- Change the input variable “URL” of the widget RedirectToURL to GetOAuth2AuthenticationURL.AuthenticationURL
   d. The result should look like this;
   
4. Remove all unneeded variables and actions in the Login screen
   - Username
   - Password
   - Remember
   - ForgotPassword
5. Open the UserInfo block
6. Open the action ClientLogin and change the following;
   a. Remove all widgets except Start and the “redirect to the login screen” widget;
   b. The result should look like this;
   
7. Open the action ClientLogout and change the following;
   a. Remove all widgets except Start
   b. Add the server action GetOauth2LogoutURL from the MicrosoftLoginConnectorReactive component into the flow.
   -- Configure the property “EspaceNameToReturnTo” with the current component name.
   c. Add the User_Logout server action from the Users component into the flow
   -- This will cause a warning about double server actions in one client action. You can choose to ignore this warning or create a wrapper for these two actions if needed.
   d. Add a Redirect widget into the flow
   -- Configure the property URL to GetOauth2LogoutURL.LogoutURL

Now you should have a working authentication with the configured application in Azure AD.

This concludes this step.

Entra ID Managing OutSystems Roles

If you are looking to Entra ID to manage the roles synchronizing them to your OutSystems instance, then this article explains how to setup the roles on the Entra ID side. it is a little old now but shoudl still apply.

https://docs.microsoft.com/en-us/azure/architecture/multitenant-identity/app-roles#roles-using-azure-ad-app-roles

Solution: 404, page not found with the CallbackPage

Should you get (in)frequent 404 page not found errors for the CallbackPage after logging in you need to do the following steps;

1. Install the Factory Configuration application and open this application on your environment(s)

2. In the tab "Shared Configuration" create a new Shared Configuration of kind "web.config_XSL"

3. Fill in a name and optionally a description

4. Add the following Value and Save the configuration

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="xml" indent="yes" encoding="UTF-8"/>
<xsl:template match="@*|node()">
<xsl:copy>
<xsl:apply-templates select="@*|node()"/>
</xsl:copy>
</xsl:template>
<xsl:template match="/configuration/system.webServer/security/requestFiltering">
<xsl:copy>
<xsl:apply-templates select="@*|node()"/>
<requestLimits maxUrl="4096" maxQueryString="2048"/>
</xsl:copy>
</xsl:template>
</xsl:stylesheet>

5. In the tab "eSpaces" search for microsoftloginconnector

6. Select "MicrosoftLoginConnector" and/or "MicrosoftLoginConnectorReactive"

7. Select the newly created Shared Configuration in the dropdown and click on "Associate Shared Configuration"

• 8. Republish the Microsoft Login Connector components via Service Center

Disabling automatic account creation in OutSystems User module

By default if a user is authenticated against entraID if the account doesn't exist in OutSystems User module then this is createdd by this application. This can be disabled by going into the advanced tab of the application configuration in the MLC Managment application.