The Macro language - SSO
- ubisebastian
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: 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
This web page (including any attachments) may contain confidential, proprietary, or privileged information – not for disclosure without authorization from Ubisecure Inc. Copyright © 2024. All Rights Reserved.