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 be testval in 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: Upper-case (reduced) ASCII alphabetic characters Lower-case (reduced) ASCII alphabetic characters Numeric characters 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 . Upper case ASCII alphabetic characters Lower case ASCII alphabetic characters Special characters Numeric characters	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: MD4: applies to .digest SSHA: applies to .digest 3DES: applies to .encrypt	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: 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:

uas
password

are typically public applications available to all end users.

The applications

ubilogin
logviewer
search

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.:

ubilogin.url = https://admin.ubilogin.intra/

See below for settings uas.url, password.url, ubilogin.url, logviewer.url and search.url.

Parameters

master.secret

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

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

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

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

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

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

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

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

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

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

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

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:

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

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

password.encoding =

or

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

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.

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:

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

proxy.local.url = http://ubilogin.local

Linux and OpenLDAP Settings

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

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

Browser not supported