Single Sign-On with SAML

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 fingerprint of the SSL certificate is required again for later setup, more information: 'File 'saml.xml''.

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

Directory 'Saml'

The further setup is done via several configuration files, that are used per data world. In the data directory of a data world, the directory 'Saml' must be located. The directory is available in the delivery state directly with sample files.

The directory contains the following files and sub-directories:

• saml.xml
  Contains the configuration of the SAML interface, that for example defines end points and entity ID.
• IdpMetadata
  In the directory 'IdpMetadata', the meta data of the Identity Provider (IDP) must be stored. They are recalled in form of a 'metadata.xml' by the Identity Provider and stored in this directory. An existing file is to be replaced, then there should be only one IDP in general. To renew the metadata in this directory, restart the waveware server.
• sp-cert.pem / sp-key.pem
  These files can be specified for signing during the configuration in the 'saml.xml'.

File 'saml.xml'

The saml.xml file is the main configuration file of the interface. This file must be located in the previously created 'Saml' directory. The minimum configuration of the saml.xml is shown as follows.

The following needs to be adjusted by default:

• Service provider ID (id)
• URL (server)
• Fingerprint of the SSL certificate (findValue)
• InstallID of the endpoints (localPath)
• 

If an additional certificate with a public key that cannot be assigned is found in the log file, the login will be blocked. This certificate must then also be trusted in the saml.xml. The entry is structured as follows:

Further configuration options are possible using the following parameters.

The following attributes can optionally be specified in the 'WaveSaml2' element of this file:

• metaDataLifetime
  To define the validity of the metadata, a maximum period of time can be specified using the 'metaDataLifetime' attribute. For one year for example, the following are given:
  <WaveSaml2 metaDataLifetime="365.00:00:00">
• disableCertificateValidation
  If the 'wavewareServerSaml.txt' log file contains the following entry: "The certificate that was used has a trust chain that cannot be verified", it must be ensured that the certificate that is used on the IdP is classified as trustworthy by the waveware server. If the waveware server is to accept any certificate, the entry in the SAML.xml can be used to switch off the check, e.g. <WaveSaml2 disableCertificateValidation ="true">. However, for security reasons this is expressly not recommended!
• allowUnsolicitedResponses
  Entries in the SAML log with a reference to an "InResponseTo attribute" or an entry such as "Possible replay attack detected" can be responded to with the entry <WaveSaml2 allowUnsolicitedResponses="true">.
  The reason for this may be a lack of replay information from the AD in the communication between waveware and the IDP. It is triggered for example, due to a timeout during a login or other timed keys that no longer match when the request meets the response.

The element 'WaveSaml2' takes on further elements to set waveware as a service provider (SP). The 'serviceProvider' element contains two attributes for this purpose, which must be assigned as follows:

• id
  Unique value, that identifies the Service Provider (SP) versus the Identity Provider (IDP). Only URLs are valid, as shown in the example above.
• server
  Takes the address, under which the Service Provider is accessible both for the Identity Provider and for the user.

Within the elements 'serviceProvider', another element ('signingCertificate') exists, that specifies, with which certificate and key the Service Provider should sign its queries to the Identity Provider. The signing can be done either with a 'PEM' certificate and Key (is to be seen in the above example) or per Windows Certificate Store.

In the environment with the self-signed certificates (e.g. a test environment), it is not sufficient to implement the certificate test via the 'metadata.xml'. In addition, the certificate of the IDP with the names 'idp-signing.crt' must be imported from the installation directory (e.g. 'C:\Program Files\Shibboleth\IdP\credentials') to the Service Provider via the certificate management of Windows.

Another element 'endpoints' under 'serviceProvider' contains the valid end point of the waveware Service Provider. Three types are supported, that build a sub-element and a typed via the attribute 'type':

• SignOn
  Starts the login process and receives SAML Assertions from the Identity Provider (IDP). Here "WaveSaml.sso/%DataWorld%/Login" is to be specified as 'localPath'. Replace "%DataWorld%" with the name of the current data world. The attribute 'redirectUrl' receives the redirection destination, that always aims for the page "0/LoggedIn.erb", if it is not specified and is not treated in the rule. The redirection destination "~/Login" is to be specified by default.
