enaio® gateway

enaio® • 11.10 »

enaio® gateway is a proxy that is used as the central authentication component for enaio® webclient and communications interface between the core services and microservices.

In live systems, enaio® gateway should always be protected by firewalls and reverse proxies. End-to-end SSL encryption for all components in the system is also possible.

The installation and configuration of NGINX are documented as an example.

Configurations are saved in the application-prod.yml file located in the ...\services\OS_Gateway\apps\os_gateway\config\ directory. There cannot be any other YML files in this directory, not even in subdirectories. Otherwise, enaio® gateway would merge this data at startup, which can lead to unwanted and corrupt behavior.

Configuration

enaio® gateway must be configured to set up the authentication method.

Authentication

It is possible to activate multiple login filters to authenticate enaio® webclient and enaio® webclient as a desktop application. If login fails with one filter, an attempt to log in using the next filter is made. The following order applies:

  • Session GUID
  • Form-based
  • NTLM
  • Basic

Enable or disable the login filter in the application-prod.yml configuration file which is located in the …\services\OS_Gateway\apps\os_gateway\config\ directory.

When using NTLM as the login filter, it is recommended that you set up the technical user login using the alternative LoginPipe. Depending on the login configuration, certain protective measures (tar pits) could otherwise delay or prevent the login of the technical user.

The URL address to enaio® gateway must be added to the 'Local intranet' zone in the Internet security settings when using NTLM authentication. 'Form-based' – form – must be disabled for automatic NTLM authentication. A further enaio® gateway installation is required for access from a different domain.

If a password confirmation is required for follow-ups, subscriptions, workflows, or a script by the user, then, by default, the user name and the enaio® password must be entered, even if NTLM/Kerberos authentication is enabled.

If NTLM/Kerberos authentication is used in combination with a login sequence, then the login types listed there will be used in that order for verification. If 'A' is entered there in the first position, then the Windows password can be used for the confirmations in enaio® client.

For enaio® webclient, the confirmation must be specifically configured.

The following applies to all clients that support NTLM:
If NTLM fails, 'Basic' will not be executed, even if it is enabled.

Settings for enaio® webclient

For enaio® webclient, the following addition is required in the ...\os_gateway\config\application-prod.yml configuration file in the ossecurity section:

ossecurity:
  exposedEndpoints: '/osweb/**'

'NTLM' also needs to be disabled there:

ntlm: {
  enabled: false
}

If 'NTLM' is enabled, then 'Basic' will not be executed, even if it is enabled.

Further enaio® gateway Installation

If enaio® gateway is configured for automatic NTLM authentication, then a further enaio® gateway installation is used for access from a different domain.

The installation takes place via the component setup located in the directory \Backend\Gateway if enaio® gateway is to be installed on a different computer.

Installations on the computer with the first installation can be performed as follows:

  • Copy the directory with the enaio® gateway setup and paste it to another directory on the computer with the first installation.

  • Open the command prompt as the administrator and change to the directory.

  • Run the following command: osgateway_setup.exe --registry 0

  • Specify a directory for the installation.

  • Specify another technical service name, another service display name, and a free port.

  • Open the command prompt as the administrator and change to the bin directory of the other installation.

  • Run the following command: service.bat install.

Then you can configure the new enaio® gateway service and start it.

Update enaio® gateway on computers with multiple installations as follows:

  • Copy the \Backend\Gateway directory of the installation data and paste it to another directory on the computer with the enaio® gateway installations.

  • Close the first enaio® gateway service.

  • Update the first enaio® gateway service via osgateway_setup.exe.
    The setup updates the first enaio® gateway service.

  • Update other enaio® gateway installations as follows:

    • Close the additional enaio® gateway service that is to be updated.

    • Open the command prompt as the administrator and change to the enaio® gateway setup directory.

    • Run the following command: osgateway_setup.exe --registry 0

    • Specify the directory for the additional enaio® gateway installation.

    • Specify the technical service name and port in exactly the same way as for the previous installation of the other enaio® gateway service.
      The installation creates a backup directory with the data from the former installation.

    • Copy the configuration files from the os_gateway\config directory of the backup directory.

    • Add the configuration files to the os_gateway\config directory of the new additional enaio® gateway installation.

  • Then restart the enaio® gateway services.

Always keep all enaio® gateway services up to date.

You can uninstall a gateway by entering the following into the command prompt as the administrator: sc delete <gateway-technical_name>. You must close the service before doing so.

