Single Sign-On with Kerberos

Last updated
Save as PDF

Overview

waveware supports three Single Sign-On (SSO) variants. It is recommened for the new installations to use Single Sign-On with MSAL or SAML, if possible.

If older waveware versions are updated, or if the technical requirements (ADFS, AzureAD integration) are not met, Kerberos/domain authentication can be used.

Kerberos authentication is the longest supported waveware Single Sign-On method. Only the Windows Client, the Web Client, the Custom Pages and from waveware 11.200.4928 also the CAD-DWG Client (not the DGN Client) are supported. The Mobile Client is not supported with this method.

Please note that Single Sign-On with Kerberos cannot be used through a reverse proxy. Instead, the server must be addressed directly.

Please note that Single Sign-On with Kerberos 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'. This feature also includes the 'Kerberos Basis' (1930) package, which you can install with the package manager after importing the new license file in order to apply standard rules with Kerberos that control authentication and mapping (further information at 'Necessary Rules'). The package is available from waveware 11.200.4370.37.

Setup

In order to be able to use the Kerberos authentication, minor adjustments in waveware and the domain controller are necessary. Bellow, it is described how to proceed here.

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 are to be able to log in via Kerberos Single Sign-On must exist in waveware as a personal record. The sample 'KerberosMapAuthentication' mapping rule uses the 'Domain user' field on the Staff card for synchronization.

The field must therefore be filled with the 'User Principal Name' (UPN). Alternatively, you can usually use another field for assignment.

Staff records can be prepared as follows, for instance:

If the staff status is "Active", you can log in via SSO
If the user access is "Direct", the login can also take place
If the 'Domain User' is entered, the synchronization can take place

Since the UPN is a Windows-specific setting, access via IOS (e.g. Apple IPad) requires a separate setup in order to be able to access the Web Client. You can read additional information in the external documentation: https://support.apple.com/de-en/guide/deployment/depe6a1cda64/web

If the system user 'SYSTEMHEARTBEAT' is set to 'Personal status' = "Inactive", no mapping can take place. In the event of an error, please check the user status and set it to "Active" if necessary.

Domain Controller

To use Kerberos authentication under Microsoft Active Directory, it must be ensured that the 'User Principal Name' (UPN) is used among all users in the domain.

Otherwise, be sure to enter this later, because waveware authentication is based on this name.

Activate Kerberos/Domain Support

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

Activate the option 'Enable Kerberos/Domain Support' and save the changes.

Necessary Rules

Setting up the rules in the waveware System Rule Editor consists of two stages for Kerberos Single Sign-On:

Rule: '0.Security.Authenticate'
Such a rule is used to decide which users should be logged on with Kerberos Single Sign-On. A redirect must be done with the 'CreateKerberosRedirectAuthenticationResult' building block.
Rule: '0.Security.KerberosMapAuthentication'
In such a rule, the User Principal Name (UPN) is assigned to a waveware user. It is possible to create new users during authentication.

These rules are supplied as system rules in the 'Kerberos Basis' (1930) 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 / Kerberos Basis (1931)"). An option in which users can be exempted from authentication via Single Sign-On and another to switch between the mapping methods "UPN (User Principal Name)" and "sAM Account Name":

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

If the option is disabled, 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 disabled, 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 determined (mapped) user of waveware comes back as a result and the 'Authenticate' rule runs through without jumping again 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

Usually 'Authenticate' is queried with which client the access of the user takes place. If the access is from the waveware Web Client or Windows Client, an authentication result is returned and if the authentication is positive, the Kerberos forwarding is carried out.

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.

The rule could be structured as follows:

