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:
@var@will be replaced at runtime with the value of the key var. For example, if var was defined to betestvalin our configuration file, then all occurrences of@var@would be replaced with testval.- The order in which the references to variables appear is irrelevant; @var@ can occur before var is defined.
- To get a literal ‘@’ character in a configuration file, type ‘@@’.
- For all URLs, appending the suffix .host.dn to the reference of the URL will return the Distinguished Name for the URL in accordance with RFC 2247. For example, if uas.url is https://localhost:8443 , then uas.url.host.dn will be dc=localhost. Similarly, uas.url.host would just return the hostname localhost.
- 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 (see Upgrade - SSO) 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 Configuration and setup application to create configurations - SSO. 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 is the publicly visible URL address of your Ubisecure Authentication Server installation. The value must not include a path component and must not end with a ‘/’ character.
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 suffix defines the location of the Ubisecure Directory settings within Ubisecure’s own LDAP directory.
Typically there is no need to change this value. The default value shown should be used.
In special cases, such as in service center deployments running multiple instances of Ubisecure SSO on the same LDAP directory instance, this value can be modified.
This value and the uas.url value uniquely identify a Ubisecure SSO installation. The name of the Ubisecure Directory cannot be changed without reinstalling the entire system, so consider carefully your choice for the suffix.
The default name of the Ubisecure Directory is derived from the host name defined in the uas.url value (see above).
For example:
- 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} |
This is the password encoding used for LDAP userPassword attribute values of Ubisecure objects in the Ubisecure Directory. The relevant options are: empty for plaintext encoding (default for Windows) and {SSHA} for digested encoding (default for Linux).
The Microsoft ADAM directory server internally encrypts the userPassword values and requires plaintext encoding. Leave the password.encoding value empty if you are using Microsoft ADAM. OpenLDAP, on the other hand, relies on external encoding. Since OpenLDAP is used in Linux installations for the Ubisecure SSO, the default there is to use {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 keys used here are used to set the Ubisecure SSO up for use with front-end reverse proxy servers. Only change these key values if you are using a reverse proxy server.
| Info |
|---|
TIP: If Microsoft ISA 2006 or TMG is used to publish Ubisecure SSO, ensure that the setting “ Verify Normalization ” is turned off. Verify Normalization blocks requests with URLs containing escaped characters. Verify Normalization may cause undesired 500 errors when accessing the Ubisecure management application. For more information, please refer to http://technet.microsoft.com/en-us/library/cc995081.aspx . Other front end servers with similar functionality should be set in a similar way according to manufacturer guidelines. |
proxy.remote-addr-name
This setting must only be used in installations with front-end reverse proxy servers. The setting specifies the name of the HTTP header carrying the network address of the client. Care must be taken to assure that the HTTP header is authoritative and truly assigned by the proxy server.
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 |
By default the setting value is empty and Ubisecure SSO reads the client network address from the TCP/IP properties of the HTTP connection.
proxy.local.url
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@ |
These settings are used to generate configuration files and scripts for the OpenLDAP server.
ubilogin.run
The folder for runtime files generated by OpenLDAP and Ubisecure SSO
openldap.root.password
The password for the OpenLDAP management account
openldap.maxsize
This is the size of the file allocation in bytes for new MDB backend (default is good for about 1 million users). Make this as big as possible because growing this value bigger requires OpenLDAP restart. See size guidance here: System Recommendations and Supported Platforms and OpenLDAP documentation here (6.2.5.8. maxsize:) OpenLDAP Software 2.5 Administrator's Guide
openldap.idlexp
This value is important for Refresh token configuration as it uses this specific type of index. This affects how much memory you need to reserve for OpenLDAP MDB.
Specify a power of 2 for the maximum size of an index slot. The default is 20, yielding a maximum slot size of 2^20 or 1048576. The specified value must be in the range of 16-30. See more here: System Recommendations and Supported Platforms and OpenLDAP documentation here (6.2.4.1. idlexp) OpenLDAP Software 2.5 Administrator's Guide
ubilogin.unix.username
The username of the user that will be used to run the Ubisecure SSO and the Ubisecure Directory processes.
ubilogin.unix.groupname
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 are used when installing the Microsoft ADAM using Ubisecure’s adaminstall.cmd script.
adam.instance
This defines the instance name of Ubisecure SSO in ADAM
adam.ldap.port adam.ldaps.port
These settings will define the ADAM port numbers for plaintext and SSL protected communication
Tomcat Instance Name
tomcat.instancename = UbiloginServer
This setting determines the name of the tomcat instance, which is visible in Windows in the Services utility. In a typical deployment, do not change this value. For service center / multi-tenant deployments, this value must be unique for each Ubisecure SSO installed on the same machine.
tomcat.instancename
This defines the instance name of Ubisecure SSO Tomcat