An additional step is required to update additional installations of enaio® gateway from version 10.10 to version 11.0. After updating an installation with the parameter registry 0, execute the following command in the administrator command prompt:
..\jdk\bin\java.exe -jar .\gatewayupdater.jar "gateway-technical_name".
The technical service name of the additional enaio® gateway installation is specified in quotation marks.

Authentication via HTTP Header

The login can also be enabled via the HTTP header.

To do so, the following entry is required in the configuration file ...\os_gateway\config\application-prod.yml in the section ossecurity:

header: {
  enabled: true,
  name: 'X-User'
}

NTLM must also be disabled:

ntlm: {
  enabled: false
}

The specified users are not checked. For this reason, this login method should only be used in combination with other security measures.

HTTP Header – Length Limitation

The request header is limited to a length of 8,192 bytes by default. The maximum length can be changed via the …\os_gateway\config\application-prod.yml configuration file.

A length change is required in the context of Kerberos authentication.

Example: proxy.max-http-header-size: 49152

Authentication with Kerberos

Kerberos authentication is a secure alternative to NTLM authentication. As with NTLM, users with an NT domain session can log in to enaio®.

If Kerberos authentication is active, then the settings of the other login methods are ignored. If it is necessary to register an NT user from outside the NT domain, there is only one web form left that the user can use to log in using NT login data.

Requirements

The following requirements must be met:

  • Active Directory synchronization between the NT domain and enaio®has been carried out
  • a configured Windows domain (in the example: 'TESTDOMAIN.ORG')
  • A host name (SPN) via which enaio® gateway can be accessed (in the example: 'enaio.testdomain.org')
  • administrative access (in the example using the NT account 'enaioadmin') to the domain controller to call the 'setspn' and 'ktpass' tools
  • The HTTP header length limit was changed.

Domain Configuration

Perform the following steps:

  1. Register SPN in the domain.

  2. Submit the following call in an administrative shell:

    setspn -A HTTP/enaio.testdomain.org enaioadmin

  3. Export the registered SPN to a keytab file:

    ktpass /out c:\enaioadmin.keytab /mapuser enaioadmin@TESTDOMAIN.ORG /princ
    HTTP/enaio.testdomain.org@TESTDOMAIN.ORG /ptype KRB5_NT_PRINCIPAL /crypto All /pass enaioadmin_password

    • The file does not necessarily have to be on the C: drive and can be assigned any name.
    • The password transferred at the end must correspond to that of the NT account 'enaioadmin'.

  4. enaio® gateway must be running with the user account as the service for which the SPN was set (see no. 1.)

Configuring enaio® gateway:

In the application-prod.yml microservices configuration file, add the following block to the logon procedures in the ossecurity section:

ossecurity:
  kerberos: {
    enabled: true,
    servicePrincipal: 'HTTP/example.testdomain.org@TESTDOMAIN.ORG',
     keytabLocation: 'c:/enaioadmin.keytab'
  }

servicePrincipal must conform to the format shown in the example. The log must be specified as HTTP and not as HTTPS, even if enaio® gateway is configured for SSL.

keytabLocation is the path to the exported keytab file; slashes (/) must be used as the path separator.

enabled: (true/false) defines whether Kerberos authentication is active. If Kerberos authentication is active then the other login methods – Session-Guid, Simple, Form-based, NTLM, Basic – are ignored.

IP Filters

You can configure what incoming IP addresses can access the services by specifying them in the configuration file ...\os_gateway\config\application-prod.yml.

The default setting permits access by all IP addresses: trusted.ipPattern: '.*'

The configuration is similar to the configuration for the microservices.

Distributing Dashlets

A web application server or enaio® gateway can be used for distributing dashlets.

To distribute dashlets via enaio® gateway, specify the pages for dashlets in the …\services\OS_Gateway\apps\os_gateway\public directory. Make sure that you assign the dashlets unique names so that no existing application with the same name is overwritten.

URL Encryption

URLs can be provided by the administrator for calling up core services and enaio® webclient. Sensitive data can be encrypted in URLs such as this.

User name and password can only be encrypted in a URL if 'Basic' is enabled as a login filter.

To enable enaio® gateway to process calls with encrypted data sections, you will need to edit the application-prod.yml configuration file located in the \services\OS_Gateway\apps\os_gateway\config directory.

The file contains the following section:

