Der Browser benötigt JavaScript, um die Webseite korrekt anzeigen zu können. Bitte aktivieren Sie die Scriptausführung.
The browser requires JavaScript to show this website. Please activate script execution.
Skip to main content
▲
Search in all areas (no filter)✓Search in current system version (11.200)Search in all system versionsSearch in packagesSearch in FAQs
Error: missing value for parameter 'map' (index 0) (click for details)
Callstack:
    at map.remove()
    at (Template:ww/Functions/Links/RelatedPages), /content/body/pre, line 69, column 32
    at template()
    at (Template:Custom/Views/Header), /content/body/pre, line 154, column 13
    at (en/01ww/200/02admin/005rmg/0057msal), /content/body/div[4]/pre[2], line 2, column 9
Loy & Hutz

Single Sign-On with MSAL

  1. Last updated
  2. Save as PDF

Overview

Microsoft Authentication Library (MSAL) is an authentication library provided by Microsoft to enable single sign-on in Microsoft  Entra ID (ehem. Azure Active Directory)  integrated domains. It can be used for websites, desktop and mobile applications. This library can therefore be used to log in to all waveware clients (from waveware 11.200.4928 also on the CAD-DWG Client, the DGN Client is not supported) by retrieving a token from the Microsoft identity platform to authenticate a user.

MSAL only works in the Fat Client if your system default browser is not "Internet Explorer". "Chrome", "Edge" or "Firefox" must be used as browser.
Please note that Single Sign-on with MSAL is a licensed functionality that must be explicitly enabled in your license file. To do this, have your license file expanded to include the 'SSO feature'. Among other things, this feature also includes the 'MSAL Basis' (1931) package, which you can install with the package manager after importing the new license file in order to apply standard rules in MSAL that control authentication and mapping (further information at 'Necessary Rules'). The package is available from waveware 11.200.4370.37.

Setup

The login process, which is carried out in waveware by default, can be overwritten using rules in the System Rule Editor. To apply MSAL in the Web, you absolutely need to register with Microsoft Entra ID and then two rules. On the one hand the 'Security.Authenticate' rule, which defines the type of authentication and in this case displays the login dialog of the Microsoft identity platform, and on the other hand the 'Security.MsalMapAuthenticate' rule, which assigns authorized data to waveware after successful authentication makes.

During setup, the server settings must be adjusted depending on the variant (SAML, MSAL, Kerberos). The waveware server service must be restarted several times and package installations take place. If you have set up the system landscape (e.g. test and production) on a server or are setting it up for production, please remember to communicate any downtime to the users. 2-4 hours are recommended here in order to have enough time to completely complete the setup and test it.

Requirements

Users who should be able to log in via MSAL Single Sign-On must be present in waveware as a satff record. The sample 'MSALMapAuthentication' mapping rule uses the email field on the staff card for matching. The field must therefore be filled with the unique attribute. Alternatively, you can usually use another field for assignment.

Staff records can be prepared as follows:

  • If the staff status is "Active", you can log in via SSO
  • If the user access is "Direct", the login can also take place

Enable MSAL/Domain Support

In order to enable authentication using MSAL, the method must be activated via the settings of the waveware server. Open 'waveware Server' in DataManagement and look for the "SSO" area.

8.png

Check the option 'Enable MSAL Support' and save the changes.

Client Connections

Port 443 is recommended for access via single sign-on (see 'waveware Server: Protocol of Client Connections'). However, a secure connection is always required if the Web Client, Custom Pages or Mobile Single Sign-on are to be used in addition to the Windows Client.

The secure client connections are set up in DataManagement in the 'Webserver' area. When importing the certificate, it must be ensured that the private key is marked as exportable and that the service account of the waveware server is authorized accordingly. You can find out the exact procedure under 'Set up Web Server: Import Certificate'.

The waveware service account must have the appropriate rights to the required TCP port. Using a command window started as administrator, you can check this with the following command:

