enaio® gateway
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. This removes the need for HTTPS and TSL configuration.
The installation and configuration of NGINX are documented as an example.
Configuration
enaio® gateway must be configured to set up encrypted data transfer (HTTPS) and the authentication method.
HTTPS
Set up the data transfer via HTTPS in the following way:
- Create a key and a (self-signed) certificate in the keystore of the application server. You can find instructions under:
http://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html
- Set the standard port of the application server to the HTTPS standard port.
To do so, start the application manager enaio blue gatewayw.exe in the …\services\OS_Gateway\bin directory, and set the –server.port=443 on the Startup tab.
- Enable data transfer via HTTPS in the application-prod.yml configuration file that is located in the …\services\apps\os_gateway\config directory. It can be edited using any editor.
- Add the following section to it:
https: {
enabled: true,
keyAlias: enaio,
keystorePass: optimal,
keystoreFile: 'config/gw_keystore'
}
The parameters have the following meaning:
Parameter |
Description |
---|---|
enabled |
Enables data transfer via HTTPS |
keyAlias: |
Keystore name |
keystorePass |
Password for the keystore user |
keystoreFile |
Directory which contains the keystore file |
Single quotation marks are required for values containing special characters. |
- Save and close the file.
The data transfer via HTTPS is set up.
If you want to use a self-signed SSL certificate in enaio® gateway, you will need to export its root CA certificate on all clients to the trusted root certification authorities. If not, the certificate will not be considered trustworthy by all clients and the attempt to set up a connection, e.g., from enaio® webclient, will fail.
Authentication
It is possible to activate multiple login filters for the authentication of 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
Apart from the 'simple' login filter, which should only be used for a purely technical login, all login filters are enabled by default.
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.
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 in enaio® webclient for follow-ups, subscriptions, workflows, or a script by the user, then the enaio® user name and the enaio® password must be entered or the login must be specifically configured if NTLM authentication is enabled.
If NTLM fails, '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 enaio® setup if enaio® gateway is to be installed on a different computer.
You cannot perform installations on the computer with the first installation using the enaio® setup:
-
Copy the OS_Gateway directory to the computer from the directory of the installation data \Win32\Disk1\Services\.
-
Perform the following console call from the directory: setup.bat attended de install.
-
Enter a different service name, service display name, and port.
-
Configure the authentication via the application-prod.yml configuration file.
Activate only 'ntlm' and 'form', for example.
Only the last installation is updated in each case when updating via the enaio® setup or a enaio® gateway hotfix. Further installations must be updated manually by copying the os-gateway-app.jar file from the directory of the updated installation to the corresponding directories of further installations.
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'
}
In addition, NTLM must be disabled.
ntlm: {
enabled: false
}
The specified user is not checked. For this reason, this login method should only be used in conjunction with a IP Filters that only allows messages from trusted sources.
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:
- Register SPN in the domain
- Submit the following call in an administrative shell:
setspn -A HTTP/enaio.testdomain.org enaioadmin
- 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'
- 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 (see 'Dashlets in enaio® client').
To distribute dashlets via enaio® gateway, file 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.
To enable enaio® gateway to process calls with encrypted data sections, you will need to edit the application-prod.yml configuration file.
The configuration file is found in the following directory:
\services\OS_Gateway\apps\os_gateway\configThe 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. It is located in the …\components\ directory of the installation data.
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 Java Runtime Environment is needed for operation.
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 |
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).
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://kunde.beispiel.de to enaio® gateway with a different domain (for example, http://<gateway_server>: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\configNumber 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.