urlEncryption.osCryptoProvider.enabled: false
urlEncryption.vigenereCryptoProvider.enabled: false
urlEncryption.vigenereCryptoProvider.key: '~secret_~secret_~secret_~secret_'
urlEncryption.tokenPrefix: '(('
urlEncryption.tokenSuffix: '))'
urlEncryption.urlAuthentication: false

To enable encryption, set the required values to 'true'.

  • urlEncryption.urlAuthentication

    • Enables encryption.

  • urlEncryption.osCryptoProvider.enabled

    • Encryption according to the Rijndael procedure. This method is also used in earlier versions of enaio®. A data section may not contain more than 128 characters.

  • urlEncryption.vigenereCryptoProvider.enabled

    • Encryption according to the Vigenère procedure – not compatible with earlier versions of enaio®.

    A data section may not contain more than 32 characters. The key must be specified (urlEncryption.vigenereCryptoProvider.key) and be precisely 32 characters long.

  • urlEncryption.tokenPrefix/ urlEncryption.tokenSuffix

    • Encrypted sections must be enclosed between a prefix and a suffix.

Data section can be encrypted by calling up the url-cipher-tool.jar application. The program can be obtained via the Service Portal in the 'Tools' area.

The data section for encryption is transferred to the application via the following console call. Example:

java -jar url-cipher-tool.jar -o -e -i data section

The encrypted data section is output on the console.

The program requires the Java Runtime Environment.

Encrypted data sections must be enclosed in the URL according to the specified prefix and suffix values.

Parameters for the url-cipher-tool.jar call

Parameter

Function

-d (--decrypt)

Mode for decryption

-e (--encrypt)

Mode for encryption

-o (--oscrypto)

Rijndael method with a fixed key

-v (--vigenere)

Vigenère method

-k <arg> (--key <arg>)

Key to be applied (only with -v)

-i <arg> (--input <arg>)

Data section to be processed
-s <arg> (--enaioServerUrl <arg>) URL of enaio® server for testing an encrypted user password
-u <arg> (--enaioServerUser <arg>) User to test the encrypted user password

Technical Users – Encrypted Passwords

The password can be specified in the …\os_gateway\config\application-prod.yml configuration file as encrypted. It must be set in simple quotation marks.

The password can be encrypted via a call of the url-cipher-tool.jar application (see above).

The Rijndael method must be used for encryption.

CORS Access

Cross-Origin Resource Sharing (CORS) is a mechanism enabling cross-origin requests for web browsers or other web clients. This kind of access is normally prohibited under the same origin policy. CORS is a compromise in favor of greater flexibility in the Internet while taking into account the highest possible security precautions.

The cors.enabled: true property must be added to the application-prod.yml configuration file in order to successfully transmit asynchronous JavaScript requests (Ajax) from a web page (such as http://customer.example.com to enaio® gateway with a different domain (for example, http://<gateway>:80)). This will authorize all website hosts for CORS access.

The configuration file is found in the following directory:

\services\OS_Gateway\apps\os_gateway\config

Number of Connections

High loads to enaio® gateway may lead to the 'Too many requests running' error message. It is not possible to predict this message, because it depends on what exactly the users in enaio® webclient are doing and whether other applications are accessing enaio® gateway.

enaio® gateway is preset to allow up to 50 concurrent open connections. Open sessions for any given point in time can be significantly more or less, depending on the actual load.

If you encounter this error message, then you can change the default via the configuration file …\os_gateway\config\application-prod.yml.

Append it with the following line:

proxy.maxParallelConnections: value

The maximum value should not be greater than '100'. If the error message continues to occur, then it may be necessary to perform another installation of enaio® gateway.

GZIP Compression

GZIP compression is enabled for enaio® gateway by default. The compression can be changed or disabled using the application-prod.yml file located in the \OS_Gateway\apps\os_gateway\config\ installation directory.

Default settings:

tomcat:
  compression: 'on'
  compressableMimeTypes: 'application/json,application/xml,text/html,text/xml,text/plain'
  compressionMinSize: 128
  serviceCompression: true

Logging

enaio® gateway logs according to the settings in the logging.xml file located in the \OS_Gateway\apps\os_gateway\config\ installation directory.

Integrating Customer-specific Services

Services that are not installed via enaio® service-manager must be integrated using the application-prod.yml configuration file located in the \OS_Gateway\apps\os_gateway\config\ installation directory.

enaio® coLab must also be integrated, if it is installed.

Example:

proxy:
  services:
    endpoints:
    - endpoint: {
        name: service_1,
        url: 'https://<server>:<port>/service_1'
      }

The name of the service and the address are specified.