netsh http add urlacl url=https://+:443/ user=domain\username
Consider that for example port 443 must not be used on your system if you want to set it up for the waveware web server. Check that for exapmle, the Internet Information Services (IIS) are uninstalled on the system before you start the waveware server. If the port set up for the web server is blocked by another service, the waveware server cannot be started or is stopped again after a few seconds.
After changes to the certificates of the waveware server, the service must be restarted.

Registration

Loy & Hutz provides a standard MSAL registration for waveware. This registration provides endpoints that work with the waveware Windows Client and Mobile Client. However, this MSAL registration will not work with the waveware Web Client and will not work in Custom Pages because the URLs where you deploy your Web Client or Custom Pages vary. If you want to use the Web Client or Custom Pages via single sign-on via MSAL, register the applications via  https://portal.azure.com.

The authenticate rule also varies depending on which clients are to be registered.

3.png

Authentication

Authentication for single-page applications must be added within the app registration.

4.png

When registering the single-page application, use the redirect URLs in the following scheme:

  • https://%HOST%/MsalAuth.html
  • https://%HOST%/WebWave.html

Enter your provision for the placeholder "%HOST%", e.g. "https://wave.example.com/MsalAuth.html". It is also important to set the entry "http://localhost" here, without which no connection via MSAL is possible. However, it depends on the port that is set for the server. If the server listens to the default port 80, setting the entry "http://localhost" at this point is correct. If the server runs over port 443, the entry must be created as a forwarding (see figure below).

Enter the URLs for the production, test and development systems separately if these are also to be authenticated via MSAL, e.g. :

https://my.address-dev/MsalAuth.html
https://my.address-dev/WebWave.html

https://my.address-test/MsalAuth.html
https://my.address-test/WebWave.html

https://my.address/MsalAuth.html
https://my.address/WebWave.html

In addition to the single-page web application, the following redirects must also be selected for mobile and desktop applications. Mobile forwarding is used, among other things: also required for the Սupervisor Օption 'redirectURL' (see 'Necessary Rules').

If waveware UX is used, a redirect for UX must also be stored in the settings. This link must be specified as a complete, parameterized call: "https://my.address/ux.html?installid...ig&autologin=1"

The forwarding to 'localhost' is also entered here, provided that the application is encrypted by waveware via SSL and port 443.

5.png

For the waveware Android app, the signature hash value of the application must be created in the Microsoft Entra ID registry. If using the default app, you can apply the following default hash value: "LEZ7iOI8lWB+MtK6/CU+57fm4W0="
The forwarding destination to be stored is accordingly: "msauth://com.loyhutz.waveware/LEZ7iO...K6/CU+57fm4W0="

If you use your own signature in the app, you must use an appropriately adapted forwarding destination with your own hash value.

Certificates & Secrets

No certificate or secret should be stored for the standard app registration.

API Permissions

The following API permissions are required for authentication via MSAL:

6.png

Completion of Registration

After setting up the app registration, please have the following data ready to store in the waveware package 'MSAL-Basis' (1931):

  • Client ID ("Application ID (Client)")
  • Tenant ID (“Directory ID (tenant)”)

Both IDs can be found under 'Overview':
10.png

Necessary Rules

Setting up the rules in the waveware modular system consists of two stages for MSAL Single Sign-On:

  1. Rule: 'Security.Authenticate'
    Such rule is used to decide which users should be signed in using MSAL Single Sign-On. A redirection must take place with the 'CreateMSALRedirectAuthenticationRuleResult' or 'CreateMSALRedirectAuthenticationRuleResultExtended' building blocks.
  2. Rule: 'Security.MsalMapAuthenticate'
    In such  rule, the MSAL user is assigned to a waveware user. It is possible to create new users during authentication.

These rules are supplied as system rules in the 'MSAL Basis' (1931) package and may only need to be slightly adapted to the attribute to be mapped. The package comes with two Supervisor Options (under "Waveware Module / SSO / MSAL Basis (1931)"). An option in which users can be excluded from authentication via Single Sign-On and another to store the access data to the Microsoft Entra ID:

13.png

14 (1).png