• Logout
  Enables the central logout. 'localPath' is "WaveSaml.sso/%DataWorld%/Logout", whereby "%Data world%" is to be replaced by the name of the current data world at this point. The typical redirection destination ('redirectUrl') is assigned with "~/Logout".
• Metadata
  Delivers the clients of the Service Providers (SP), that is forwarded to the Identity Provider (IDP). The attribute 'localPath' should be found with the "WaveSaml.sso/%DataWorld%/Metadata" ("%DataWorld%" which is replaced by the current data world name).

In the optional element 'metaData' you can store information that should be included in all 'metadata.xml' files. 'metaData' can e.g. B. have the following sub-elements:

After you have completely configured and saved the 'saml.xml', restart the waveware server and recall the meta data (in form of a 'Metadata.xml') of waveware (SP) at the end. Open the URL "https://%wavewareServer%/WaveSaml.sso/%Datenwelt%/Metadata", e.g. "https://waveware.domain.tld/WaveSaml...eware/Metadata" and forward the file to the IDP. The provider of the IDPs must restart the service 'Shibboleth 3 IdP Deamon' after the transfer of the metadata.

Every change of the 'saml.xml' requires a new recalling and determination of the metadata.

Signing with PEM Certificate

If you want to use a PEM (Privacy Enhanced Mail) certificate when signing, you must extend the 'signingCertificate' element when configuring the 'saml.xml' with the following attributes:

• certPath
  Receives the path to the PEM certificate file. If the input is not a complete path, it is assumed that the input was relative to the subfolder 'Saml' in the data directory
• keyPath
  Path to the PEM-Key-File. Here too a relative path to the subdirectory 'Saml' is possible..

When inputting the path to the certificate file must be considered, that the (service) user, that executes the waveware server, has read access authorization to the files. Otherwise the files cannot be used.

Example for the usage related to path:

<serviceProvider id="http://waveware.localhost.com/WaveSaml.sso" server="http://waveware.localhost.com">
    <signingCertificate certPath="sp-cert.pem" keyPath="sp-key.pem" />
    <endpoints>
        ...
    </endpoints>
</serviceProvider>

An example for the usage with absolute path:

<serviceProvider id="http://waveware.localhost.com/WaveSaml.sso" server="http://waveware.localhost.com">
    <signingCertificate certPath="C:\keys\sp-cert.pem" keyPath="C:\keys\sp-key.pem" />
    <endpoints>
    ...
    </endpoints>
</serviceProvider>

Signing with Certificate Store

Alternative to the usage of the PEM Certificate, the Windows certificate store can be used. The 'signingCertificate' element is to be extended with the following attributes during the configuration of the 'saml.xml':

• x509FindType
  Specifies the type of the certificate search. For example, "FindBySubjectDistinguishedName" can be used. Then, a character string must be listed in the 'findValue' attribute for the Find method, that displays the defined subject name of the certificate. Another method is "FindByThumbprint", where 'findValue' must then be the string representing the certificate thumbprint.
  Further methods can be found in the MSDN. 
• findValue
  Specifies the value, which is to be searched for together with the method specified under 'x509FindType', e.g.: "CN=MySPCert".
• storeLocation
  Specifies, where the certificate is to be searched for. Possible input is "LocalMaschine" or "CurrentUser".
• storeName
  Specifies which certificate store is to be used in the specified 'storeLocation'. Possible input (Default "My"):

  Value	Description
  AddressBook	Certificate store for other users.
  AuthRoot	Certificate store for third-party provider-certificate authorities.
  CertificateAuthority	Certificate store of interposed certificate authorities.
  Disallowed	Certificate store for suspended certificate.
  My	Certificate store for personal certificate.
  Root	Certificate store for trustworthy core-certificate authorities.
  TrustedPeople	Certificate store for direct trustworthy persons and resources.
  TrustedPublisher	Certificate store for direct trustworthy issuer.

The following example uses the "FindBySubjectDistinguishedName" method to search for the certificate with "CN=MySPCert" in the certificate store of the computer.