[!Script [[@loginname #"System.String"] [@passwordHash #"System.String"] [@clientId #"System.Int32"] [@pwChanging #"System.Boolean"] [@source #"LoyHutz.Framework.Session.TokenSource,loyhutz.framework.lib"] [@sso #"System.Boolean"] [@fromSaml #"System.Boolean"]] #"System.Object" [if
    [base.And
        [base.Not
            @sso]
        [base.Or
            [str.SpecialEquals
                [base.ExplicitCastObjectToString
                    @source]
                [base.ExplicitCastObjectToString
                    [RightsApi_TokenSourcePicker 1]]
                null]
            [str.SpecialEquals
                [base.ExplicitCastObjectToString
                    @source]
                [base.ExplicitCastObjectToString
                    [RightsApi_TokenSourcePicker 2]]
                null]
            [str.SpecialEquals
                [base.ExplicitCastObjectToString
                    @source]
                [base.ExplicitCastObjectToString
                    [RightsApi_TokenSourcePicker 5]]
                null]]
        [str.SpecialNotEqual
            @loginname
            "Supervisor"
            null]]
    [RightsApi_CreateKerberosRedirectAuthenticationResult null]
    null]]

'KerberosMapAuthentication' Rule

The assignment (mapping), i.e. the synchronization of the user data with the waveware user, then takes place. For this purpose, 'KerberosMapAuthentication' is usually checked to see whether the user is present in waveware and can be assigned. If this is the case, a waveware session is started. Otherwise the login will not work and an error message will be displayed. In addition, it is also possible to create new users during authentication if they are not present in waveware.

Please note that user principal names ('User Principal Name' - UPN) must be maintained for all users who want to log in via Kerberos. Further information under 'Requirements' / 'Domain Controller'.

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.

A typical Kerberos mapping rule might look like this:

[!Script [[@tokenSource #"LoyHutz.Framework.Session.TokenSource,loyhutz.framework.lib"] [@clientId #"System.Int32"] [@upn #"System.String"] [@sAMAccountName #"System.String"]] #"System.Object" [|$a "Personalkennung" = [record.GetRecordNew2
    [VFMAPI_SelectTblNo 126 "DefFiles.Object.126"]
    null
    [VFMAPI_SelectFId 798 "FIds.Object.126.798"]
    @upn
    1
    null
    null
    null
    null
    null]| -> 
    [if
        [base.IsNull $a]
        null
        [SamlApi_CreateWaveUserMappingExtended
            [record.GetValue
                [VFMAPI_SelectFId 18545 "FIds.Object.126.18545"]
                $a
                null]
            @clientId
            @tokenSource]]]]

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:

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 (by default it is installed in the 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", whereby you must 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 to the waveware server is carried out with Kerberos in the 'Authenticate ' rule. So you can enter any character strings here. More information about parameters: 'Command Line Call waveware'.
Note that the service principal name is set up correctly, otherwise the error 'The target principal name is incorrect: Error in SSPI call.' can occur.

Note that values containing spaces or special characters must be enclosed in quotes.
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:443/WebWave.html"
- Access with single sign-on: "https://MyServer.local:443/WebWave.html?installid=MyDataWorld&user=ny&autologin=1"
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:443/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"

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"

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: 'waveware Server: Secure Client Connections'.

Set the Service Principal Name (SPN)

The network Kerberos authentication used in Single Sign-On requires that the client be provided with a ServicePrincipalName (SPN) to identify the service. Setting the service principal name is necessary so that the necessary rights are available to query other users.

The service principal name must be set for the waveware web server. Assuming the waveware web server is running at the following address: http://srv-http-00.test.local:10000 under the user account test). In this case, the following setting is made using the "setspn" application:

setspn -S HTTP/SRV-HTTP-00.test.local -U test

Another example:

Domain: test.unternehmen.de
Server: SRV1110
User: ADM110

The PowerShell or command line command would need to be composed like this:

setspn -S HTTP/SRV1110.test.unternehmen.de -U ADM110

The SPN identifies under which account a service is running. This is a requirement for the successful completion of the Kerberos login process.

This setting can only be set with a domain administrator account. A local administrator is not enough for this.

Single Sign-On with Kerberos

27 Changes

105 Views