Contents
| Table of Contents | ||
|---|---|---|
|
Introduction
The Ubisecure SSO configuration files use a macro language that can, for our purposes, be described in the following way:
...
- The variable compile.dir is the base directory of the Ubisecure SSO installation, e.g., C:\Program Files\Ubisecure\ubilogin-sso\ubilogin.
Processing suffixes
Variable suffixes in the macro language may or may not contain special processing rules. If a variable ends with a special processing suffix, the preceding string is evaluated recursively and then the final processing suffix is applied to the current value. Processing suffixes are, as follows:
| Suffix | Description | Example | Produces |
|---|---|---|---|
| .host.dn | This can be appended to a variable that contains a fully qualified domain name (FQDN). Appending the suffix will transform the variable to a X.509 Distinguished Name. | uas.url = https://www.example.org:8443/ | uas.url.host.dn→ dc=www,dc=example,dc=org |
| .url.host | This can be appended to a URL and it will parse the FQDN from the URL string. | uas.url = https://www.example.org:8443/ example = @uas.url.host@ | example → www.example.org |
| .base64 | This suffix can be appended to any text string. It will take the original text and base64 encode it. | uas.url = https://www.example.org:8443/ example = @uas.url.base64@ | example → aHR0cHM6Ly93d3cuZXhhbXBsZS5vcmc6ODQ0My8= |
| .password | Appending this suffix to any variable, will cause the value to be autogenerated if it is left empty. Non-empty variables will be preserved as-is. Generation will ensure that the generated 24-character string will hold following character classes:
The generated passwords are reduced so that the do not contain letters or numbers that can easily be mistaken for one-another. | example.password = | example.password → aB123cD4ffZZ |
| .secret | Appending this suffix to any variable will cause the value to be automatically generated if it is left empty. Non-empty variables will be preserved as-is. Generation will ensure that the generated 24-character string will hold following character classes .
| example.password = | example.password → )aesw-r46AA&a1a2BDKjAQQ! |
| .encrypt | Appending this suffix to any variable, will encrypt the preceding, evaluated value with the shared secret from the master.secret variable. | example.password = secret example = @example.password.encrypt@ | example → {3DES}jq7UmTE7iUs= |
| .digest | Appending this suffix to any variable, will creates a digested value of the preceding evaluated variable. | example.secret = secret example = @example.secret.digest@ | example → {SSHA}DuOQ/St6IjMHWXkvS3jQ7SETSNg5CUCc6Qkbmw== |
| .password.encoding | This suffix can be appended to a variable ending with ".password", this will ensure that a certain algorithm be applied to the .digest or .password suffixes. Possible values are:
| example.password.encoding={MD4} example.password = secret example.password2.encoding={3DES} | @example.password.digest@ → {MD4}h42AFGBs2ilnekTvoTU/xw== @example.password.encrypt@ → {3DES}bk8jbCfyChU= |
| .uuid | Appending this suffix to a variable name - that has no existing function nor value - will cause an uuid to be generated. | example.uuid = | example.uuid → abcd1234:ab12:ab12:ab12:abcd1234abcd |
| .urn:uuid | Similar as the ".uuid" suffix, but in this case the generated value will be prefixed by a "urn:uuid:" string | example.urn\:uuid = | example.urn:uuid → urn:uuid:abcd1234:ab12:ab12:ab12:abcd1234abcd |
| .esc | Appending this to a variable will cause the underlying generated value to have its following characters escaped with a "\" character.
| example = http://example.com?one=two | @example.esc@ → http\://example.com?one\=two |
| ./ | Appending this suffix to a variable will cause the value to have all its backslashes replaced with forward slashes. | example = something\else | @example./@ → something/else |
| .& | Appending this suffix to a variable will cause the value to have all its "&", "<" and ">" characters to be XML encoded. | example = <element>&</element> | @example.&@ → <element>&</element> |
| .% | Appending this suffix to a variable will cause the value to be URL encoded. | example = http://www.example.com?one=two | @example.%@ → http%3A%2F%2Fwww.example.com%3Done%3Dtwo |
| .cmd | Appending this suffix to a variable will cause the value to be escaped to be suitable for use in Windows cmd scripts | example = &ecre_t | @example.cmd@→ ^&ecre_t |
| .cmd! | Appending this suffix to a variable will cause the value to be escaped to be suitable for use in Windows cmd scripts with delayedexpansion enabled | example = secre_! | @example.cmd!@ → secret_^^^! |
| .url.port | Appending this suffix to a variable containing a URL, will cause the value to be the port associated with the URL. Default port is determined based on scheme. | example.url = ldaps://localhost/dc=localhost | @example.url.port@ → 636 |
| .url.scheme | Appending this suffix to a variable containing a URL will cause the value to be the scheme associated with the URL. | example.url = ldaps://localhost/dc=localhost | @example.url.scheme@ → ldaps |
| .url.secure | Appending this suffix to a variable containing a URL will cause the value to be the boolean value denoting if the protocol is expected to be secure. | example.url = ldaps://localhost/dc=localhost | @example.url.secure@ → true |
| .name | Appending this suffix to a variable containing a distinguished name, will cause the output to be omitted if the input value would be an invalid x.509 Distinguished Name.. | example = cn=person | @example.name@ → cn=person |
| .toURI | Appending this suffix to a variable containing a file path will cause the value to be converted to a URI representation of the path.. | example = C:\Windows | @example.toURI@ → file:/C:/Windows |
| .toFile | Appending this suffix to a variable containing a URI representation of a file path will cause the value to be converted to a path. | example = file:/C:/Windows | @example.toFile@ → C:\Windows |
| Note |
|---|
NOTE: The individual Ubisecure applications below are using the default @uas.url@ parameter. This means that all of the required applications are installed to the same address. Each application will have its name appended to the url address. In demonstration and development environments, no changes are typically required. If you wish to install components to different addresses, you must change the value to match the desired destination. For example, the applications:
are typically public applications available to all end users. The applications
however are for system administrators. To publish system administrator tools at a different address (e.g., an intranet domain), adjust the application URLs accordingly, e.g.:
See below for settings uas.url, password.url, ubilogin.url, logviewer.url and search.url. |
Parameters
master.secret
| Code Block | ||||
|---|---|---|---|---|
| ||||
master.secret = |
The encryption keys for confidential values stored in the Ubisecure Directory are derived from the master.secret value. If you are upgrading (seeUpgrade - SSO Upgrade) or reinstalling then you must use the existing master.secret value for your directory.
The default value is empty. The empty value is an indication for the setup script to securely generate a new secret. The new generated secret is then stored in the configuration file.
suffix.pfx
| Code Block | ||||
|---|---|---|---|---|
| ||||
suffix.pfx = |
This field is a placeholder for the key pair required in SAML signing operations. A base64 encoded PKCS#12 file will be generated to this field by the setup script in in Configuration and setup application to create configurations. The file is protected by the master.secret. Leave this field empty during initial installation.
uas.url
| Code Block | ||||
|---|---|---|---|---|
| ||||
uas.url = https://localhost:8443 |
...
This address must be accessible for all users of this installation. In an installation with front-end reverse proxy servers this address refers to the first front-end server that is accessible from the public network.
ubilogin.url
| Code Block | ||||
|---|---|---|---|---|
| ||||
ubilogin.url = @uas.url@ |
This is the publicly visible URL address of the Ubisecure SSO Management. The value must not include a path component and must not end with a ‘/’ character.
password.url
| Code Block | ||||
|---|---|---|---|---|
| ||||
password.url = @uas.url@ |
This is the publicly visible URL address of the Ubisecure Password management application. The value must not include a path component and must not end with a ‘/’ character.
logviewer.url
| Code Block | ||||
|---|---|---|---|---|
| ||||
logviewer.url = @uas.url@ |
This is the publicly visible URL address of the Ubisecure Logviewer application. The value must not include a path component and must not end with a ‘/’ character.
search.url
| Code Block | ||||
|---|---|---|---|---|
| ||||
search.url = @uas.url@ |
This is the publicly visible URL address of the Ubisecure Search application. The value must not include a path component and must not end with a ‘/’ character.
password.url
| Code Block | ||||
|---|---|---|---|---|
| ||||
password.url = @uas.url@ |
This is the publicly visible URL address of the Ubisecure Password application. The value must not include a path component and must not end with a ‘/’ character.
logs.dir
| Code Block | ||||
|---|---|---|---|---|
| ||||
logs.dir = @compile.dir@/logs |
The path of the folder for run-time generated log files. The default value is a logs sub-directory of the installation folder. Enter a fully qualified path without a trailing ‘/’ character.
netmask
| Code Block | ||||
|---|---|---|---|---|
| ||||
netmask = disabled |
The network address of the browser clients is used to keep track of user sessions. The netmask is used determine if the client’s network address is allowed to change. The default value disabled allows the client’s network address to change during a session, whereas the value 255.255.255.255 would not allow the address to change during a session.
system.password
| Code Block | ||||
|---|---|---|---|---|
| ||||
system.password = admin |
This is the initial password for the System Administrator account.
The default value must be changed immediately after installation. You can also leave this field empty and let the configuration application randomly generate a new password.
ldap.url
| Code Block | ||||
|---|---|---|---|---|
| ||||
ldap.url = ldap://localhost:389 |
This value specifies the network address of the Ubisecure Directory server. Consider using SSL encryption if the Ubisecure Directory is installed on a different host from the Ubisecure web applications. Example of the value when using SSL encryption:
| Code Block | ||||
|---|---|---|---|---|
| ||||
ldap.url = ldaps://directory-server:636 |
If you are running the LDAP in the same server as Ubisecure SSO, please do not change the localhost address.
suffix
| Code Block | ||||
|---|---|---|---|---|
| ||||
suffix = cn=Ubilogin,@uas.url.host.dn@ |
...
- The directory name derived from the uas.url value https://localhost:8443 is cn=Ubilogin,dc=localhost
- The directory name derived from the uas.url value https://sso.example.com:8443 is cn=Ubilogin,dc=sso,dc=example,dc=com
password.encoding
| Code Block | ||||
|---|---|---|---|---|
| ||||
password.encoding = |
or
| Code Block | ||||
|---|---|---|---|---|
| ||||
password.encoding = {SSHA} |
...
Please note that the password encoding of the Ubisecure SSO accounts is managed using the Ubisecure SSO Management application.
Reverse Proxy Configuration
| Code Block | ||||
|---|---|---|---|---|
| ||||
proxy.remote-addr-name = proxy.local.url = @uas.url@ |
...
The value “X-Forwarded-For” is commonly used by proxy servers to pass the address of the requesting client:
| Code Block | ||||
|---|---|---|---|---|
| ||||
proxy.remote-addr-name = X-Forwarded-For |
...
In case there is a reverse proxy server acting in front of the Ubisecure SSO, proxy.local.url specifies the URL that will be used by the reverse proxy when accessing the Ubisecure SSO. In this case the reverse proxy server could have the publicly visible URL address while the URL specified here need only be locally accessible
| Code Block | ||||
|---|---|---|---|---|
| ||||
proxy.local.url = http://ubilogin.local |
Linux and OpenLDAP Settings
| Code Block | ||||
|---|---|---|---|---|
| ||||
ubilogin.run = /var/run/ubilogin openldap.root.password = secret ubilogin.unix.username = ubilogin ubilogin.unix.groupname = @ubilogin.unix.username@ |
...
The name of the user’s group for the user that will be used to run the Ubisecure SSO and the Ubisecure Directory processes.
Microsoft ADAM and Microsoft AD LDS Settings
| Code Block | ||||
|---|---|---|---|---|
| ||||
adam.instance = UbiloginDirectory adam.ldap.port = 389 adam.ldaps.port = 636 |
...
These settings will define the ADAM port numbers for plaintext and SSL protected communication
Tomcat Instance Name
tomcat.instancename = UbiloginServer
...