<serviceProvider id="http://waveware.localhost.com/WaveSaml.sso" server="http://waveware.localhost.com">
    <signingCertificate findValue="CN=MySPCert" storeLocation="LocalMachine" storeName="My" x509FindType="FindBySubjectDistinguishedName" />
    <endpoints>
    ...
    </endpoints>
</serviceProvider>

General

During the login via SAML, the end point 'SignOn' should be called. The end point forwards the user to the Identity Provider (IDP), that generates a login mask, as long as the user is not logged in yet. After the authentication is done, the user is forwarded back to the Service Provider (SP) and waveware triggers the rule 'Security.SamlMapAuthenticate'. This rule has the task to communicate waveware with the help of the SAML assertion sent by the Identity Provider (IDP), with which waveware user and authentication is to be executed.

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.

The default rule 'Authenticate' already provides a possible authentication for all clients. Normally no adjustments need to be made here. In the mapping rule, the parameter/link to the parameter that is returned by the IDP may have to be exchanged and assigned to the correct field ID of the waveware staff record.

Various application examples are listed below, which show, among other things, how the rules have been adapted to changed attributes.

Web and Custom Pages

For custom pages, the 'Security.SamlMapAuthenticate' rule must use the 'CreateSamlWaveMapping' building block and return the result of the building block. At the end, waveware uses the returned login names and the client ID during the login. If the authentication is successful, the user is either forwarded to the page that was submitted to the 'CreateSamlWaveMapping' building block or that was previously stored in the corresponding 'SingOn' endpoint element, in the 'redirect' attribute. If both entries do not give a value, the page "0/LoggedIn.erb" is forwarded.

Requests for the web client can also be processed in the same rule. For this, the building block 'CreateSamlWaveWebClientMapping' is to be used. In order to realize the simultaneous application of multiple targets (CustomPages and Web client) in one rule, the requesting URL has to provide a parameter 'redirect', e.g. "https://MeinWavewareServer/WaveSaml....direct=webwave". The parameter content stored in the request ("custompage" or "webwave" in the example below) is transferred to the rule in the argument 'redirectUrl' and can again be evaluated in a condition (or in the 'Switch' example) that ensures that the correct rule section returns a relevant mapping. The parameter 'redirect' and the associated rule adaptation is optional. If only the web client is to be used, you only need to create a mapping with the 'CreateSamlWaveWebClientMapping' building  block.

The ''GetAssertionAttributeFriendlyNameList' building block can be used to request the attributes provided by the IDP. Ideally, this will return the staff ID, which is kept in waveware. In the following example, the IDP will provide you with the email address that can be used as a unique attribute and is removed from the assertion using the 'GetAssertionAttributeByName' building block. On the basis of the determined email address, the corresponding staff record can be found by means of the 'GetRecord' block and passed as a value to the 'CreateSamlWaveMapping' or 'CreateSamlWaveWebClientMapping' building block:

The example also shows how a forwarding via the 'CreateSamlWaveMapping' building block is configured. It is not necessary to specify the entire target URL, but only the part following the domain specification (page path). The URL is automatically merged in the background.

If there are several Identity Providers (IDP), waveware will first forward to a selection page, where users can select the IDP they want to use themselves. If this selection should not be offered to the user, but given to the IDP directly in the initial call, the URL must be extended by the parameter '? Cidp ='. The following example shows a call with a predefined example IDP:

1https://Server-FQDN/WaveSaml.sso/Installation/Login?cidp=https%3A%2F%2Fbeispiel.idp.waveware.de%2Fidp%2Fshibboleth

The parameter '?Cidp =' must be assigned so that it contains the 'EntityID' of the IDP in URL-encoded form. The required encoded form of this ID can be generated via any free web pages on the Internet.

Windows and Mobile Clients

Unlike on the web and custom pages, SAML for Mobile and Windows clients cannot be accessed via a special URL, but must be integrated into the existing login process by adapting the 'Security.Authenticate' rule.

The rule serves the purpose of deciding which persons are authorized to log in using SAML, e.g. all persons who use the waveware Windows Client or have certain names/roles. To do this, the 'CreateSamlRedirectAuthenticationRuleResult' building block must be integrated in order to create a forwarding to the SAML IDP.