In addition, Single Sign-On with MSAL can be switched on and off centrally via another Supervisor Option. The setting is made via “Waveware Module / SSO / MSAL Basis (1931) / General”.

15.png

If the option is deactivated, normal authentication is carried out and the authenticate rule of the installed Single Sign-On package is not used. This can be for example, always helpful when several system environments are running in parallel (e.g. a development, test and a production system) and these are linked to each other with transport orders. Since Single Sign-On can only be activated for the productive system in this way and all other systems can be deactivated, there is no need to adapt the authentication rule with a query/condition for the current system.

The 'Authenticate' rule is always run through twice when logging in via Single Sign-On. The first time, the "fictitious" user from the client connection is given. The second time, the identified (mapped) user of waveware comes back as a result and the 'Authenticate' rule runs through without jumping back into the building block for the redirect. The client connection just mentioned takes place either by storing parameters in the .exe (see 'Hide Login Window for Single Sign-On') or by using the ClickOnce arguments if the clients are distributed via ClickOnce.

'Authenticate' Rule

If MSAL is to be used, 'Security.Authenticate' must usually be forwarded to MSAL. For this you usually use the building block 'CreateMSALRedirectAuthenticationRuleResult' or 'CreateMSALRedirectAuthenticationRuleResultExtended' (required for individual application registrations).

Depending on the type of login, you can evaluate the 'tokenSource'/'source' argument accordingly. To do this, the 'TokenSourcePicker' building block is used in a condition. In the building block, use e.g. "FatClient" to condition the login to the Windows Client, "Mobile" for waveware Mobile, etc. You can also handle users who log in via an interface (e.g. REST) ​​accordingly with "Webservice".
This differentiation of the login procedure is often necessary because e.g. different building blocks have to be used during the login.

To customize the system rule, open the System Rule Editor and navigate to the 'Security/Authenticate' rule in the 'MSAL-Basis' (1931) package.

Variant 1

In the following example, the login is set up without a Web Client or NETPROCESS (without mandatory registration in the Microsoft Entra ID portal). This variant is only possible if there is no separate Active Directory and the registration has to run via waveware.

1 (1).png

The example rule checks whether the registration type is 'MobileCompact', i.e. a Mobile Client, or the Windows Client and whether the rule call is not already due to another forwarding ('FromSaml'). Furthermore, the supervisor is excluded from the MSAL login so that he can continue to use this access without a user comparison. In this case, the 'CreateMSALRedirectAuthenticationRuleResult' building block is called, which generates an 'AuthenticationRuleResult', which in turn initiates the redirection to the MSAL authentication dialog after the rule has been exited.

Variant 2

In the following example rule, the supervisor is first excluded from the login, in order to use then the 'CreateMSALRedirectAuthenticationRuleResultExtended' building block to generate an 'AuthenticationRuleResult', which in turn triggers the forwarding to the Microsoft authentication library. The stored IDs of the application in the Azure portal are required in this building block. The first input is a mandatory input and requires the ID of the Azure application. It is also recommended to set the 'Client ID' and a 'Mobile Redirect' (Android/iOS). All three fields are usually pre-assigned with the Supervisor Options and only need to be adjusted under the Supervisor Options. 

9.png

'MsalMapAuthenticate' Rule

After authentication has taken place via the MSAL authentication dialog, the rule 'Security.MsalMapAuthenticate' is called in order to map the data transmitted by the Microsoft Identity Platform to waveware data.

Please note that the URL of the waveware server must be specified correctly in the data world settings.
17.png
This is the only way to ensure that the correct token source (WebWave, CustomPage, FAT client) can be output and called in the mapping rules.

Open the builder and navigate to the 'Security.MsalMapAuthenticate' rule in a package.

2.png

The example rule extracts the value with the key "mail" from the transmitted JObject ('identity'). The identification usually corresponds to the email address of the user. The next step is to check whether this attribute matches the specified email address. The next step is to check whether this attribute matches the specified email address. In the positive case, an object is created with the 'CreateWaveUserMappingExtended' building block, which is used to log in to waveware. In contrast to the 'CreateWaveUserMapping' building block, the transferred "tokenSource" can still be submitted here.

Alternatively, you can use any other attributes (from Microsoft Entra ID) of the transmitted JSON (argument 'identity') for authentication or make an assignment based on field contents, e.g. based on the fields 'Email' of the spatial object type 'Staff'.

Hide Login Window for Single Sign-On

The advantage of single sign-on, reducing the steps involved in software login, must then be set in the client. Subsequent storage means that the user no longer sees a login screen, but starts the application directly.

The further procedure depends on which waveware client you want to provide single sign-on for:

  1. waveware Windows Client
    The waveware Windows Client has to be started with certain command line parameters in order to automate the login. To do this, create a link to waveware.exe (installed in the default path "C:\Program Files\LoyHutz\waveware\waveware.exe") in which you expand the target with parameters. The following information is required: "-servername Myserver.local -installid MyDataWorld -username any -password any -clientid Client", where you have to adapt the server name of the waveware server and the data world. What is transmitted as 'username' and 'password' is not relevant at this point, since the login into the waveware server is usually carried out using MSAL in the 'Authenticate' rule. So you can enter any string of characters here. More information about parameters: 'Command Line Call waveware'.

    11.png
    Note that values ​​containing spaces or special characters must be enclosed in quotes.
  2. waveware Web Client
    With the Web Client, the login mask can also be hidden by adding parameters to the URL. Any username must also be entered here, otherwise the login mask cannot be skipped (mask is displayed and the missing username is criticized).
    • Default call: "https://MyServer.local/WebWave.html"
    • Access with single sign-on: "https://MyServer.local/WebWave.html?installid=MyDataWorld&user=ny&autologin=1"
  3. waveware Custom Pages
    Adjusting the link on the Custom Page behaves in the same way as on the Web Client. The call must also be given a parameter to which package the single sign-on is to be forwarded. By default, the parameter 'redirect' ("redirect=1589/Navigation.erb") is used for this.
    • Default call: "https://MyServer.local/CustomPageLogin.html?redirect=1589/Navigation.erb"
    • Call with Single Sign-On: "https://MyServer.local/(MyDataworld)/1589/CustomPageLogin.html?installid=MyDataworld&mandantId=1&redirect=1589/Navigation.erb&username=sso&autologon=1"
  4. waveware UX
    As with the Web Client and Custom Pages, waveware UX uses a parameterized call to apply Single Sign-On with MSAL.
For a ClickOnce installation, ClickOnce arguments can be passed for SSO login. The parameters match those of the Windows Client, e.g.:
"-installid MyDataWorld -servername MyServer.local -username any -password any -clientid 1"
12.png
Please note that the client must be specified with ClickOnce.
Please note that the URL of the waveware server must be specified correctly in the data world settings. This is the only way to ensure that the correct token source (WebWave, CustomPage, FAT client) can be output and called in the mapping rules.
If secure client connections are deactivated, a message "non-encrypted connection to the waveware server" appears in the waveware Windows Client. This message indicates a security flaw and can only be prevented by enabling secure client connections. More information: 'Client Connections'.

Application

Once set up, authentication via MSAL is ready to use. The following scheme shows the login process:

7.png

The waveware login is passed on to Microsoft Entra ID (formerly Azure Active Directory) and authentication takes place. Here the user enters their normal access data for Microsoft login. When logging in, an MSAL token is generated that is automatically cached so that the user does not have to authenticate again with a username and password the next time they log in.

In the waveware Windows Client, the token is cached by default in a file located in the path “%LOCALAPPDATA%\LoyHutz”. This default directory can be changed when starting waveware from the command line with the following parameter:

-msalTokenCacheFolder C:\waveware\CacheFolder

If re-authentication is required every time you log in, the reason may be that for example, user profiles are deleted centrally or they are only saved temporarily. This often applies to terminal servers. Also in Citrix environments in which the waveware client is running on different servers, the problem can occur.

Prevent deleting the cache file or use the command line parameter to relocate the directory to avoid frequently repeated authentication.

Single Sign-On with MSAL
29 Changes
154 Views