The forwarding takes place in the Windows/Mobile client in an integrated browser window that displays the SAML login window of the IDP and enables login with personal information. If the login was successful, the 'Security.SamlMapAuthenticate' rule is called in the waveware server. As with the Web client or custom pages, this rule has the task of using the SAML assertion sent by the identity provider (IDP) to tell waveware which waveware user and client should be used for authentication. If the rule is also to deal with Web clients and/or custom pages, a distinction must be made because different building blocks must be used. The 'tokenSource' argument contains the correct source for this purpose and can be compared with a value of the 'TokenSourcePicker' building block within the rule.

The best way to make an assignment is to use the email address, which can be used as a unique attribute and extracted from the assertion using the 'GetAssertionAttributeByName' building block. Based on this email address, a suitable waveware staff record is then determined and login data for waveware is returned using the 'CreateWaveUserMappingExtended' building block.

With the 'GetAssertionAttributeNameList' building block you get a list of all attributes for which mapping would be possible. In the example shown for the 'SamlMapAuthenticate' rule, the attribute in the 'Let' building block (input 0) is only used to read out the attribute value. Here the attribute is returned as a link and is set in 'GetAssertionAttributeByName' at the top left.

A comparison is then made with the login name, which is required for unique registration in waveware.

If a login data could be determined using the rule, the waveware server will carry out an authentication. Here, the rule 'Security.Authenticate' is run again. It is therefore important to integrate the rule parameter 'sso', which is only true if the login is via single sign-on, into the authenticate rule.

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 (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 into the waveware server is usually carried out using SAML 'Authenticate' (see 'Windows and Mobile Clients'). So you can enter any character strings here. More information about parameters: 'Command Line Call waveware'. 
   
   Remember 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
   Customizing 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: "http://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.
   • Standard call: "https://MyServer.local/ux.html"
   • Call with Single Sign-On: "https://MyServer.local/ux.html?insta...ig&autologin=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 client must be specified with ClickOnce.

Authentication via IDP

After successful setup, waveware forwards the login to the identity provider or directory service (e.g. Active Directory) and authentication takes place. Here the user enters their normal access data for the directory service. This authentication usually does not have to be repeated every time you log in, as caching takes place automatically.

If authentication is still required every time you log in, the reason may be that for example, user profiles can be deleted centrally via IT/network administration or only saved temporarily. This often applies to terminal servers, for instance.

The caching is done in a file 'wavewareToken.cache', which is located in the path "%LOCALAPPDATA%\LoyHutz". Prevent deletion of this file to avoid frequently repeated authentication (e.g. via email address from the Active Directory).

Login with Deep Link

In the waveware Web, it is possible to display a specific transaction or a specific object to the user directly after the login via Single Sign-On. This is done via parameters in the link, a 'ShowCard' rule in the package and a building block exchange in the 'SamlMapAuthenticate' rule.

In the following example, the object "0101 test room" is to be displayed immediately after it is called:

1. Structure of the Link
   The "initRule" parameter is required in the link, which calls a rule that in turn should display the specific card record directly. The rule is also given arguments in the "initRuleArgs" parameter that describe the record to be opened:

   https://meinserver.de/WebWave.html?a...initRuleArgs=["defno",106,"search","e984302f-38b5-44b4-b796-c3bd6704bcb0"]

2. 'ShowCard' Rule
   The rule stored in the "initRule" parameter must either be created yourself or adapted using the package supplied. The following is an example of a 'ShowCard' rule:
   

   [!Script [[@defno #"System.Int32"] [@search #"System.String"]] #"System.Object" [base.CallBaseScript
       [CallScript "4731c493-cf4a-41f9-b277-7a8949749e9a22d956f1-da39-4451-890c-a8500a6b7f18" 
           @defno
           999
           @search
           [base.NewGuid]]]]

3. 'SamlMapAuthenticate' Rule
   Instead of 'CreateSamlWaveMapping' or 'CreateSamlWaveWebClientMappingOld' building block, the 'CreateWaveUserMappingExtended' building block should be used, that gets another return value and successfully passes the parameters through the login.