Introduction

What is Unison?

Tremolo Security’s Unison is powerful way to provide authentication, course grained authorization and identity management services for your applications. With Unison you can:

Provide Single Sign-On to your Active Directory forests
Provide identity information to cloud based applications without having to forklift existing identity infrastructure into the cloud

Unison combines the identity tools needed by applications into a single virtual appliance that can be used to enhance the implementations of internal applications or provide identity services to applications in the cloud. Unison provides the following features:

User provisioning
Authentication
Authorizations
LDAP Virtual Directory
Last Mile Authentication This guide provides direction to implementing Unison in your environment and will act as a reference for individual configuration options.

How the Pieces Fit

Tremolo Unison combines the functions of many pieces of an identity management infrastructure including:

Authentication System
Virtual Directory
Certificate Manager
Authorization Policy Manager
Reverse Proxy
Provisioning Web Services
Audit
Workflows

These pieces come together in the administration interface. If these pieces were separate servers, the diagram might look like the following:

Each label in the above diagram corresponds to a configuration section in the administration interface. The first layer has “web servers” for accessing Unison. The administration interface typically runs on port 9090 and ALWAYS runs over SSL. The reverse proxy is the main interface that users access. Additional virtual hosts may be configured to support multiple application hosts. An LDAP virtual directory interface allows applications to access identity data. The web services interface provides access to Unison workflows via a RESTful web service. These systems all interact with a server core. The core systems organize application interactions and users are authentication. Unison has an internal virtual directory. This virtual directory handles all interaction with external data stores. Finally, Unison has an integrated user provisioning system including a workflow engine and a way to configure provisioning targets for creating and disabling users.

How Does Unison Fit in Your Enterprise?

Tremolo Security’s Unison is a unified cloud identity system for web applications. Unison provides the identity functions most commonly needed by applications, including:

Authentication
Federation – Allowing another party to perform authentication for you instead of managing the credential yourself
PIV Cards / SSL – Common in the US Federal Government, allows the use of federal ID badges for authentication
Username and Password – Commonly used by most applications
Virtual Directory
Authorization
Just-in-Time Provisioning
Application Integration
User Provisioning Web Services
Access Requests

Figure 1. ScaleJS

ScaleJS is an AngularJS application that uses RESTful web services to interact with Unison. The application can be downloaded from https://www.tremolosecurity.com/downloads or directly from the OpenUnison github repo. The services may be used on their own without ScaleJS. Details for each service is in the integration guide. The configuration of each application is included in the Filter reference of this guide.

Figure 2. Reverse Proxy

When your application uses Unison users will interact with your application by putting a url, such as https://www.mycompany.com/application, into their browser which will take them to Unison. Unison will

Authenticate users using its internal LDAP virtual directory
Authorize users to use applications based on policies
Provide mechanisms to add headers and cookies, as well as transform requests
Forward requests to applications
Provide LDAP virtual directory services to the application
Process the applications’ responses
Forward responses back to the users

Unison provides a wide variety of functions as a reverse proxy to applications. Applications can leverage Unison as an LDAP virtual directory without using the reverse proxy as in the below diagram:

Figure 3. LDAP Virtual Directory

In the above scenario Unison is acting as an LDAP virtual directory to provide identity data to an application using the LDAP standard. This provides a simple integration method for applications that need to authenticate users using a username and password. In this scenario the user authentication occurs according to the following:

A user accesses the application.
The application prompts the user for a username and password.
The application uses an LDAP library to search for the user in Unison’s LDAP virtual directory.
Unison returns the distinguished name associated with the user’s account in the directory.
The application uses an LDAP library to perform an LDAP bind to authenticate the user.

Using Unison as an LDAP virtual directory can provide a good first integration step. However, under this deployment scenario much of the functionality that Unison offers cannot be utilized. This includes:

Federation
PIV / SSL Authentication
Common Access Controls

Figure 4. Cloud Web Access Manager

Unison is purpose built for deployment in the cloud. Unison is able to provide the identity integration features that can extend your enterprise into the cloud. When deployed in the cloud Unison can provide:

Simplified sign-on with your existing identity infrastructure (e.g. Active Directory)
Just-in-time provisioning of identity data to application databases
Use of cloud databases for identity stores for cloud applications
LDAP virtualization of cloud databases to provide dynamic identity data to applications without setting up synchronization across the corporate firewall
Multi-factor authentication to SaaS applications

What Do You Need to Get Started?

Before starting the installation process for Unison, you should collect the following parts list:

Hypervisor – See the installation guide for supported hypervisors if you are installing Unison onto a local network.
Cloud Provider Image – If Unison is to be installed into a cloud environment retrieve the cloud provider specific image for your provider.
Directory – A user directory to which you will authenticate users.
Application Documentation – If integrating with an application then consult the application’s documentation for integration with an SSO system.

Where Do I Start?

Getting Unison from installed to operational is a very simple process:

Run through the initial configuration process
Run the "Proxy" configuration wizard
Integrate an Application

Initial Configuration

The initial configuration screen is what you are presented with the first time you access the Unison management portal on port 9090. Once the information is filled out and Unison restarts you will be able to login to the management portal.

Proxy Configuration Wizard

Once the initial configuration is complete, there’s a red button under "Setup Wizards" that says "Proxy". This wizard will set your initial listener interfaces and create some basic application configurations to support logins and logouts.

Application Integration

Once the proxy is able to receive connections, the next step is to integrate an application. In this section we will walk through setting up a simple "Login Test" application that relies on a local user account created inside of Unison. This application will be very simple, it will echo the login back to you in a simple table that will also show you what headers and cookies have been generated. This app will involve several components of Unison and is a good starting point to understand how the pieces fit (in addition to the section of the same name in this manual).

Create the Test User

The first step is to create a test user to be able to login with. Unison manages an internal LDAP Virtual Directory to manage all user authentication and authorization requests. One of the supported directory types is called the "Admin" directory which creates a single static user. To create this user:

From the main screen click on "User Directories" on the left hand side:

The "User Directories" section contains all directories that Unison will search when a user attempts to access an application. Once the screen loads, click on "Admin" on the lower section of the screen:

On the next screen, specify the required information about the user (seen below). For specific information on the different fields see the "Directory Configuration" chapter. NOTE: the password specified below is "secret" with no quotes.

The user "testuser" has been created. Its not available yet for applications since the proxy configuration hasn’t been reloaded. Once the next step is done we will reload the proxy configuration and test with this user.

Create the Test Application

Once the test user is created, the next step is to create an application. Unison organizes its inbound connections into "Applications", which are a collection of URLs. The common denominator across the URLs of an application is a single session. Otherwise, the URLs can have any relationship. For instance if an "Application" includes Wordpress, JBoss and .NET applications, thats OK. The first step is to click on the "Applications" link on the left hand side of the administration portal:

Once the Applications screen loads, click "Add Application":

On the "Edit URL" screen, fill out the information as per below. This main information tells Unison how to react when it receives a request for this URL:

Configure Application screen loads, fill in the information as shown below. For this application, specifying "*" as the cookie domain will make the cookies scoped as a host cookie (based on whatever is typed into the browser).

After clicking "Submit" the screen will refresh with "URLs" listed at the bottom of the screen. Click "Add URL"

On the "Edit URL" screen, fill out the information as per below. This main information tells Unison how to react when it receives a request for this URL:

After clicking "Submit", three new options will appear on the screen. "Hosts" identifies the host portion of a URL. "Filters" provides a mechanism for Unison to perform work, such as adding headers or calling workflows, before the request is sent to the backend application. Finally "Rules" are authorization rules that determine who has access to this URL.

Under "Hosts" click "Add Host":

Once the host screen appears, specify "*" as the name of the host. This will accept requests for this URL no matter what the user types as the host portion of the URL into the browser.

After clicking "Submit", click "Return to URL".

Now that Unison can identify this URL, filters can be added to process information. In this tutorial the "Login Test" filter, which will generate a table of cookies, headers and session information, will be added to the URL. From the URL screen click on "Add Filter"

Once the Edit Filter screen loads choose the "Login Test" filter from the "Class Name" drop down and click "Submit". Once the configuration is reloaded, specify "/logout" as the Logout URI and click "Submit" again. Finally click on "Return to URL Configuration".

The final application configuration step is to add an authorization rule. At the bottom of the URL configuration screen click on "Add Rule".

On the Edit Rule screen choose "dn" as the LDAP Scope and o=Tremolo as the Constraint. This tells Unison that any user with a distinguished name inside of Unison’s virtual directory that ends in o=Tremolo (which is all of them since o=Tremolo is the root of the vitual directory) can access this URL.

The final step is to reload the proxy configuration so Unison can start accepting requests to this URL. On the left hand side choose "Manage Proxy"

At the bottom of the screen is a link called "Reload Proxy Configuration", click this link to reload the proxy

Login to Test Application

Now that everything has been configured, login to your test application by going to https://host/login where host is the host or IP of your application. You’ll be prompted to login, use "testuser" as the username and "secret" as the password (no quotes). Once logged in you will see a table of data including login information and user data.

What’s Next?

Now that you have Unison running you can start integrating new applications and authentication mechanisms. The rest of this manual contains all of the configuration information for Unison. In addition:

Tremolo Security SAML2 Playground - https://www.tremolosecurity.com/support/ - Use Tremolo Security’s testing identity provider to test applications without setting up your own identity provider
Application Integration Wikis - https://www.tremolosecurity.com/wiki/ - See how-to’s and videos on how to integrate with various applications

Installing Unison

Installing Unison from RPMs

Any RHEL based system (RHEL 6/7, CentOS 6/7, Amazon Linux) can become a Unison virtual appliance by installing the RPM. To install the rpm, first add tremolosecurity.com’s RPM repository to your yum repositories and then install the unison package.

$ cd /etc/yum.repos.d
$ wget https://www.tremolosecurity.com/docs/tremolosecurity-docs/configs/tremolosecurity-1.0.8.repo
$ yum install ts-unison

Unison is ready to be configured on port 9090

Installing Unison on Linux

If you are deploying Unison on a cloud hosted system and are unable to use the ISO you can install unison directly. Before installing a base line system must have: The following minimum hardware (or virtual hardware):

8GB of hard disk space
1GB RAM (2GB recommended)
a network connection

In addition, Unison requires these minimum packages:

openssh-clients
sudo
ntp
hal
iputils
openssl
java-1.8.0-openjdk-devel

Note that these package names are based on RedHat 6.x/7.x packages. Other distributions might have different names. Additionally Oracle’s JDK may be substituted for OpenJDK but the Unlimited JCE policy files MUST be installed. Finally, the following packages are recommended to assist in debugging:

openldap-clients
telnet
tracert

To install Unison on Linux, use the binary installer distributed by Tremolo Security. The file can be run directly with the following commands:

$ cd $PATH_TO_INSTALLER
$ ./unison_installer.bin

Where $PATH_TO_INSTALLER is the path to the directory where the binary installer file is located and unison_installer.bin is the name of the installer file itself) The installer must be run as the root user or using sudo. If the command results in a "Permission denied" error, ensure that the binary installer file is executable.

Installing Unison with Docker

Unison is available both on CentOS and RHEL as containers.

On Dockerhub: https://hub.docker.com/r/tremolosecurity/unison/

Red Hat Container Catalog: https://access.redhat.com/ecosystem/software/2206141

Tremolo Security Unison Appliance

Overview

Tremolo Security Unison is deployed as an appliance. It can be deployed onto dedicated hardware or into an existing virtual environment.

File System Layout

Unison is installed on the appliance at the path /usr/local/tremolo/tremolo-unison. All of the files necessary to the application are contained in this directory. Important directories include the bin, conf, and logs directories. They are used to store binary/executable files, configuration files, and Unison’s log files respectively.

/usr/local/tremolo/tremolo-service/bin - Binary/executable files such as the tremolo.sh script used to control Unison (this is a copy of the /etc/init.d/unison script and is used in exactly the same way)
/usr/local/tremolo/tremolo-service/conf - Unison configuration files
/usr/local/tremolo/tremolo-service/logs - Unison log files

Unison uses the system Java Runtime Environment (JRE).

Controlling Unison with the /etc/init.d/unison Script

The Unison appliance is configured to start and stop Unison automatically when the appliance is booted and shut down. To start and stop Unison manually, use the control script located at /etc/init.d/unison. The script can be used with the following arguments: start, stop, restart, status, getenv. Use the start/stop/restart arguments to start/stop/restart Unison.

$ /etc/init.d/unison start
$ /etc/init.d/unison stop
$ /etc/init.d/unison restart

The status argument displays the status of the application and, if Unison is running, the process ID (PID) assigned to it by the operating system.

$ /etc/init.d/unison status
Unison is running.
PID=12345

The getenv argument is used to display the values of each of the Unison environment variables.

$  /etc/init.d/unison getenv

TREMOLO_ROOT = /usr/local/tremolo
TREMOLO_HOME = /usr/local/tremolo/tremolo-unison
TREMOLO_PROXY_HOME = /usr/local/tremolo/tremolo-unison/apps/proxy
TREMOLO_ADMIN_HOME = /usr/local/tremolo/tremolo-unison/apps/tremolo-admin
TREMOLO_WS_HOME = /usr/local/tremolo/tremolo-unison/apps/webservices
TREMOLO_SSH_KEYS = /usr/local/tremolo/.ssh
TREMOLO_ETC = /usr/local/tremolo/etc
TREMOLO_CONF = /usr/local/tremolo/conf
TREMOLO_SDKS = /usr/local/tremolo/sdks
TREMOLO_LOGINS = /usr/local/tremolo/logins
TREMOLO_SSL = /usr/local/tremolo/ssl
TREMOLO_CERTS = /usr/local/tremolo/ssl/certs
TREMOLO_CRLS = /usr/local/tremolo/ssl/crls
TREMOLO_ACTIVEMQ=/usr/loca/tremolo/tremolo-service/activemq
TREMOLO_QUARTZ_DIR=/usr/local/tremolo/tremolo-service/conf/quartz

This sample output assumes that Unison was installed at /usr/local/tremolo.

Unison Utilities

Nearly all configuration tasks can be performed from inside of the Unison administrative interface. If a situration ocurrs where the interface won’t start, its important to be able to access the Unison configuration. Since Unison’s configuration is encrypted, editing requires that the configuration be decrypted, changed and re-encrypted. The tools described in this section assist in this process. NOTE: These tools are ment as a last line and should NOT be used if the administrative interface is available.

Unison has three license protected configuration files:

Proxy - /usr/local/tremolo/tremolo-service/apps/proxy/WEB-INF/tremolo-cfg.json
Administration Interface - /usr/local/tremolo/tremolo-service/apps/tremolo-admin/WEB-INF/tremolocfg.json
Web Services - /usr/local/tremolo/tremolo-service/webservices/WEB-INF/tremolo-cfg.json

Each of these files can be decrypted into two configuration files:

Tremolo Configuration (XML)
MyVD Configuration (Properties)

Once edited, these files can be re-combined and encrypted to update the Unison configuration

Print Configuration

The printConfig.sh script in /usr/local/tremolo/tremolo-service/bin provides the ability to decrypt one of these files. It takes no command line parameters, but requests four inputs on startup:

Config file - The full path to tremolo-cfg.json (usually one of the files mentioned above)
Key - The license key for Unison
Path to write Tremolo Configuration - Path and filename to write the Unison configuration informationto
Path to write MyVD Configuration - Path and filename to write the MyVD configuration information to

The output of this command can be downloaded and updated in any text or XML editor, then re-encrypted using the saveConfig.sh command.

Save Configuration

The saveConfig.sh script in /usr/local/tremolo/tremolo-service/bin provides the ability to encrypt a Tremolo and MyVD configuration file for use by Unison. It takes no command line parameters, but requests four inputs on startup:

Tremolo XML - The full path to the XML file used by Unison
MyVD Config - The full path to the properties file used by MyVD
Config file - The full path to the encrypted file to write to (typically one of the above paths)
Key - The license key for Unison

Export Server Package

The exportPackage.sh script in /usr/local/tremolo/tremolo-service/bin will generate a server package that can be uploaded to Unison at startup or to restore the state of a corrupted server.

Path to tremolo-service (NOT including tremolo-service) - Example /usr/local/tremolo on most installations
Package path - The full path to the file to save the package to, ie /tmp/unison-package.json

Logs

All logs are stored in tremolo-service/logs. There are three main logs used by Unison for the following:

tremolo.log - This file is used by the tremolo.sh script to log standard output and standard error associated with the starting and stopping of Prelude and its components on Linux and Mac OS X. This log is not used by Windows systems.
tremolo-service.log - This is the service log used to log all events other than access events. The following information is captured on each line in this log: Timestamp ,Thread, Log Level, Component, Message. A sample line from this log is included below.[2011-10-17 20:54:16,234][main] INFO Server - Started SSL Listener on Port 9090
access.log - This is the log file used to log access events including successful authentication attempts, failed authentication attempts, successful authorization, failed authorization, and page not found errors. The following information is captured on each line in this log: Event Type, Component, Request URL, DN of the User, Result Group. A sample line from this log is included below.[AzSuccess] - Admin System - https://127.0.0.1:9090/auth/formLogin - cn=none - formlogin
ldap-access.log - This log file captures all LDAP requests (both from internal requests and external requests). It records the type of access, timestamp, user, connection operation on the connection and results.

Creating Services

Unison can be run as a service on either Red Hat 6.x or 7.x (and variants). Neither the installer nor the RPM installs the scripts by default but they are included in the bin directory. This section provides instructions for both distributions.

Red Hat Linux 6.x / CentOS 6.x

$ sudo su -
$ cp /usr/local/tremolo/tremolo-service/bin/unison.chkconfig \
 /etc/rc.d/init.d/unison
$ chmod 740 /etc/rc.d/init.d/unison
$ chkconfig unison on
$ service unison start

Red Hat Linux 7.x / CentOS 7.x

NOTE - If deploying on RHEL make sure that the optional repository is installed

$ sudo yum-config-manager \
 --enable rhui-REGION-rhel-server-extras \
 rhui-REGION-rhel-server-optional

On all other distributions:

$ sudo su -
$ cp /usr/local/tremolo/tremolo-service/bin/unison.service \
 /etc/systemd/system/
$ systemctl daemon-reload
$ systemctl enable unison
$ systemctl start unison

Server Setup Wizard

Proxy First Time Setup

This wizard will setup Unison to be able to accept requests.

Option	Description	Example
Server Name (CN)	The Common Name of the certificate. This is the server name that users will type into their browser.	apps.mycompany.com
Department (OU)	The name of the department assigned to this certificate	IT
Company (O)	The name of the company assigned to this certificate	Tremolo Security Inc.
City (L)	The name of the city the company is located in	Arlington
State (ST)	The FULL name of the state or province the company is in.	Virginia
Country Code ©	The two letter country code the company is in.	US
IP Address (blank for all)	If Unison will run on a specific interface, it can be specified here. Usually this is left blank
Open Port (blank for none)	Port for non secure communications. Usually this can be left blank
External Open Port (blank for none)	What port is used for external URLs if different then the actual port being listened on. For instance if Prelude is running on 8080 but a load balancer will present it on port 80 this would be 80.	80
Secure Port (blank for none)	Port for non secure communications	8443
External Secure Port (blank for none)	What port is used for external URLs if different then the actual port being listened on. For instance if Prelude is running on 8443 but a load balancer will present it on port 443 this would be 443.	443

Identity Provider Wizard

Introduction

The Identity Provider Wizard is designed to help you connect your enterprise to your SaaS applications quickly. This wizard will guide you through the process of connecting Unison to your directory, generating certificates and connecting to your SaaS application.

Welcome

The first screen is an introduction screen with no input. This screen gives you an overview of what information you’ll need.

Identity Provider Basic Information

This screen configures two main pieces of information: The name of the IdP and the host users will use to access your IdP:

Option	Description	Example
Identity Provider Name	Descriptive name for the identity provider. There should be no spaces	EnterpriseIdP
Enterprise Facing	The host name (with no port) of the Unison URL. For instance if Unison is being hosted at https://idp.myenterprise.com:8443 then this would be idp.myenterprise.com	idp.myenterprise.com

Identity Provider Signing Certificate

When configuring an identity provider its important to always sign the assertions that are sent to your SaaS applications. This ensures the SaaS application that your assertions are coming from you. This step will setup a self-signed certificate that is used for signing. Once this step is complete, you may want to have the certificate signed by a 3rd party CA. Additionally, you may choose an existing certificate.

Option	Description	Example
Existing Certificate	If using an existing certificate, choose it from this list	Existing Certificate or blank
Name of new Certificate	The name of the new certificate. No spaces, will be forced to lower case	idp-saml2-sig
Name (CN)	The Common Name of the certificate. For web servers this is the server name but for federation a descriptive name will do.	idp-saml2-sig
Department (OU)	The name of the department assigned to this certificate	IT
Company (O)	The name of the company assigned to this certificate	Tremolo Security Inc.
City (L)	The name of the city the company is located in	Arlington
State (ST)	The FULL name of the state or province the company is in.	Virginia
Country Code ©	The two letter country code the company is in.	US

Identity Provider Encryption Certificate

An encryption certificate is used when SaaS applications are making encrypted requests from Unison. This is generally not needed and can be left to "No Encryption". Once this step is complete, you may want to have the certificate signed by a 3rd party CA. Additionally, you may choose an existing certificate.

Option	Description	Example
No Encryption	If checked, no encryption certificate is generated or configured.	Checked
Existing Certificate	If using an existing certificate, choose it from this list	Existing Certificate or blank
Name of new Certificate	The name of the new certificate. No spaces, will be forced to lower case	idp-saml2-sig
Name (CN)	The Common Name of the certificate. For web servers this is the server name but for federation a descriptive name will do.	idp-saml2-sig
Department (OU)	The name of the department assigned to this certificate	IT
Company (O)	The name of the company assigned to this certificate	Tremolo Security Inc.
City (L)	The name of the city the company is located in	Arlington
State (ST)	The FULL name of the state or province the company is in.	Virginia
Country Code ©	The two letter country code the company is in.	US

Create New Directory?

If the IdP requires the integration of a new directory, check the box on this page. Otherwise directory configuration will be skipped.

Option	Description	Example
Create a new directory?	If checked, the next screen will be the creation of a new directory.	Checked

Directory Information

Unison retrieves user data from directories configured in the administrative interface. The Identity Provider registration wizard can also configure a directory. Choose the type of directory to configure. See the directory configuration section for details on individual directory configurations.

Option	Description	Example
Source	The type of directory to configure	LDAP

Directory Configuration Validation

This screen will show the results of a directory configuration validation test. If any errors are shown, click "Previous" to correct them.

Identity Provider Attributes

Unison will supply a SaaS application with information about the logged in user via an assertion. This assertion can contain information such as a username, email address and entitlement information. Use this screen to configure these attributes.

Option	Description	Example
Attribute Name	The name of the attribute as it will appear in the assertion	userName
Source Type	The user attribute the value will come from. There are three options: - user - An attribute that is currently a part of the user’s object - static - A pre-defined value that never changes - composite - A combination of static text and attributes defined by ${attributeName}	composite
Source	The data to be used There are three options: - user - The name of the attribute, ie uid - static - A set value, ie someData - composite - The composite attributes, ie ${givenName}.${sn}@test.com	${givenName}.${sn}@test.com
NameID?	Will this attribute be used to identify the user?	Checked
NameID Format	SAML identifies different types of user names. If this attribute is a NameID, you must specify what type it is.	urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
Default Name ID Type?	If the SaaS application does not specify a NameID format, either in its meta data or in the authentication request, should this be the default NameID?	checked

SP Meta Data Import

In order to more quickly configure identity providers, SaaS providers may supply a meta data file that contains information about certificates, the urls used, etc. This metadata can be imported on this screen. There are three options:

Option 1 - Load from URL : If your SaaS provider has a URL that the metadata can be retrieved from it can be directly imported
Option 2 - Upload Metadata File : If the SaaS provider has a downloadable file, it may be uploaded here
Option 3 - No Meta Data : If the SaaS provider does not supply meta data it may be configured manually

SP Meta Data Import Verification

If there are any issues with the meta data import, check the logs for any errors.

Next Steps

These are steps to take once the wizard is complete to finish the integration of the SaaS application. All of these steps can be performed at any time in the Unison admin interface.

Option	Description	Example
Reload Identity Provider	Unison must be reloaded for changes to take effect	Click the link
Generate IdP Meta Data	Most SaaS providers will accept metadata files for simpler configuration. This section can be used to quickly generate the metadata

Application Wizard

Welcome

This screen is informational and does not contain any configuration information

Application Basic Information

This screen configures three main pieces of information: The name of the application, the URL users will use to access the application and the host Unisons will communicate with to connect to the application.

Option	Description	Example
Application Name	Descriptive name for the application. There should be no spaces	MyApp
Enterprise Facing	The host name (with no port) of the Unison URL and the URI (path) the application will be hosted on. For instance if Unison is being hosted at https://apps.myenterprise.com:8443/test then this would be apps.myenterprise.com in the first box and /test in the second box	idp.myenterprise.com
Application Facing	The host and port of the server hosting the application behind Unison. For instance if the server hosting the application is 10.1.2.100 port 8080 then this would be 10.1.2.100:8080	idp.myenterprise.com
Use SSL?	If checked, Unison will use HTTPS instead of HTTP	Checked

Create New Directory?

If the IdP requires the integration of a new directory, check the box on this page. Otherwise directory configuration will be skipped.

Option	Description	Example
Create a new directory?	If checked, the next screen will be the creation of a new directory.	Checked

Directory Information

Option	Description	Example
Source	The type of directory to configure	LDAP

Directory Configuration Validation

This screen will show the results of a directory configuration validation test. If any errors are shown, click "Previous" to correct them.

Authentication Type

Use this screen to tell Unison how to authenticate users. Either choose an existing authentication chain from the list or create a new chain using once of the mechanisms from the drop down list.

Option	Description	Example
Authentication Type	Choose an existing authentication chain or "New Chain" to create a new chain	New Chain
Authentication Mechanism	If "New Chain" is selected, choose a mechanism to base the new chain on. Once selected, configure the chain using the instructions from the information from the Authentication Mechanisms chapter.	New Chain

Just-In-Time Provisioning

If the application needs user data to be populated as users login, check the box on this page. Otherwise JIT provisioning configuration will be skipped.

Option	Description	Example
Use Just-In-Time Provisioning?	If checked, the next screen will be provisioning configuration.	Checked

Provisioning Target

This screen tells Unison which provisioning target to use when creating users. Either choose an existing target from the list or create a new target using once of the mechanisms from the drop down list.

Option	Description	Example
Existing Target	Choose an existing provisioning target or "New Provisioning Target" to create a new target	New Provisioning Target
New Target Type	If "New Provisioning Target" is selected, choose a target type to configure. Once selected, configure the chain using the instructions from the information from the Provisioning Targets chapter.	New Target Type

Target Configuration Validation

his screen will show the results of a target configuration validation test. If any errors are shown, click "Previous" to correct them.

Just-In-Time Provisioning

On this screen tell Unison how to map data from authentication into the application’s user store.

Attribute Mappings

In this section tell Unison which attributes from authentication to provision into the application’s provisioning target

Option	Description	Example
Provisioned To	The name of the attribute in the target system	login
Source Type	One of user, static, custom or composite. user loads an attribute directly from authentication. static sets the value to a constant value. composite allows for an attribute to be built from several attributes easily with something like "${givanName} ${sn}". Custom is a class name.	uid
From Authentication	The value of the attribute according to the source type	login

Group Mappings

In addition to setting attributes, the just-in-time provisioning process can set group memberships. There are two methods for doing this. The first is to leave "Map all values of one attribute to groups" unchecked and manually list mappings of attribute values to groups. The other method is to check "Map all values of one attribute to groups" and specify which attribute to read group names from.

If doing a manual mapping:

Option	Description	Example
Attribute Name	The name of the user attribute to map to a group	attribute1
Attribute Value	The value of the attribute to map to a group	value1
Group Name	The name of the group to add to the user if the attribute name and value are present in the authentication data	group1

Last Mile Configuration

The final step is to tell the application who the user is. There are three ways to do this, each with their own advantages.

None - This option is only useful in situations where you plan on configuring a custom last mile integration.
Secure Last Mile - This is the recommended option for integrating with applications. See the integration guide for specific instructions on different application platforms. If "Set Use Groups to Role Attribute?" is checked then the attribute named in the "Role Attribute Name" box will be configured as the role identifier.
Header - If a Last Mile integration is not possible, you can use a header to supply the unique identifier.

Administration Reference

Servers

The servers section of the admin system focuses on the management of the Unison system such as listeners and pushing configurations to other systems.

Manage Proxy

This screen specifies on what ports Unison listens on:

Option	Description	Example
Disable HTTP2	If checked, HTTP2 will not be enabled	Unchecked
Open Port	The port that will listen on “http”, leaving blank means there will not be an open port	8080
External Open Port	If Unison is behind a firewall running a different port, this is the open port that users see, often port 80. This setting is used for creating redirects.	80
Secure Port	The port that will listen using SSL, leaving blank means there will not be a secure port	8443
External Secure Port	If Unison is behind a firewall running a different port, this is the secure port that users see, often port 443. This setting is used for creating redirects.	443
Force to SSL	Check this if the host should force all requests to ssl	true/false
SSL Certificate	The name of the certificate from the “SSL Certificates” section in Certs	idp-server
Allow SSLv3	Check this if the listener should allow SSLv3 connections, default to false	true/false
SSL Client Authentication	When using SSL, is a trusted client certificate required?	none – No client certificate required optional – If a certificate is available, accept it required – A certificate is REQUIRED to establish a connection Note, that to support SSL Authentication optional or required are needed. Selecting optional allows for user friendly error pages.
SSL Accepted Issuers	What issuers will be trusted?	One or more issuers.
Available Ciphers	Which ciphers will be used?	If none are specified, defaults to TLS_RSA_WITH_RC4_128_SHA, TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHA, TLS_RSA_WITH_3DES_EDE_CBC_SHA, TLS_RSA_WITH_AES_128_CBC_SHA256, TLS_RSA_WITH_AES_256_CBC_SHA256
IP Address	The ip address of the interface Unison will listen on, leave blank for all interfaces	10.10.10.2
Enabled	If checked, the proxy interface is eabled	Checked
Enable Unescaped URL Characters	If checked Unison will allow unescaped characters in URLs	Unchecked
Open Session Cookie Name	The name of the session cookie for "open sessions"	tremoloOpenSession
Open Session Cookie Timeout	the number of seconds the open session is idle until it is timed out	1200
Open Session Secure	checked if the open session session cookie should be "secure"	checked
Open Session HTTP Only	Checked if the open session cookie shouldn’t be accessed by javascript	checked
Enable HSTS	If checked, enable the HSTS header	checked
HSTS Time To Live (seconds)	The number of seconds until the browser should inspect the hsts header again	31536000
Number of Threads Per Session and Route	The number of concurrent threads per user session per route (host/port), should be equal to the number of threads used by expected browsers.	6

Restart Proxy

Clicking on this link restarts the Unisons listeners. Click this link after making changes such as changing port numbers.

Reload Proxy Configuration

Clicking on this link reloads Unisons configuration without restarting Unison. Click this link after making changes such as adding applications.

Manage Proxy Libraries

This link is used to manage libraries for custom components such as JDBC drivers, filters and mappings

Proxy Libraries

This screen will allow for the upload of jar files that can contain JDBC drivers, filters and custom mappings. Any library uploaded via this screen will be pushed to other servers in the cluster.

Virtual Hosts

Clicking on this link allows for additional listeners for Unison. This is useful if there are separate certificates for multiple proxies.

Proxy Virtual Hosts

This screen lists out the configured virtual hosts. From this screen hosts can be added, edited or deleted.

Virtual Host Configuration

The following fields are available for virtual hosts:

Option	Description	Example
Open Port	The port that will listen on “http”, leaving blank means there will not be an open port	8080
External Open Port	If Unison is behind a firewall running a different port, this is the open port that users see, often port 80. This setting is used for creating redirects.	80
Secure Port	The port that will listen using SSL, leaving blank means there will not be a secure port	8443
External Secure Port	If Unison is behind a firewall running a different port, this is the secure port that users see, often port 443. This setting is used for creating redirects.	443
Force to SSL	Check this if the host should force all requests to ssl	true/false
SSL Certificate	The name of the certificate from the “SSL Certificates” section in Certs	idp-server
SSL Client Authentication	When using SSL, is a trusted client certificate required?	none – No client certificate required optional – If a certificate is available, accept it required – A certificate is REQUIRED to establish a connection Note, that to support SSL Authentication optional or required are needed. Selecting optional allows for user friendly error pages.
Available Ciphers	Which ciphers will be used?	If none are specified, defaults to TLS_RSA_WITH_RC4_128_SHA, TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHA, TLS_RSA_WITH_3DES_EDE_CBC_SHA, TLS_RSA_WITH_AES_128_CBC_SHA256, TLS_RSA_WITH_AES_256_CBC_SHA256
IP Address	The ip address of the interface Unison will listen on, leave blank for all interfaces	10.10.10.2
Enabled	If checked, the identity provider is running	Checked

Manage Virtual Directory

This screen specifies on what ports the virtual directory listens on:

Option	Description	Example
Open Port	The port that will listen on “ldap”, leaving blank means there will not be an open port	10389
External Open Port	If Unison is behind a firewall running a different port, this is the open port that users see, often port 80. This setting is used for creating redirects.	389
Secure Port	The port that will listen using SSL, leaving blank means there will not be a secure port	10636
External Secure Port	If Unison is behind a firewall running a different port, this is the secure port that users see, often port 443. This setting is used for creating redirects.	636
Force to SSL	Check this if the host should force all requests to ssl	true/false
SSL Certificate	The name of the certificate from the “SSL Certificates” section in Certs	idp-server
SSL Client Authentication	When using SSL, is a trusted client certificate required?	none – No client certificate required optional – If a certificate is available, accept it required – A certificate is REQUIRED to establish a connection Note, that to support SSL Authentication optional or required are needed. Selecting optional allows for user friendly error pages.
IP Address	The ip address of the interface Unison will listen on, leave blank for all interfaces	10.10.10.2
Enabled	If checked then the virtual directory is started. Unchecking this box and submitting will stop the virtual directory.	checked
Directory Root	The root for the virtual directory, defaults to o=Tremolo	dc=mycompany,dc=com
User Object Class	The object class to use for users, defaults to inetOrgPerson	posixUser
Group Object Class	The object class to use for groups, defaults to groupOfUniqueNames	posixGroup
Group Membership Attribute	The attribute used to store group memberships, defaults to uniqueMember	member

Reload Virtual Directory Configuration

Clicking on this link reloads the virtual directory’s configuration without restarting Unison. Click this link after making changes such as adding applications.

Manage Web Services

This screen specifies on what ports the user provisioning web services listens on:

Option	Description	Example
Open Port	The port that will listen on “http”, leaving blank means there will not be an open port
External Open Port	If Unison is behind a firewall running a different port, this is the open port that users see, often port 80. This setting is used for creating redirects.
Secure Port	The port that will listen using SSL, leaving blank means there will not be a secure port	9093
External Secure Port	If Unison is behind a firewall running a different port, this is the secure port that users see, often port 443. This setting is used for creating redirects.	9093
Force to SSL	Check this if the host should force all requests to ssl	true/false
SSL Certificate	The name of the certificate from the “SSL Certificates” section in Certs	idp-server
Allow SSLv3	Check this if the listener should allow SSLv3 connections, default to false	true/false
SSL Client Authentication	When using SSL, is a trusted client certificate required?	none – No client certificate required optional – If a certificate is available, accept it required – A certificate is REQUIRED to establish a connection Note, that to support SSL Authentication optional or required are needed. Selecting optional allows for user friendly error pages.
Available Ciphers	Which ciphers will be used?	If none are specified, defaults to TLS_RSA_WITH_RC4_128_SHA, TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHA, TLS_RSA_WITH_3DES_EDE_CBC_SHA, TLS_RSA_WITH_AES_128_CBC_SHA256, TLS_RSA_WITH_AES_256_CBC_SHA256
IP Address	The ip address of the interface Unison will listen on, leave blank for all interfaces	10.10.10.2
Enabled	If checked then the virtual directory is started. Unchecking this box and submitting will stop the virtual directory.	checked
Session Key	The session key used to encrypt the session for identity web services.	tremolowssession
Session Cookie Name	The name of the cookie for identity web services	tremolowssession
Issuers	Unison identity web services are secured using certificate authentication. Specify which certificate issuers to trust from this option.

Reload Web Services Configuration

Clicking on this link reloads the web service’s configuration without restarting Unison. NOTE: this will not reload workflows. Reload the proxy configuration to reload workflows.

Manage Admin Service

This screen provides the ability to configure the administration service. NOTE: in order for changes to the admin service to take affect Unison MUST be restarted. The options available are:

Option	Description	Example
Open Port	The port that will listen on “http”, leaving blank means there will not be an open port	8080
External Open Port	If Unison is behind a firewall running a different port, this is the open port that users see, often port 80. This setting is used for creating redirects.	80
Secure Port	The port that will listen using SSL, leaving blank means there will not be a secure port	8443
External Secure Port	If Unison is behind a firewall running a different port, this is the secure port that users see, often port 443. This setting is used for creating redirects.	443
Force to SSL	Check this if the host should force all requests to ssl	true/false
SSL Certificate	The name of the certificate from the “SSL Certificates” section in Certs	admin-server
Allow SSLv3	Check this if the listener should allow SSLv3 connections, default to false	true/false
IP Address	The ip address of the interface Unison will listen on, leave blank for all interfaces	10.10.10.2
Enabled	If checked, the admin service is running	Checked
Hosted on a Shared File System?	If checked, Unison looks for changes to the file system to reload or restart rather then using the configuration push system for configuration. This is useful in situations where the IP address of the server is not static.	Unchecked
Administrative Constraint Type	Determines how Unison authorizes administrators. dn – A root dn, all users below this DN can administer Unison group – The DN of a group of users that can administer Unison filter – an LDAP filter that can be used it identify administrative users See the “Directories” section for how to specify a static group	dn
Administrative Constraint	The constraint for identifying administrators. A DN, group or filter See the “Directories” section for how to specify a static group	ou=admin,o=Tremolo
Synchronization Certificate	The certificate from the “Trusted Certificate Authorities” of certificate management to require for cluster syncing	sync-certificate
JCE	The class name of the JCE provider to use. By default, org.bouncycastle.jce.provider.BouncyCastleProvider however another JCE (ie a FIPS 140-2 certified one) may be specified. The server must be restarted after changing this setting to take effect.	org.bouncycastle.jce.provider.BouncyCastleProvider
Administrative Authentication Type	Use this setting to enable SAML2 authentication for the administration portal. If SAML2 is selected, the same screen as the SAML2 Authentication Chain is available.	Choose between "Username and Password" and "SAML2"
Available Ciphers	Which ciphers will be used?	If none are specified, defaults to TLS_RSA_WITH_RC4_128_SHA, TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHA, TLS_RSA_WITH_3DES_EDE_CBC_SHA, TLS_RSA_WITH_AES_128_CBC_SHA256, TLS_RSA_WITH_AES_256_CBC_SHA256
Available Ciphers	Which ciphers will be used?	If none are specified, defaults to TLS_RSA_WITH_RC4_128_SHA, TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHA, TLS_RSA_WITH_3DES_EDE_CBC_SHA, TLS_RSA_WITH_AES_128_CBC_SHA256, TLS_RSA_WITH_AES_256_CBC_SHA256

Administrative Authentication

The administration interface may authenticate via either username and password or via SAML2. See the authentication mechanism reference for details on how to configure the SAML2 authentication mechanism.

Option	Description	Example
User ID Attribute Name	The name of the user identifier attribute. Defaults to uid	uid

Update License

When new licenses are needed this screen is used to update the license. The below fields are available:

Option	Description	Example
License Key	The license key you were provided	9bde4b9493afcb89b908c9b9bf824334773f862d1343aa5asdds324
Company Name	The EXACT company name as specified in your license file	My Company
Year	The 4 digit year your company was registered	2011
Month	The numeric month your company was registered, in the license file	07
Day	The day your company was registered, in the license file	10

Download Server Package

This link will download an encrypted version of all Unison configurations, including:

Application and server configurations
Any jar files that were uploaded
Any JSPs that have been uploaded

The downloaded package is encrypted with the current license key and can be used to during the bootstrap process of a new Unison server.

Manage Configuration Slaves

This link allows for the management of Unison servers in a cluster.

Slaves

Slaves are Unison servers in a cluster that rely on a master server for configuration. All slaves should be listed as “host:port”. For instance if a slave is on Unison1.domain.com with SSL port 9090 the slave should be configured as Unison1.domain.com:9090.

Update Cluster Configuration

This link is to update the slaves in the cluster configuration. This link should be followed after updating a configuration to push the new configuration out to the cluster.

Server Configuration

Check the services to be restarted. Note that if the server needs to be restarted that must be done manually.

Reload Proxy	Equivalent to clicking on the “Reload Proxy Configuration” on the “Proxy” management screen
Reload Admin	Equivalent to clicking on the “Reload Admin Service Configuration” on the “Admin” management screen
Restart Proxy	Equivalent to unchecking “Enabled” on the “Proxy” screen, submitting, re-clicking “Enabled” and submitting again
Restart Admin	Equivalent to unchecking “Enabled” on the “Admin” screen, submitting, re-clicking “Enabled” and submitting again

Upload Server Package

This can be used to restore a backup of Unison’s configuration from the "Download Server Package" link.

Manage Certificates

The certificate management screen is where all of the keys and certificates used by Unison are managed. Certificates in Unison are divided by use to make them easier to manage:

Use	Description	Operations
SSL Certificates	Used for any services that will listen over SSL, such as the identity provider, admin service and any virtual hosts	Create, Import, Manage
Session Keys	Used for encrypting the session token. These keys are used to seperate different sessions with the same cookie scope.	Create, Delete
Signature and Encryption Keys	Used for signing and encrypting data outside of an SSL session such as signing and encrypting SAML2 assertions. These keys are used for outgoing data.	Create, Manage
Signature and Encryption Validation Certificates	Used to validate and encrypt data outside of SSL for external sources such as SAML2 assertions. These keys are used for validating incoming data.	Import, Delete
Trusted Certificate Authorities	Certificates for CAs that are trusted	Import, Delete

Keystore Password

The password for the keystore can be reset from this screen.

Create Certificate

Clicking on this link will create a new self-signed certificate using the below options:

Option	Description	Example
Name	A descriptive label	idp-ssl
Server Name (CN)	Either the Fully Qualified Domain Name for the server this certificate will be used for or a descriptive name	apps.mycompany.com
Organizational Unit (OU)	What department is this certificate for?	IT
Organization (O)	The legal name of your organization	My Company Inc.
City (L)	The name of the city your company is located in	Arlington
State (ST)	The FULLY SPELLED OUT name of your state or province. Do not use a two letter abbreviation	Virginia
Country ©	The two letter country code your company is located in	US
Key Size	The size of the key, 1024 is the minimum recommended key size	1024
Signature Algorithm	How the certificate should be self-signed	SHA1withRSA
Valid After	First date, in MM/DD/YYYY, the self-signed certificate is valid	10/05/2011
Valid Until	Final date, in MM/DD/YYYY, the self-signed certificate is valid	10/02/2021
CA Certificate?	If checked, the certificate will be marked as a CA certificate	Checked

Import Key and Certificate

Clicking on this link allows for the import of an existing key and certificate. This tool can be used to import existing wild card certificates or certificates generated using an external tool such as openssl. Two sources for import are available: PKCS 12 or individual key and certificate files (PKCS 11 or PKCS 1).

PKCS12 File

Option	Description	Example
Alias	A descriptive label	idp-ssl
PKCS12 File	The PKCS12 file to import	Path to the PKCS12 file
PKCS12 Alias	The name of the key inside of the PKCS12 file	1 by default
Password	Password to unlock the PKCS12 file
Verify Password	Verify the password

Individual Files

Option	Description	Example
Alias	A descriptive label	idp-ssl
Key File (PEM or DER)	Either a binary or base64 encoded private key in PKCS1 or PKCS11 format	Path to the file
Certificate File (PEM or DER)	Either a binary or base64 encoded certificate in PKCS1 or PKCS11 format	Path to the file

Manage

Clicking on the “Manage” link next to certificate provides common administration capabilities:

Generate a Certificate Signing Request
Import a Signed Certificate
Export the certificate

Generate CSR Request

Clicking on this link will generate a certificate signing request that can be imported into a certificate authority. The generated text can be copied and pasted into a PEM file for the request.

Import Signed Certificate

Once a CSR is generated and a signed certificate has been generated it must be imported back into the keystore by clicking on this link. If the certificate is a text file, or PEM file, its contents can be copied and pasted into the “Certificate” box. If the file is a binary file, or DER file, it can be uploaded by clicking on the “Browse…” button.

Export

This link generates the text for a PEM file of the certificate that can be imported into other SSL systems. The generated text can be copied and pasted into a PEM file. Additionally links to download PEM or DER formatted certificates are available.

Create Session Key

Clicking this link will generate an AES-256 key. Specify the name of the key in the “Name” field.

Import Session Key

Clicking this link will allow you to import a base64 encoded AES key into Unison. Specify the name of the key in the “Name” field and the base64 encoded key in the "Key" field.

Delete

Clicking the Delete link will delete a session key or trusted certificate.

View

Clicking on view will display the base64 encoded version of the key.

Import Certificate

If a certificate needs to be trusted there are three options for importing it. Option 1 is to copy and paste the contents of the PEM file into the “Certificate” box. Option 2 is to directly import a certificate from a service running on SSL, such as an LDAPS or HTTPS service.

Option 1 - Copy and paste the contents of the PEM file into the “Certificate” box
Option 2 - Directly import a certificate from a service running on SSL, such as an LDAPS or HTTPS service
Option 3 - Upload either a DER or PEM encoded certificate

Admin Service Directories

This section allows for the use of external user stores, such as LDAP directories or Active Directory, for access to the Unison administration site. Edit and Delete directories by clicking on the links next to the directory in the list. Add a directory by clicking on the directory type under the “Create Directory” header. See the directory configuration reference for individual configuration options.

Access

Find Users

The users section is a simple way to search for users in the internal virtual directory. There are three ways to search for a user:

Simple Lookup – Search based on a specific attribute value, for instance uid and myuser
LDAP Filter Lookup – Use an LDAP filter to perform a search, for instance (&(uid=myuser)(objectClass=inetOrgPerson))
SQL Lookup – For users that are more comfortable with SQL syntax, a SQL lookup can be done using the syntax defined by the JdbcLdap driver (http://myvd.sourceforge.net/bridge.html)

When searching for users all attributes are returned, as is the DN from Tremolo.

Applications

Unison organizes user facing URLs into "Applications". An application can be either a "User Application" or an "Identity Provider". Both are configured in the same way with the same screens. The difference is that a "User Application" is generally associated with a proxied application. An identity provider is a specialized application that provides identity data to other applications (ie a SAML2 identity provider). An application has two components:

Application Data – Information such as the name, cookie domain and logout url
URLs – individual urls that are used to access the application.

In Unison the key difference between an application and an identity provider is that an identity provider’s URL is static based on the name of the identity provider. Each identity provider can have only one URL where as an application can have any number of URLs

Error Responses

If down stream applications do not generate error pages, you can redirect to specific pages. Add response codes and the page you want to redirect to here.

Application Identity Provider

Every application and identity provider has some common configuration options:

Option	Description	Example
Name	A descriptive name for the identity provider	Saml2
Type	Determines if the application is a User Application or an Identity Provider	User Application
Session Cookie	The name of the session cookie for the application. If you use the same name across applications there will be SSO between them.	Tremolosession
Session Cookie Secure	If checked, the browser will only send the session cookie for this application when connected over an SSL or TLS connection.	true
Session Cookie HTTP Only	If checked, javascript in the browser can not access this cookie	true
Session Inactivity Timeout (Seconds)	The number of seconds that an in-active session can remain open until the user must re-authenticate. Specify 0 for no inactive timeout.	900
Session Cache Timeout in Milliseconds	Number of milliseconds that an authorization decision made about a user exists before it is revalidated	30000
Cookie Domain	The domain to be listed in the cookie. Only domains that end in this domain will receive the session cookie. For sso between applications this cookie should be scoped high enough to be sent to all applications.	Unison.enterprise.domain.com
Logout URI	The uri that will trigger an end to the user’s session	/logout
Session Key Alias	The encryption key to use for encrypting the session cookie	tremolosession

URL

Identity Provider Settings

Each identity provider is managed as a URL. Multiple hosts may be used, but the URI is set based on the application name.

Option	Description	Example
IdP Class Name	The idp implementation type. See the Identity Providers reference guide for individual options	SAML2
Authentication Success Result	The result group to execute when authentication succeeds	My Success Group
Authentication Failure Result	The result group to execute when authentication fails	My Failure Group
Authorization Success Result	The result group to execute when authorization succeeds	My Success Group
Authorization Failure Result	The result group to execute when authorization fails	My Failure Group

For idp type specific configurations, see the IdP Types section.

Application Settings

Each application is a collection of URLs. A URL can contain a set of hosts and URIs to be associated with a set of authorization policies, filters and an end point to proxy to.

Option	Description	Example
URI	The URI to match on	/myapp
Regular Expression	If checked, Unison interprets the URI configuration option as a regular expression	unchecked
Proxy To Application?	If checked, allows for a the Proxy To field to be set.	checked
Proxy To	The URL to proxy to with the URI being set based on request variables. To use the full URI, use ${fullURI}. Any request variable can be used by placing it inside of a ${}.	}
Override URL Host	If set to true, the HOST header and all Referal and Location headers are mapped from the URL in the request to the URL in the Proxy To. If false, the host header is not changed.	true
Authentication Chain	The name of the authentication chain to use with this URI. If the user is already authenticated to a chain of equal or higher value then the user is NOT re-authenticated. If the user is already authenticated to a lower strength chain then the user IS prompted to authenticate.	Default Form Login
Authentication Success Result	The result group to execute when authentication succeeds	My Success Group
Authentication Failure Result	The result group to execute when authentication fails	My Failure Group
Authorization Success Result	The result group to execute when authorization succeeds	My Success Group
Authorization Failure Result	The result group to execute when authorization fails	My Failure Group

Hosts

The list of hosts is used to determine if a request will apply to this URL. Port numbers should not be included. For instance if Unison is listening on port 8443 the host should NOT be myhost.com:8443, it should just be myhost.com. For all hosts, a “*” can be used to specify that all hosts will be accepted.

Filters

Filters are used to process requests before an assertion is created, for instance adding attributes. For information on configuring specific filters, see the Http Filter reference.

Rules

A rule defines how a user should be authorized for this URL. If multiple rules are specified and ANY are satisfied then the user is given access. The below table defines how to specify a rule:

Option	Description	Example
group	Full dn of a static group. Groups may be looked up by clicking on the "Pick Group" button to the left of the "Constraint" box.	Cn=My Group, ou=groups,ou=My Directory,o=Tremolo
dn	A root dn for all users with access. A root may be picked by clicking the "Pick Root DN" button to the left of the "Constraint" box.	Ou=My Directory, o=Tremolo
filter	An LDAP filter	(objectClass=*)
dynamic group	Full dn of a dynamic group	Cn=My Group, ou=groups,ou=My Directory,o=Tremolo
custom authorization	Name of custom authorization	Manager Auth

Mappings

The mappings are used to determine what attributes from a user are included in an assertion. For an attribute to be used in an assertion it must be listed. Mappings are run AFTER filters. The below table details how to define a mapping:

Source Type	Source	Target	Example
user	Map an attribute form the user’s directory object	Name of an attribute	givenName
static	A static value that doesn’t change	The static value	Myvalue
custom	A class that is used to determine the mapping	Class name, see the SDK for details on how to implement	com.mycompany.mapper.Mapper
composite	A composite of attributes and static values. Attributes are defined with ${attributename}. Only attributes that exist before the mappings are run are available	Static and attribute data	${givenName}.${sn}@mydomain.com

The target is the name of the attribute that the mapping will create.

Trusts

A trust defines a connection the Unison will provide identity data. For specific configuration options, see the IdP configuration guide.

User Directories

This section allows for the use of external user stores, such as LDAP directories or Active Directory for authenticating users by Unison. Edit and Delete directories by clicking on the links next to the directory in the list. Add a directory by clicking on the directory type under the “Create Directory” header. See the directory configuration reference for individual configuration options.

Inserts

Inserts can be used to manipulate directory operations, including searches and results. Inserts may be configured either globally or on individual directories. See the insert configuration guide for options for specific inserts.

Add Insert - Add a new insert
Edit - Edit the current insert
Delete - Delete the current insert
Move Up - Move the current insert up in order of execution
Move Down - Move the current insert down in order of execution

====== Configure an Insert

Inserts are configured based on properties. Each insert defines it’s own properties. See the documentation for each individual insert to determine the configuration options.

Option	Description	Example
Name	A descriptive name for this insert	myinsert
Class Name	The Java class name for the insert	com.tremolosecurity.insert.MyInser

Add Property - Adds a new property to the insert
Rmove - Removes the specific property

Authentication Mechanisms

Authentication Mechanisms define the ways in which a user can be authenticated. Prior to being added to an authentication chain, a mechanism must be defined in the section. Unless creating a custom authentication method, it is generally not necessary to add mechanisms here. Every authentication method has its own configuration parameters. See the Authentication Mechanisms section for configuration options on specific mechanisms.

Adding an Authentication Mechanism

Unison supports several authentication mechanisms. In addition, custom authentication mechanisms may be created. When configuring a custom authentication mechanism the below options are available:

Option	Description	Example
Name	A descriptive name for this authentication mechanism. Do not include spaces.	MyAuthMech
Class	The Java class name for the mechanism. If this is a custom mechanism the java class name will appear in the drop down box.	com.tremolosecurity.mech.MyAuthMech
URI	The uri that users will be redirected to when authenticating. This uri should always start with "/auth/".	/auth/myauth

When adding a custom mechanism, properties can be specified by clicking on "Add Property"

Authentication Chains

An authentication chain determines how a user will be authenticated. Every chain has a name, level and list of authentication mechanisms. The name is used to identify the chain in the Tremolo configuration. The level is used to evaluate equivalent chains. For instance a form based authentication might have a level of “1” but certificate based authentication may have a level of “2”. If a user that logs in with a form based authentication but attempts to access an area protected with a level 2 chain the user will be forced to re-authenticate. In the reverse, a user authenticated at a level of 2 will not need to re-authenticate when accessing a URL protected by a level “1” chain.

Chaining mechanisms lets you validate a user’s identity in multiple ways. For instance you may have Integrated Windows Authentication for internal users, but want to provide a form for users that are using external hardware (such as a tablet) or accessing the system remotely. A chain with an IWA mechanism and a form based mechanism where both are “sufficient” would accomplish this. Another possibility is wanting to use certificate authentication with a password as a second factor for software certificates. Using a certificate mechanism and a form based mechanism where both are “required” would accomplish this.

To review individual mechanism configurations see the Authentication Mechanism section.

Authentication Chain

When adding or editing an authentication chain there are two configuration options:

Option	Description	Example
Name	A descriptive label	IWA Login
Level	A number indicating the authentication level	Arbitrary, ie 1
Directory Root	DN of where to search for users in the internal directory tree	o=Tremolo

Adding a mechanism to a chain can be done by clicking on the “Add Authentication Mechanism” link.

Compliance

In order to comply with most security requirements systems must be protected from brute force attacks where a user can repeatedly try to authenticate with passwords until one is found. OpenUnison can help protect against this by adding a compliance section to an authentication chain. This will trigger OpenUnison to track the last time a user failed to log in, succeeded and how many failures have occurred. In order to use this feature the following attributes must be available in the virtual directory:

Description	Data Type	Description
Last Successful Authentication	Directory String OR Long Integer	Stores the last successful authentication in the form of the number of milliseconds since epoch
Last Failed Authentication	Directory String OR Long Integer	Stores the last failed authentication attempt in the form of the number of milliseconds since epoch
Number of failed authentications	Directory String or Integer	The number of failed attempts since the last success

In addition to these attributes, a workflow will need to be created that can update these attributes as needed. The below workflow can be imported as a starting point:

<workflow name="updateLockout">
        <tasks>
                <ifAttrExists name="unisonFailedLogins">
                        <onFailure>
                                <customTask className="com.tremolosecurity.provisioning.customTasks.LoadAttributes">
                          <param name="name" value="unisonFailedLogins"/>
                          <param name="nameAttr" value="uid"/>
                        </customTask>
                        </onFailure>
                </ifAttrExists>
                <ifAttrExists name="unisonLastFailedLogin">
                        <onFailure>
                                <customTask className="com.tremolosecurity.provisioning.customTasks.LoadAttributes">
                          <param name="name" value="unisonLastFailedLogin"/>
                          <param name="nameAttr" value="uid"/>
                        </customTask>
                        </onFailure>
                </ifAttrExists>
                <ifAttrExists name="unisonLastSuccessLogin">
                        <onFailure>
                                <customTask className="com.tremolosecurity.provisioning.customTasks.LoadAttributes">
                          <param name="name" value="unisonLastSuccessLogin"/>
                          <param name="nameAttr" value="uid"/>
                        </customTask>
                        </onFailure>
                </ifAttrExists>
                <provision sync="true" target="activedirectory"/>
        </tasks>
</workflow>

The configuration options for compliance:

Option	Description	Example
Enabled	Determines if compliance should be enabled for this chain	Checked
Maximum Failed Authentication Attempts	The number of allowed attempts until a user is considered locked out	5
Lockout Time in Milliseconds	The number of milliseconds a user is locked out before they can log back in	120000 (20 miuntes)
Failed Attempts Count Attribute	The name of the attribute that stores the number of failed attempts	unisonFailedAttempts
Last Failed Authentication Attribute	The name of the attribute that stores the last failed login attempt Timestamp	unisonLastFailedLogin
Last Successful Authentication Attribute	The name of the attribute that stores the last successful login attempt timestamp	unisonLastSuccessLogin
Update Workflow	The name of the workflow that will update attributes on login attempts	updateLockout
UID Attribute Name	uidAttributeName - The name of the attribute in the provisioning target used to identify this user, MUST be on the authenticated user’s object in the virtual directory	uid

Authentication Mechanism

Individual authentication mechanisms have their own specific configuration. To review individual mechanism configurations see the Authentication Mechanism section. Every mechanism that is on a chain has two options:

Option	Description	Example
Name	The mechanism as defined in the Auth Mechs screen	loginForm
Required	Determine if the mechanism is required or sufficient. If a required mechanism fails to authenticate the user the entire chain fails. If any sufficient mechanisms authenticate the user the chain succeeds.	required - If the mechanism fails, the entire chain fails sufficient - If the mechanism succeeds, the entire chain succeeds

Result Groups

A Result Group is used to do something as a result of an authentication or authorization event. This could be the setting of an HTTP header, creating a cookie or sending a redirect. Result groups can be defined and re-used. For instance a common failed authentication result that will direct the user to a common error page can be created and re-used be several URLs.

Result Group

A result group contains a list of individual results. When a group is executed all of the results in the group are executed. Once the name is specified and saved results can be added by clicking on the “Add Result” link.

Result

There are three types of results: headers, cookies and redirects. Each is detailed below:

Type	Direction	Description	Value
header	inbound	An HTTP header is added to the request. Useful for passing attributes to a backend application.	name=value
cookie	outbound	Cookies are small pieces of information stored in the browser.	name=value
Redirect	outbound	Instructs the user’s browser to go to another page	value

Each result can have one of three sources:

Option	Description	Example
static	A static value, not changed based on the user	Myheader=somevalue
user	Comes from a user attribute	Firstnameheader=givenname
custom	A custom result generator, see the SDK for how to implement	Customheader=com.mycompany.tremolo.Result

Each result has the following configuration options

Option	Description	Example
Type	The type of result, see the above table for a detailed description of the options	header cookie redirect
Source	Where the value for the result will come from, see the above table for a detailed description of the options	static user custom
Value	For header and cookie results, a name=value. For redirects, the url to be redirected to	See above table for examples

Custom Authorizations

A custom authorization allows Unison to make authorization rules on more then a list of users as defined by an LDAP group or filter. This could include information such as the time of day, date, server being accessed, or any other type of information that Unison has access to. Custom authorizations are implemented by implementing the com.tremolosecurity.proxy.az.CustomAuthorization interface of the unison-sdk.

Custom authorizations can be used in any context where an authorization decision needs to be made including:

URLs
Workflow Approvals
Organizations

Before being able to use these implementations the authorizations must be defined on this screen.

When reviewing the main custom authorizations screen:

Name	Description
Authorization Name	The name of the authorization, this will be referenced inside of authorization rules
Authorization Class	Implementation of com.tremolosecurity.proxy.az.CustomAuthorization
Edit	Edit the current authorization
Add New Custom Authorization	Create a new custom authorization rule

Adding and Editing Custom Authorization Rules

Prior to configuring a new authorization rule the class/jar that implements this rule must be uploaded to Unison via the "Manage Proxy" screen. Once uploaded and Unison is restarted, the rule can be configured.

Built-in authorization implementations are documented in the Custom Authorization Rules section.

When authorizing based on a custom rule, use the name of your rule. If your rule takes parameters, list them after a ! in your constraint. For instance to call a rule called Manager1 with a parameter use Manager1!param1!param2 as your constraint.

Provisioning

Provisioning Targets

Provisioning Targets are how Unison pushes, updates and disables account information in individual systems. Targets are utilized inside of workflows (covered in the next section) to manage account information. Custom targets can be created as well, to create a custom target consult the SDK. For specific information configuring targets see the Target Configuration section in this guide. Every target has a mapping associated with it. This mapping makes the target “self-contained”, so it may be used across multiple workflows. The below table details the available mappings:

Source Type	Description	Source	Example
user	Map an attribute form the user’s directory object	Name of an attribute	givenName
static	A static value that doesn’t change	The static value	Myvalue
custom	A class that is used to determine the mapping	Class name, see the SDK for details on how to implement	com.mycompany.mapper.Mapper
composite	A composite of attributes and static values. Attributes are defined with ${attributename}. Only attributes that exist before the mappings are run are available	Static and attribute data	${givenName}.${sn}@mydomain.com

Add Provisioning Target

Click this link to create a new provisioning target

Edit

Click this link to edit an existing target

Delete

Click this link to delete an existing target

Workflows

Workflows are utilized to manage user data inside of a provisioning target or targets. A workflow can be used to manipulate a user’s attributes, add entitlements in the form of groups or attributes and to update the data in a target. Unison workflows follow a tree-like structure, where each set of tasks (where appropriate) can have a set of sub tasks. When all of the sub tasks are complete the next task is run. Tasks that involve a choice, like an approval, can also have a failure track. This lets tasks execute if the test in the task fails. For instance, in the below workflow:

Add the group MyGroup to the user object
Does the user have the attribute myattr with the value myval?
1. Yes
  - Perform a mapping
  - Provision to the target named ldap
  - Resync the user object from the internal virtual directory
2. No
  - Resync the user object from the internal virtual directory

When working with the current level in a workflow, the associated task will be highlighted in white.

The main workflow screen lists the existing workflows and provides a way to quickly import new workflows. The first section will list all of the existing workflows with a link to Edit or Delete the workflow. There is also a link to Add Workflow to create a new workflow.

Importing a Workflow

The main workflow screen provides a section to import an existing workflow. Paste the XML of the workflow into the "Workflow XML" box and select the organization from "Set Organization" and click "Import XML". Note that if you import a workflow with the same name as an existing workflow it will be overwritten by the imported workflow.

Editing Workflows

When editing a workflow, there are three sections. The first section "Workflow Data" defines some common information about a workflow. The "Sub Tasks"/"On Success"/"On Failure" sections shows the various tasks at the current level of the workflow. Finally the graphic on the right hand side has the graphical representation of the workflow.

Workflow Data

This section has the following options:

Option	Description	Example
Name	An internal name for the workflow.	AdminAddToGroup
Label	A descriptive name for the workflow. This is what users in Scale will see.	Add a user to a group.
Description	A description of the workflow for reference purposes in Scale	Requests for administrators
Organization	The organization this workflow should be included in if displayed in Scale.	Root
Include in List	If checked, provides this workflow to Scale when looking up available workflows.	Checked
Dynamic Workflow?	If checked, when this workflow is processed by the workflow listing web services it returns multiple instances of this workflow with parameters filled in by an implementation of the com.tremolosecurity.provisioning.util.DynamicWorkflow interface.	Checked
Dynamic Workflow Class Name	Implementation of com.tremolosecurity.provisioning.util.DynamicWorkflow	com.mypackage.class

Dynamic Workflows

See the dynamic workflows implementation section for specific dynamic workflow implementations.

Task Data

See the task reference for specific information on each task type.

Sub Tasks / On Success / On Failure

Unison workflows are built using a tree structure. This starts at the root and moves down each task. When editing a workflow, sub tasks can be added to the current task if that task allows sub tasks. To add a sub task to the current task, click on "Add Task". The task currently being edited is highlighted in white. To delete a task, select the task and click "Delete Task".

Edit Raw XML

Clicking on the "Edit Raw XML" button will open a screen that will allow you to edit the XML version of the workflow. This can be useful when editing if you know exactly how to edit the XML tags. NOTE: this should only be done if you are an expert, as editing the tags directly can cause the XML to be corrupted and require fixing through the primary XML configuration.

Execute

While editing a workflow it may be useful to run the workflow without having to install Scale or anthor web service interface. Clicking "Execute" lets you run a workflow from inside of the administrative console.

Option	Description	Example
User Identifier Attribute Name	The name of the attribute that identifies the user. The attribute named here MUST be listed in the Attributes section	uid
Attributes	Name/Value pairs of attributes to be passed into the workflow. AT LEAST the attribute named in the "User Identifier Attribute Name" field must be listed. Multi-value attributes may be listed multiple times.	uid/someuser
Groups	List of groups to be passed into the workflow	MyGroup
Parameters	Name/Value pairs to be passed into the workflow’s request object. Typically left blank.
Execute Approvals as Current User	If checked, Unison will NOT send a notification on the first approval seen and will assume that the currently logged in user to the admin interface is an approver. In order for this to work the Unison admin console should be configured with the same source directory data as the user system.	Checked
Request Reason	The reason why the workflow is being executed, recorded in the audit logs	For testing
Approval Reason	If "Execute Approvals as Current User" is checked, the reason for the approval. Recorded in the audit log.	To test the workflow

Organizations

Organizations provide a way to organize workflows in a hierarchy. In a small deployment a single organization may be all thats needed, but in larger deployment it can be difficult to organize workflows. By creating organizations users can navigate through a tree to find the workflow that they need. In addition, organizations provide a mechanism to authorize users to be able to request certain workflows. For instance an organization called "Administrators" may only allow users that are a member of the administrators group to execute workflows. This makes it easier to cut down on extra approvals.

Navigating Organizations

The Organizations screen shows all organizations, with children organizations indented beneath their parent. To navigate to an organization, click on its name.

Organization Data

Option	Description	Example
Name	A descriptive name for the organization. This is what users will see in GetAccess.	Administrators
Description	A description of the organization for reference purposes in GetAccess	Requests for administrators
Show in Portal	If true, shows the organization on the main links page	Show in Requests
If true, shows the organization on the request access page	Show in Reports	If true, shows the organization on the portal page

Authorized Users

If an organization has a list of authorized users then when GetAccess requests the list of organizations for a user this organization is returned IF AND ONLY IF the user satisfies the listed constraints. If no constraints are listed, then all users may view this organization.

Option	Description	Example
Constraint Scope	How the constraint is enforced: Group is a static LDAP group, Filter is an LDAP filter and User is a base DN to verify	Filter
Constraint	The rule of the constraint	Dependent on the Constraint Type

Pick Group

Clicking this button will allow for a group to be picked using a search dialog.

Pick User

Clicking this button will allow for a DN to be picked using a search dialog.

Remove

Clicking this button will remove the constraint from the list.

Add Authorization

Clicking this link will create a new authorization rule for this organization.

Add Child Organization

Creates a new child organization in the currently selected parent.

Delete Organization and Children

Deletes the currently selected organization and all children organizations.

Move into Parent Organization

Moves the currently selected organization and all children organizations into its grand parent organization.

Move Up

Moves the currently selected organization up in the ordered list of children for the selected organization’s parent.

Move Down

Moves the currently selected organization down in the ordered list of children for the selected organization’s parent.

New Parent Organization

Moves the currently selected organization, and all child organizations, into the parent named in the drop down box. Click on "Move" to complete the move.

Message Queue

Unison uses a message queue for all asynchronous provisioning operations. The use of a message queue allows Unison to ensure that workflows are completed, even if targets such as directories and databases are down. Unison encrypts all messages sent to the queue for increased security. There are two modes that Unison can use:

Internal Queue
External Queue

When Unison uses an internal queue, the queue is local to the Unison instance. This provides a simpler deployment model, but Unison servers are not able to failover in case of a failed provisioning task or spread the load across multiple servers. This is the default mode that Unison uses and no actions need to be taken to get this working after installation.

Leveraging an external queue allows for high availability across Unison instances if a workflow fails on one server it can be picked up by another server. External queues can also increase the volume of operations Unison can handle because tasks do not need to be processed on a single box. Any message queue that supports JMS 2.0 is supported by Unison. See the certification matrix for tested and certified queues.

Common Configuration

The common configuration section defines parameters that are common to both scenarios.

Option	Description	Example
Use Internal Queue	Determines if Unison should use the internal ActiveMQ system for message management or an external system.	Checked
Task Queue Name	The name of the queue for managing workflow tasks	TremoloUnisonTaskQueue
Outbound Email Queue Name	The name of the queue for managing emails generated by Unison	TremoloUnisonSMTPQueue
Encryption Key	The session key used to encrypt all task messages.	workflowtasks

Empty Dead Letter Queue

If the message queue you are using doesn’t have a built in capability to re-send messages in the dead letter queue this function can be used to re-process the messages in the dead letter queue. Unison creates attributes that are used to track the the request and which queue it was meant for. Enter the name of the queue for "Queue Name" and press "Resend Messages".

External Queue Configuration

These options are specifically for the case when Unison is leveraging an external queue server. To use an external server, make sure that the client libraries have been uploaded to Unison.

Option	Description	Example
Provider Connection Factory	Implementation of `javax.jms.ConnectionFactory`	org.apache.activemq.ActiveMQConnectionFatory
Maximum Message Producers	Maximum number of threads generating messages	5
Maximum Message Consumers	Maximum number of threads consuming messages	5
Support Multiple Task Queues		Checked
Number of Task Queues	Number of queues if "Support Multiple Task Queues" is checked	5

Connection Factory Parameters

This section defines properties for the connection factory. A property is the name of a getter/setter without the "set" and the first letter is lower case. For instance to set the broker url for ActiveMQConnectionFactory’s setBrokerURL the property name would be brokerURL.

Message Listeners

In addition to workflows, Unison can provide queue services to other components in Unison as well. For instance a schedule task that needs to perform work on user accounts would want to put the work load for each account in a queue, allowing the payload to be worked on by a different server in a cluster and not block the scheduled task from completing. All queue messages are encrypted with the same encryption key as workflow tasks. To implement a task, extend the com.tremolosecurity.provisioning.core.UnisonMessageListener class. Pre-built message listeners are documented in the Unison Message Listeners section.

To add a new listener, click "Add New Listener".

Queue Listener

When editing the configuration of a Queue Listener, choose the class name (or label) and the name of the queue. NOTE: if the queue doesn’t exist Unison will attempt to created it on startup.

Option	Description	Example
Class Name	The name of the class or label	com.company.MyQueueListener
Queue Name	The name of the queue to listen on	MyQueue

Scheduler

Unison includes an integrated scheduler that can be used to schedule task to run on a periodic basis. Unison can either use a local, in memory scheduler or a database scheduler. The database scheduler is recommended for production deployments to ensure that scheduled tasks are only executed once. Unison uses the Quartz scheduler (http://quartz-scheduler.org).

Scheduler Configuration

Option	Description	Example
Scheduler Label	A descriptive label for this scheduler	Unison
IP Mask	This field is used to determine which IP address to use on the system to identify the particular instance	192.168.2
Thread Count	The number of threads the scheduler should use. Must be at least 3	3
Use Database To Store Jobs	If checked, use a database to manage jobs. NOTE: prior to starting Unison the database must be initialed per Quartz' documentation	checked

Job Database

The below options are used when several Unison servers share a single configuration.

Option	Description	Example
Quartz Database Delegate Class Name	The delegate to use to work with the database	org.quartz.impl.jdbcjobstore.StdJDBCDelegate
Driver	The JDBC Driver for the database	com.mysql.jdbc.Driver
URL	The JDBC URL	jdbc:mysql://server/db
User	User to connect to database with	serviceAccountUser
Password	Password to connect to database with
Verify Password	Verify your the password
Max Connections	Maximum number of connections to the database	10
Validation Query	A query that can be used to verify the connection is still active	SELECT 1

To add a new job, click "Add New Job".

Job

When editing the configuration of a job, choose the class name (or label) of the job and give a descriptive name and group name to this job configuration. What you name the job and group are not important to Unison and are only used for organizational purposes. on startup.

Option	Description	Example
Class Name	The name of the class or label	com.company.MyQueueListener
Job Name	The name of the job	MyJob
Job Group	The name of the job group	MyJobGroup

Schedule

See the Quartz cron schedule for details on how to configure a job’s schedule: http://quartz-scheduler.org/api/2.2.0/org/quartz/CronExpression.html

Workflow Tasks

Several tasks can include request parameters in their configuration values. This is useful when using a workflow as a template. Any name/value pair in the workflow’s request object can be included between $. For instance, to include the value of an entry in the request object called "groupName" in your workflow’s Add Group to User would specify "$groupName$" (no double quotes) for the Name. Tasks that take parameters can take any number of parameters and can mix parameters with static text. If a configuration option supports parameters, it will be marked as such in the task documentation below.

Provision to Target

This task is used to push user data to a provisioning target. This task type has the following options:

Option	Description	Example	Supports Parameters
Target	A target as defined in the Targets area of the administration system	LDAP	No
Set Password	If set to true this will create a password on the user. Note that not all targets support password	True/False	No
Full Synchronization	If checked, then the target will update the object in the target to match exactly the current user’s object; potentially removing attributes and entitlements on the user’s object in the target. If unchecked, then only the attribute values on the user’s object will be pushed to the target, in essence “overlaying” it onto the provisioning target	True/False	No
Use Only Attributes on the User Object	If checked, then the provisioning task will ignore any attributes that are listed in the target configuration but NOT explicitly added to the user object in the workflow	Unchecked	No
Use Only These Attributes (Leave Empty for All)	List of attributes to be examined in this step, omit or leave the list empty to allow all of the attributes specified in the target configuration	List of attributes	No

If User Does Not Exist

This task will execute "On Success"" tasks if-and-only-if there is not a user in the internal virtual directory that matches the value of the attribute specified in the current user’s context.

Option	Description	Example	Supports Parameters
User ID Attribute	The attribute to test on	uid, userPrincipalName	No

Add Group to User

The Add Group to User task will an entitlement to the user’s object in Unison. The name of the group MUST match the name of a group in the provisioning target.

Option	Description	Example	Supports Parameters
Name	The name of the group to add, must match the name of the group in a downstream target.	MyGroup	Yes

Synchronize User Session from Directories

When executing a just-in-time provisioning workflow, for instance when using identity federation, once the user’s object is created in downstream targets the user’s object in Unison will need to be “refreshed”. This task updates the internal Unison object.

Option	Description	Example	Supports Parameters
Keep External Attributes?	If true, will keep attributes from the external source (such as an assertion) that were not pushed to downstream targets	True/False	No
Change User Search Root?	If checked, Unison will reload the user’s object from a different search base then the one that was originally used to find the user	Checked	No
New User Search Root	If "Change User Search Root?" is checked, the root of the virtual directory to use to find the user	o=Tremolo	Yes

If Attribute has Value

This task will execute "On Success" tasks if-and-only-if the user’s Unison object has an attribute with a matching value.

Option	Description	Example	Supports Parameters
Name	The attribute to check	MyAttribute	Yes
Value	The value that must be present	MyValue	Yes

If Attribute Exists

This task will execute "On Success" tasks if-and-only-if the user’s Unison object has an attribute with a matching name.

Option	Description	Example	Supports Parameters
Name	The attribute to check	MyAttribute	Yes

Add Attribute to User or Request

As the name specifies, adds a value to the specified attribute of the user or the workflow’s request object

Option	Description	Example	Supports Parameters
Name	The attribute to add	MyAttribute	Yes
Value	The value to add	MyValue	Yes
Remove	If checked and the value is empty, remove the entire attribute; if true and the value is set, remove only that value of the attribute	Unchecked	Add to Request

Map User Attributes

This task will execute sub tasks in the context of a mapped user object. The object that results from the mapping task will be distinct from the user object for the rest of the workflow. For instance if because of the mapping a user object now has an attribute named “NewAttr” with the value “SomeVal” then this attribute will exist for all sub tasks. Once all sub tasks are complete however, this attribute will no longer for other tasks outside of this mapping.

Option	Description	Example	Supports Parameters
Strict Mapping	If checked, the user object used for sub tasks will only have attributes that are explicitly listed in this mapping.	True/False	No

For all mapping options, the source and target support parameters. The below table details the mapping options:

Source Type	Description	Source	Example
user	Map an attribute form the user’s directory object	Name of an attribute	givenName
static	A static value that doesn’t change	The static value	Myvalue
custom	A class that is used to determine the mapping	Class name, see the SDK for details on how to implement	com.mycompany.mapper.Mapper
composite	A composite of attributes and static values. Attributes are defined with ${attributename}. Only attributes that exist before the mappings are run are available	Static and attribute data	${givenName}.${sn}@mydomain.com

Call Workflow

This task allows for another workflow to be called. This allows for the creation of modular workflows. For instance a modular workflow can be created that requires 2 approvals before provisioning to a resource. This workflow can be included in a self-service request from the portal and a helpdesk application with the same results without having to duplicate the workflow.

Option	Description	Example	Parameters Supported
Workflow	The name of the workflow to call	My Workflow	No

Approval

The approval task allows for steps to require approval from a pre-set list. The approval can be constrained by a static group, an LDAP filter or a particular user or base. Approvals are not bound to a resource or target, so any number of approvals or scenarios may be implemented.

Each approval can have a series of escalations. An escalation is executed based on the Time to Pass and Units for each escalation. Escalations are sequential, for instance if the first escalation is marked for running after 5 days and the second escalation is marked for running after 5 days then it will take 10 days for the second escalation will run. In addition to providing a time based escalation, an implementation of the com.tremolosecurity.proxy.az.VerifyEscalation interface may be used to add logic to the decision. Escalations may have the same approvers as the approval.

Finally, an approval can have a failure rule. If the escalation policy is set to "Leave" then nothing happens when no approvers are available for an escalation. However if "Assign" is used then the failure policy is treated as an escalation and the approvers as configured in the policy.

Option	Description	Example	Parameters Supported
Label	A descriptive name for this approval	Access to the portal	Yes
Email Template	A template for the email sent to approvers to notify them that they have an open approval. Attributes from the REQUESTOR’s object can be placed in the email by enclosing it in a “${}”. For instance, to include the user’s full name user “${givenName} ${sn}”	You have an open approval waiting. Please go to https://unison.mycompany.com/approvals/ to complete the approval. Requesting user: ${givenName} ${sn} ${mail} ${ou}	Yes

====== Approvals

The definition of who may approve a given request can be defined by using:

Group – Any LDAP group from Unison’s internal virtual directory may be specified
User – The specific DN of a user or search base containing users
Filter – An LDAP filter of all users who are able to approve
Custom – A custom rule configured on the "Custom Authorizations" screen

Multiple sets of approvers may be specified. If ANY of the users who match these constraints approve of the request then the approval moves forward. For all scopes of an approval, parameters are supported for the constraint.

Scope	Constraint	Example
Group	Full dn of a static group	Cn=My Group, ou=groups,ou=My Directory,o=Tremolo
User	A root dn for all users with access	Ou=My Directory, o=Tremolo
Filter	An LDAP filter	(role=Admin)
Custom	A custom authorization rule configured on the "Custom Authorizations" screen	ManagerLevel1

Notify User

This task provides a way to send an email to the requester of the workflow. This can be used to notify the user of a successful execution, request more information, etc. Emails are sent from the server specified in the “Approval DB” section of the configuration interface. If the requester is different then the subject of the workflow, then the requester is notified UNLESS the unison.sendToSubject property is stored in the workflow’s request object. The value does not matter.

Option	Description	Example	Parameters Supported
Subject	What should the subject line of the email be?	Request for access has been approved	Yes
Mail Attribute Name	The name of the user attribute that has the user’s email address	mail	No
Message	A template for the email sent to approvers to notify them that they have an open approval. Attributes from the REQUESTOR’s object can be placed in the email by enclosing it in a “${}”. For instance, to include the user’s full name user “${givenName} ${sn}”	${givenName} ${sn}, Thank you for registering for the portal. Your request is waiting approval. Thanks The Team	Yes

Custom Task

Unison’s workflow engine provides the ability to create custom tasks written in Java. This task allows for those tasks to be added to the workflow. See the documentation for each individual custom task to see if it supports parameters.

Option	Description	Example
Class Name	Implementation of the com.tremolosecurity.proxy.auth.secret.CustomTask interface. Implementations should be uploaded from the “Manage Proxy Libraries” screen.	com.tremolosecurity.proxy.auth.secret.CreateSecretQuestionsTask
Initialization Parameters	Name/Value pairs that can be passed to the task when its initialized. These parameters can have multiple instances of the same parameter	AttributeName = something

Delete User

This task will delete a user from the target. There are no configuration parameters.

Approvals

This screen is used for configuring the approval database. This database is utilized for tracking approvals, workflows and changes to users.

Option	Description	Example
Enabled	If not checked, and approval database is not registered. All provisioning actions are logged to the tremolo-service.log	Checked

Approval and Audit Database

If the above checkbox is enabled, this information is for the approval database.

Option	Description	Example
Hibernate Dialect	The class of the Hibernate dialect for your database	org.hibernate.dialect.MySQLDialect
Additional Hibernate Parameters	Additional parameters to Hibernate
Hibernate Mapping File	Optional - The mapping file (.hbx.xml) to use if the default mapping doesn’t work, must be loaded like a jar file	oracle12c.hbm.xml
Let Hibernate Create Schema	If checked, create tables. After initial configuration, you may want to disable this depending on the dialect.	Checked
Driver	The class of the JDBC driver	com.vendor.jdbc.Driver
URL	The JDBC URL for accessing the database	jdbc:driver://host/db
User	The user for connecting to the database
Password	The password for the database
Maximum Connections	The maximum number of connections to the database	10
Maximum Idle Time	The maximum time a connection can be idle before its closed in milliseconds	1000
Validation Query	A query that will be used to test if a connection is active on checkout	SELECT 1
Workflow Encryption Key	An encryption key, defined in the CERTS section to encrypt workflows in process in the database	workflowkey
User Identifier Attribute	The name of the attribute on the user that is used to identify them	mail
Report Approver Attributes	The names of attributes that are added to the approvers table. These attributes are meant to be used for reporting and audits.	sn cn givenName mail
Report User Attributes	The names of attributes that are added to the users table. These attributes are meant to be used for reporting and audits.	sn cn givenName mail
Mask Attributes	The names of attributes who’s values will NOT be written to the audit database	secretKey

SMTP Settings

Option	Description	Example
Host	The host of the SMTP server	Smtp.google.com
Port	The port of the SMTP server	25 or 587 (google)
User	The user used for authenticating	donotreply@mycompany.com
Password	Password for accessing the SMTP server
Validate	Validate password
Subject	The subject used for approval notifications	Approval Waiting
From	Email address in the “From” of the email	donotreply@mycompany.com
Use SSL	Check if the server uses SSL	True

Portal URLs

While Unison can provision access to applications, its also can be important to be able to tell users about what applications they have access to. To provide this, Unison has a portal URL api that can be configured on this screen. Each URL can be assigned to an organziation for situations where there are hundreds of applications a user may have. Each portal URL has the following options:

Option	Description	Example
Name	Descriptive name of the link	MyApplication
Label	The value show to the user as a link	My Application
URL	The URL to be used for this link	https://www.myapp.com/
Organization	The organization this link should be displayed for
Icon	A PNG file that will be used for this link. If none is specified then a default one will be used. All PNG files shold be the same size, with a recommendation of 240x210.
Authorized Users	Authorization rules that specify which users will see this link.

Reports

Unison provides a simple reporting mechanism that can be used to provide reports via the web services API. These reports can be used by Scale or any other client via the API. Reports have the following features:

Header Sections	Data sets can be broken out be groups and include a header section for each data set
Parameters	Unison reports can accept any of the four parameters: - currentUser - The currently logged in user - userKey - Specify a specific user - beginDate - Date for the beginning of a date range - endDate - Date for the end of a date range
Authorizations	Reports are categorized into organizations, each having an authorization

Each report has the following configuraiton options:

Option	Description	Example
Name	A descriptive name for the report	Completed Approvals
Description	A desctive blurb about the report	All approvals completed between two dates
Organization	The organization that this report will sit in	Root Organization
SQL	The SQL that drives this report. All paraeters must be marked as a question mark (?)	SELECT id, name as `Workflow Name` FORM workflows where beginTS > ? and endTS < ?
Header Fields	Fields that should be displayed in a data set’s header. NOTE - fields MUST map to a field that is in the SQL SELECT clause.
Data Fields	Fields that should be displayed in a data set. NOTE - fields MUST map to a field that is in the SQL SELECT clause.
Parameters	List of which of the above available parameters are used by this report
Break Report into Groups	If checked, then each report will be a collection of smaller sub reports rather then one large report.	Checked
Group By	If Break Report into Groups is checked, this field will tell Unison how to break the data set up. In order for the data set to be broken up properly, the field specified in this option should be the ORDER BY field in the SQL	id

Exporting Reports

Reports may be exported for easier migration across environments. To export a report, simply click on the "Export Reports" link, choose which reports to export and click "Export".

Importing Reports

Exported reports may be directly imported into Unison. Under "Import Reports" click on "Browse…" and choose the file you wish to import. Follow the prompts to complete the import process.

Database Schema

Unison’s provisioning model uses an open table format for storing relationships and audit data from the provisioning process. This format allows for custom reporting as well as storage in any SQL database. The below diagram and descriptions provide information on how these tables relate and provide the baseline for writing reports using you’re favorite reporting tools.

users

This table lists the users and certain that attributes that have been processed. This table should be updated based on the user attributes to be tracked in reports. The only two fields in this table that are required are id and userKey. Each additional field should be the same name as an attribute in the workflow request. For instance if the givenName, sn and mail attributes are to be tracked then they should have fields in this table called givenName, sn and mail.

Field	Type	Foreign Key	Description	Example
id	int (Primary Key, Auto Increment)		entry id	1
userKey	varchar(255)		User identifier	User ID

approvers

This table lists the approvers and certain attributes that have been processed. This table should be updated based on the approver attributes to be tracked in reports. The only two fields in this table that are required are id and userKey. Each additional field should be the same name as an attribute in the workflow request. For instance if the givenName, sn and mail attributes are to be tracked then they should have fields in this table called givenName, sn and mail.

Field	Type	Foreign Key	Description	Example
id	int (Primary Key, Auto Increment)		entry id	1
userKey	varchar(255)		User identifier	User ID

targets

This table lists the name of all workflow targets as configured in the administration system. It is automaticly populated when Unison is started or the configuration is re-loaded. It should only be used for reporting and should not be updated manually.

Field	Type	Foreign Key	Description	Example
id	int (Primary Key, Auto Increment)		entry id	1
name	varchar(255)		Target Name	AD-MyEnterprise.com

workflows

The main driving table, each row tracks a workflow and is the main table for tracking all workflows.

Field	Type	Foreign Key	Description	Example
id	int (Primary Key, Auto Increment)		entry id	1
name	varchar(255)		Workflow name as configured in the administration system	AddUser
startTS	datetime		Timestamp for when the workflow was started	2012-11-15 11:45:23 AM
completeTS	datetime		Timestamp for when the workflow was completed, null is not completed	2012-11-15 11:45:23 AM
userid	int	users.id	Link field to the user the workflow is acting on	1
requestReason	text		The reason why this workflow is being executed	Need access to do my work

approvals

Tracks each approval needed in a workflow. Each workflow’s state is stored in an encrypted and Base64’d object. Once the approval is complete, the workflow object is null.

Field	Type	Foreign Key	Description	Example
id	int (Primary Key, Auto Increment)		entry id	1
label	varchar(255)		Approval label as configured in the administration system	Owner Approval
workflow	int	workflows.id	1
workflowObj	text		Encrypted and Base64’d workflow state. If the approval is complete, null
createTS	datetime		Timestamp for when the approval step was created	2012-11-15 11:45:23 AM
approvedTS	datetime		Timestamp for when the approval was completed, null if not completed	2012-11-15 11:45:23 AM
approver	int	approvers.id	Link field to the approver that acted on this approval. null if not yet approved.	1
approved	int		1 if approved, 0 if denied	1
reason	text		Reason for the approval action (denied or approved)	More information needed

allowedApprovers

Link table for determining who can act on an approval. This table is primarily for use by the web service to list who can act on an approval and is populated when the approval is created in the workflow based on the rules configured in the administration system. When the approval is executed, it still checks against the rules configured in the administration system.

Field	Type	Foreign Key	Description	Example
id	int (Primary Key, Auto Increment)		entry id	1
approval	int	approval.id	ID of open approval	1
approver	int	approvers.id	ID of potential approver	1

auditLogType

This table is a lookup table for various audit log types. Its populated with the values below.

Field	Type	Foreign Key	Description	Example
id	int (Primary Key, Auto Increment)		entry id	1
name	varchar(255)		Audit Log Entry Type	See below table

Valid Entries:

id	name
1	Add
2	Delete
3	Replace

auditLogs

This table tracks all changes processed by Unison’s provisioning engine.

Field	Type	Foreign Key	Description	Example
id	int (Primary Key, Auto Increment)		entry id	1
isEntry	int		1 if the action is against the entry, 0 if its against a particular attribute	1
actionType	int	auditLogType.id	ID of action type	1
userid	int	users.id	ID of user being acted upon	1
approval	int	approvals.id	ID of approval, 0 if no approval was needed	1
attribute	varchar(255)		The name of the attribute being acted on	uid
val	varchar(255)		The value being set	SomeUser
workflow	int	workflows.id	The id of the workflow being executed	1
target	int	targets.id	The id of the target effected	1

Directory Configuration

At the core of Unison is an LDAP virtual directory that is used to provide Unison with identity data from any directory or database in the enterprise. Each directory supported by Unison has its own configuration options defined in this section.

Normalization and DN Mapping

Unison creates an internal virtual directory of the directories configured. This provides tremendous flexibility. The root dn for a directory is based on the name of the directory. For instance if a directory is named “My Directory” then the root will be “ou=My Directory,o=Tremolo”. DN attributes are also mapped. If a user’s DN is cn=My User,cn=Users,dc=domain,dc=com for “My Directory” then the DN in Unison will be “cn=My User,cn=Users,ou=My Directory, o=Tremolo”.

In addition to mapping DNs, Unison normalizes all data into the inetOrgPerson standard. This means that when integrating an Active Directory into Unison the samAccountName will be mapped to uid, the member attribute will be mapped to uniqueMember.

Testing Configurations

Unison tests the directory configuration whenever it is saved. If there is an error in testing the connection, it will be displayed.

Inserts

Unison’s integrated virtual directory, based on the open source MyVirtualDirectory, supports inserts that are similar to the HttpFilters that Unison supports and HttpServletFilters used when developing J2EE applications. For a list of standard inserts, see the MyVirtualDirectory website (https://www.tremolosecurity.com/myvirtualdirectory/). Inserts can either be configured globally from the “Directories” screen or on individual directories. When configuring an insert click on “Add Insert”.

Insert

When configuring an insert this screen is used to select the insert class and set configuration properties with the following options:

Option	Description	Example
Name	A descriptive name for the insert	MyInsert
Class Name	The class name of the insert	com.tremolosecurity.proxy.myvd.util.CorruptObjectGUID
Property	The name of the configuration property	MyProperty
Value	The value of a configuration property	MyValue

Properties may be edited in place, added or removed using the appropriate buttons.

Directory Types

ActiveDirectory

Configuration of an Active Directory forest with the following options:

Option	Description	Example
Name	A descriptive name for the directory	MyForest
User Directory	Determines if this directory stores user objects (Default is True)	True / False
Enabled	Determines if this directory will be started (Default is True)	True / False
Enabled	Determines if this directory will be started (Default is True)	True / False
Remote Base	The DN of the root Unison should connect to	DC=domain,DC=com
Host	The host for the forest, may be a load balancer	Ldap.myforest.com
Port	The port to connect to, generally 389 for open ports, 636 for secure ports	389 / 636
Bind DN	The full DN, unmapped, of a service account user	cn=svcact,cn=Users,dc=domain,dc=com
Bind Password	The password for the service account
Use SSL	Determines if the connection to the forest is secure. Either the connection certificate or it’s root certificate must be trusted
Use Kerberos	If SSL is not available, Kerberos authentication can be used for authenticating Unison users. In order for this option to work the forest must be configured on the IWA authentication mechanism.
Max Timeout (milliseconds)	The maximum amount of milliseconds that an operation can take before erroring out.	30000
Stale Connection Timeout (milliseconds)	The maximum amount of milliseconds that a connection can remain locked until it is considered stale. Once a connection is considered stale the connection is closed and re-added to the pool.	60000
Minimum Number of Connections	The minimum number of connection to open	10
Maximum Number of Connections	The maximum number of connection to open	100
Heart Beat Interval in Milliseconds	Interval to send a heart beat	30 seconds
Use Paging	Active Directory by default will only support returning 500 objects in a single search. Enabling this option allows for the use of pages to return larger result sets transparently. This setting is useful when Unison is used as a virtual directory to perform large searches.	checked
Page Size	When used with "Use Paging", determines the size of each "page" when returning results. Should be less then 500.	450

LDAP Directory

Configuration of standard LDAP Directory with the following options:

Option	Description	Example
Name	A descriptive name for the directory	MyForest
User Directory	Determines if this directory stores user objects	True / False
Enabled	Determines if this directory will be started (Default is True)	True / False
Remote Base	The DN of the root Unison should connect to	DC=domain,DC=com
Host	The host for the forest, may be a load balancer	Ldap.myforest.com
Port	The port to connect to, generally 389 for open ports, 636 for secure ports	389 / 636
Bind DN	The full DN, unmapped, of a service account user	cn=svcact,cn=Users,dc=domain,dc=com
Bind Password	The password for the service account
Use SSL	Determines if the connection to the forest is secure. Either the connection certificate or it’s root certificate must be trusted
Stale Connection Timeout (milliseconds)	The maximum amount of milliseconds that a connection can remain locked until it is considered stale. Once a connection is considered stale the connection is closed and re-added to the pool.	60000
Minimum Number of Connections	The minimum number of connection to open	10
Maximum Number of Connections	The maximum number of connection to open	100
Heart Beat Interval in Milliseconds	Interval to send a heart beat	30 seconds
Use Paging	Active Directory by default will only support returning 500 objects in a single search. Enabling this option allows for the use of pages to return larger result sets transparently. This setting is useful when Unison is used as a virtual directory to perform large searches.	checked
Page Size	When used with "Use Paging", determines the size of each "page" when returning results. Should be less then 500.	450

Admin

An admin directory stores a single static user. The user in the Admin directory always has the attribute uid to identify the user. While intended for use by the administration system an Admin directory can be used to create static users in Unison with the following options:

Option	Description	Example
Name	A descriptive name for the directory	MyForest
User Directory	Determines if this directory stores user objects	True / False
Enabled	Determines if this directory will be started (Default is True)	True / False
Login ID	The user’s login name	Myuser
Password	The user’s password

Amazon SimpleDB

Unison can use Amazon SimpleDB to store user and group information. This allows for a cloud based solution with no storage or backup footprint. This can provide an extremely effective way to store cloud based identities without having to deploy a cloud based LDAP directory. In order to use this directory type you must have an Amazon Web Services account. This directory should be used in conjunction with the Amazon SimpleDB provisioning target.

Option	Description	Example
Name	A descriptive name for the directory	MySimpleDB
User Directory	Determines if this directory stores user objects	True / False
Access Key	The access key generated by Amazon Web Services
Secret Key	The secret key provided by Amazon Web Services
User Domain	The domain to store user information in	Users
Group Domain	The domain to store groups in	Groups

BasicDB

The BasicDB directory is used to provide identity data from a relational database. Users in a BasicDB can be used for authentication ONLY when passwords are created via the Relational Databases provisioning target. Otherwise this insert can be used only for user attribute data. The database can store users and optionally groups using a many-to-many relationship. It does not require a specific schema, but the tables specified must follow a particular pattern:

Schema for Users Only

Schema for Users and Groups

Option	Description	Example
Name	A descriptive name for the directory	MySimpleDB
User Directory	Determines if this directory stores user objects	True / False
Driver	The class of the JDBC driver	com.vendor.jdbc.Driver
URL	The JDBC URL for accessing the database	jdbc:driver://host/db
User	The user for connecting to the database
Password	The password for the database
Maximum Connections	The maximum number of connections to the database	10
Users Table Name	The name of the table that stores the user objects	Users
Users Table Primary Key	The name of the column in the user table that is the primary key	id
Support User Objects?	If checked, this directory will present user objects, otherwise only groups and memberships	Checked
Support Authentication	If checked, the directory will support authentication	Checked
Password Column	If Support Authentication is checked, the name of the column in the Users table that holds the PBKDF2 encoded password.	password
Connection Validation Query	Query used to test connections when being checked out of the pool	SELECT 1
Idle Connection Test Period (Seconds)	Number of seconds unchecked out connections are tested	30
Unreturned Connection Timeout (Seconds)	Number of seconds a connection can checked out before the connection is closed and returned to the pool. 0 means it will not be forced.	0
Checkout Timeout (Milliseconds)	Number of milliseconds to wait for a connection to be available.	30000
Use Groups?	Determines if this database stores group information about the users in the db	True/False
Member Search Base	If not supporting user objects, supplies the search base to look for the users listed as group members, searched for by the uid attribute	dc=domain,dc=com
Group Table Name	The name of the table that stores group information	Groups
Group Table Primary Key	The name of the primary key of the group table	Id
Link Table Name	The name of the table used to link users and groups	LinkTable
Link Table User Column	The name of the column in the link table that maps to the user’s primary key	User
Link Table Group Column	The name of the column in the link table that maps to the group’s primary key	Groups

User Mappings

This area is where ldap attributes are mapped to database columns. The uid LDAP attribute MUST be mapped to a database column.

Group Mappings

This area is where ldap attributes are mapped to database columns. The cn and uniqueMember LDAP attributes MUST be mapped to a database column.

Remote Schema

The internal virtual directory in Unison does not provide an LDAP schema. If a schema is needed by an application, this directory type can be used to proxy the schema of another directory.

Option	Description	Example
Name	A descriptive name for the directory	MySchema
User Directory	Determines if this directory stores user objects	True / False
Remote Base	The DN of the root Unison should connect to	cn=SubSchema
Host	The host for the forest, may be a load balancer	Ldap.myforest.com
Port	The port to connect to, generally 389 for open ports, 636 for secure ports	389 / 636
Use SSL	Determines if the connection to the forest is secure. Either the connection certificate or it’s root certificate must be trusted

NoOp

The "NoOp" directory is a placeholder for configuring custom directory types. This directory should use inserts for performing searches and authentication.

Option	Description	Example
Name	A descriptive name for the directory	MySchema
User Directory	Determines if this directory stores user objects	True / False

Joiner

The joiner creates a view of two namespaces that are "joined" based on a filter. This provides the ability to add attributes to directories by storing the new attributes in a separate directory or database without having to change the directory’s schema. It is recommended that the two directories being joined are not "User Directories" (make sure User Directory is left unchecked). This way you can’t run into a circular reference.

Option	Description	Example
Name	A descriptive name for the directory	MyJoiner
User Directory	Determines if this directory stores user objects	True / False
Primary Name Space	The name space that will drive the directory structure of the joined name spaces. All attributes from this name space are available.	ou=addomain,o=Data
Joined Name Space	The name space to be joined to the primary name space. This should be the name space that stores additional attributes.	ou=db,o=Data
Joined Attributes	List of attributes from the joined name space that will be available to Unison.	givenName,sn,etc
Joined Object Classes	Optional, list of objectClasses to limit the join to	inetOrgPerson
Join Filter	A filter that is used to combine objects. When including an attribute from the joining entry prepend the attribute with "ATTR.". For instance, to combine a user based on the uid attribute the filter would be "(uid=ATTR.uid)"	(uid=ATTR.uid)
Bind Primary Namespace First	If set to true then the joiner will first attempt to bind against the primary namespace BEFORE trying to bind to the joined namespaces. Otherwise bind first to the joined namespace then the primary	Checked

MongoDB

The MongoDB insert provides search capabilities via LDAP of a mongodb database. Each collection maps to an OU. Each document MUST have two attributes:

unisonRdnAttributeName - The name of the attribute that stores the rdn of the directory object
The attribute named in unisonRdnAttributeName

While not strictly required, an objectClass attribute should also be present for the objects to work consistently with LDAP.

At this time ONLY search capabilities are implemented. For updates and modifications, see the provisioning target.

Option	Description	Example
Name	A descriptive name for the directory	MyMongoDB
MongoDB Connection URL	A MongoDB connection url as defined by https://docs.mongodb.com/manual/reference/connection-string/	mongodb://dbs.tremolo.lan:27017
Database Name	The name of the database to use	unison

K8sCrdMyVD

This insert will add an LDAP interface to the User objects stored as Kubernetes custom resources. In order to work, the CRDs MUST be created.

Option	Description	Example
Kubernetes Target	The name of an OpenShift (kubernetes) target	k8s
Namespace	The namespace to search for User objects	unison

OpenShiftMyVD

The OpenShiftMyVD will create an LDAP directory of OpenShift user objects. Groups are listed as attributes on objects, not as individual objects.

OpenShift Target	The name of the openshift target to use for connecting to OpenShift	openshift

Insert Reference Guide

These inserts are specific to Tremolo’s Unison and are not included with the MyVirtualDirectory project.

External Group Members

The External Group Members insert allows an Active Directory forest to store group members that are not a member of the forest or a trusted forest. This insert requires an attribute to be defined that will store the Unison DN of a user in the specified attribute and merge it with the uniqueMember attribute of the group.

Class Name	com.tremolosecurity.proxy.myvd.inserts.ad. ExternalGroupMembers
externalGroupAttrName	The name of the attribute for storing the DN, must be allowed on the group objectClass

TOTP Authentication

The TOTP Authentication insert provides TOTP authentication for users who have been provisioned with a TOTP token using the CreateOTPKey custom provisioning task by adding the current key to the end of the password after a ":". So if the current code is 123456 and your password is "secret" then the correct password would be "secret:123456".

Class Name	com.tremolosecurity.proxy.myvd.inserts.otp.AuthTOTPInsert
attribute	The name of the attribute that stores the token
encryptionKey	The name of the encryption key managed by Unison
window	Number of 30 second windows a key should be valid for

Add Groups From Provisioning Target

This insert creates a virtual attribute, which can only be viewed but not searched, that shows the groups a user is a member of from a specific provisioning target.

Class Name	com.tremolosecurity.proxy.myvd.inserts.AddGroupsFromProvisioningTarget
attributeName	The name of the attribute to create
targetName	The name of the target to search
uidAttribute	The name of the attribute used to identify the user in the provisioning target
label	A prefix to put on the group
targetRoleAttribute	The name of the attribute in the target that stores groups, optional

Add Attributes From Provisioning Target

This insert creates a virtual attribute, which can only be viewed but not searched, that shows specified user attributes from a specific provisioning target.

Class Name	com.tremolosecurity.proxy.myvd.inserts.AddAttributesFromProvisioningTarget
attributeNames	The name of the attributes to load from the target
targetName	The name of the target to search
uidAttribute	The name of the attribute used to identify the user in the provisioning target
label	A prefix to put on the group

Authentication Lockout

This insert performs the same function as the compliance feature of authentication chains, but in the internal virtual directory. See the compliance section of the authentication chain for details on how to deploy.

Class Name	com.tremolosecurity.proxy.myvd.inserts.compliance.AuthLockoutInsert
maxFailedAttempts	The number of attempts before a user is locked out
maxLockoutTime	The amount of time, in milliseconds, that a user should be locked out after too many failed attempts
numFailedAttribute	Attribute that stores the number of failed login attempts
lastFailedAttribute	Attribute that stores the last failed login attempt timestamp, stored as the number of seconds since EPOCH
lastSucceedAttribute	Attribute that stores the last successful login attempt timestamp, stored as the numer of seconds since EPOCH
updateAttributesWorkflow	Name of the workflow to update directory attributes
uidAttributeName	The name of the attribute to identify the user

Authentication Mechanisms

Unison supports multiple ways to authenticate a user. Each mechanism has two configuration points:

Mechanism – In the Auth Mechs section, global to all authentication chains
Chain – Configuration for a specific authentication chain

Form Login

An HTML login form. All login forms must be stored in the apps/tremolo-admin/auth/forms directory. Forms can be static HTML or JSP pages. See apps/tremolo-admin/auth/forms/defaultForm.jsp.

Mechanism

No configuration Parameters

Chain

Option	Description	Example
Login JSP	The URI for the jsp page used to log the user in	/auth/forms/defaultForm.jsp
User Attribute Name/LDAP Filter	Either an attribute name OR an ldap filter mapping the form parameters. If this is an ldap filter, form parameters are identified by ${parameter}	Attribute name : uid Filter : (&(uid=${username})(l=${locationName}))
Search Using LDAP Filter	If true, the user is determined based on an LDAP filter rather than a simple user lookup

SAML2

This mechanism is used to authenticate the user using a SAML2 assertion. The HTTP-POST and HTTP-REDIRECT profiles are supported.

Mechanism

Some identity providers, such as Active Directory Federation Services, do not have a way of providing a default RelayState for IdP Initiated SSO. In such cases, a mapping from the Referer HTTP header to a default relay state may be configured on the mechanism.

Chain

When configuring the authentication chain there are two options:

Manually – Provide specific configuration options
Using MetaData – User the metadata from an identity provider to automatically configure most options

Identity Provider Information

This section are specific to the identity provider this chain is associated with.

Option	Description	Example
Optional Identity Provider EntityID	The URL for the IdP’s EntityID, needed for Single Logout	https://www.myidp.com/fed/aunth20Response
Identity Provider POST URL	The URL for the IdP’s POST endpoint	https://www.myidp.com/fed/aunth20Response
Identity Provider Redirect URL	The URL for the IdP’s REDIRECT endpoint	https://www.myidp.com/fed/aunth20Response
Optional Identity Provider Logout URL	The URL for the IdP’s Single Logout Service HTTP-Redirect endpoint; requires that the Signature Certificate and Optional Final Logout URL be set	https://www.myidp.com/fed/aunth20Response
Trigger Logout URL	Set the url to redirect to to trigger a logout when receiving a LogoutRequest	https://myhost.domain.com/logout
Optional Final Logout URL	URL to redirect users to after receiving a response from the identity provider indicating a successful single logout	https://www.myhost.com/logout
Require Signed Assertions	Should the assertion be signed?
Require Signed Response	Should the entire response (including the assertion) be signed?
Signing Algorithm	The algorithm to use when signing AuthnRequest and SingleLogoutRequest messages to the identity provider
Signature Certificate	The name of the certificate used to validate the signed response / assertion	Certificate must be trusted in the Certs section
Required Authentication Type	How does the user need to be authenticated	Choose “other” to specify one manually or leave blank to not require an authentication type
Other Authentication Type	If “Other” is chosen for the Required Authentication Type, one can be specified here	A SAML2 recognized context class ref

Service Provider Information

When Unison is authenticating using SAML2 its acting as a Service Provider. These options dictate how the SP will work.

Option	Description	Example
Force response to SSL	For sites that do not work well with SSL this feature will allow an application to use federation for https, but switch back to HTTP once authentication is complete. Note: for this feature to work sesison cookies must NOT be marked as secure.	If true, the certificate used to sign the metadata must be trusted in the Certs management system
Require Signed MetaData	When importing metadata, must it be signed?	If true, the certificate used to sign the metadata must be trusted in the Certs management system
Require Encrypted Assertion	Must assertions be encrypted? If false, encrypted assertions will still be accepted if properly encrypted
Assertion Decryption Key	If an assertion is encrypted, which key should be used to decrypt it?	Key must be created in the Certs management area
Sign Authentication Requests	Should authentication requests be signed before being sent to the Identity Provider?
Authentication Request Signing Key	If authentication requests are signed, what key to use to sign the request	Key must be created in the Certs management area
Optional Jump Page URI	An optional setting to allow for a page to be displayed to the user prior to SP initiated federation being triggered. This page is for notifying the user they will be redirected for authentication.	Empty to be ignored or /auth/forms/jump.jsp for the default jump page

Directory Mapping Information

Once an assertion is validated, it may map to a user. If the user can be mapped, then the user is loaded from the directory and the attributes from the directory are merged with whatever attributes were in the assertion. If a user can’t be mapped then a user object is created based on the information in this section.

Option	Description	Example
LDAP Name Attribute	Name of the attribute that the NameID in the assertion	Uid
DN Org Unit	What the ou of the DN for an unlinked user should be. For instance if a user named testuser is authenticated but not associated with a user in the directory and the value of this setting is SAML2 the user’s DN will be uid=test,ou=SAML2,o=Tremolo	External users
Default Object Class	If a user can not be mapped, the objectClass that should be used when constructing the user object	inetOrgPerson
Do Not Attempt to Link to Directory	If checked, Unison will skip attempting to find an object in the internal virtual directory to associate with this user. This should be checked when using Just-In-Time provisioning and will reload the context AFTER the workflow executes.	false

Generating Meta Data

From the chain configuration screen SAML2 meta data can be generated for this chain. When specifying the host name ensure that the port is included. Meta data can optionally be signed with the specified certificate.

Anonymous

Anonymous authentication is used for scenarios when user authentication is not needed. Its not generally needed for Unison.

Mechanism

Option	Description	Example
RDN	Attribute name of the anaonymous user	uid
Value	Attribute value of the anonymous user	Anonymous

In addition to the user name, additional attributes can be added by clicking "Add Attribute".

Chain

There are no chain specific configuration options.

Basic

Basic authentication can be used for simple authentication tasks.

Mechanism

There are no mechanism configuration options.

Chain

Option	Description	Example
Realm Name	The name of the realm presented to the user when authenticating	My Authentication Server
User Attribute Name	The name of the attribute to use when looking for the user	uid

IWA

IWA, or Integrated Windows Authentication, allows a user to authenticate using their current windows Kerberos token. For IWA to work the user MUST be logged into a desktop that is a member of one of the domains configured on this mechanism. NTLM is NOT supported.

Mechanism

Every domain that will validate the Kerberos token is configured on the mechanism. Each domain has the following options:

Option	Description	Example
Enterprise	The fully qualified domain name of the domain	Enterprise.domain.com
KDC Host	The host of the AD domain controller	Ad.enterprise.domain.com
SPN	Service Principal Name – the samAcountName of a user that has been setup as a SPN.	To create an SPN: Create a service account in the domain Use the setspn tool to create an spn on the user with the host name of the Unison server
SPN Password	The password for the SPN

Chain

There are no authentication chain configuration options.

SSL Certificate Authentication

This mechanism supports authentication using SSL certificates. If the certificate can be associated with a user in the directory it will be, otherwise a user object is created. Note that in order for sslCert mechanisms to work certificate authentication must either be optional or required on the IdP.

Mechanism

Certificate Revocation Lists are configured on the mechanism. There are three types of CRLs: file based, LDAP and OCSP.

Option	Description	Example
Custom Extracts	List of classes that implements com.tremolosecurity.proxy.auth.CertificateExtractSubjectAttribute to get custom subject attributes from a certificate
Name	A descriptive name for the CRL	MyCRL
Type	The type of CRL
Path	The path to the CRL	For File based, relative to the TREMOLO_CRL_PATH environment variable For LDAP, an LDAP url for the cRLDistributionPoint object For OCSP, the host and port (host:port) of the OCSP server

Chain

When authenticating a user using certificates the chain configuration specifies how to identify a user and link them to a user in the directory. If a user can’t be linked in the directory then a user object is created based on the components of the DN.

When a certificate has subject alternative names they are added as potential components or attributes. These attribute names are:

otherName
email
dNSName
x400Address
directoryName
ediPartyName
uniformResourceIdentifier
iPAddress
registeredID

Any of these attributes are available to the matching filter for directory lookups or in the DN of an unmatched entry.

Option	Description	Example
UID Attribute	Either an attribute name OR an ldap filter mapping the certificate dn components. If this is an ldap filter, dn components are identified by ${component}	Attribute name : uid Filter : (&(uid=${CN})(ou=${OU}))
Is Filter	If the UID Attribute is a filter or just an attribute name
RDN Attribute	A list of attributes in the certificate subject, or subject alternative names, that will be the RDN of an unmatched entry.	CN
Default Object Class	The object class to use for objects created because the user doesn’t exist in the directory
DN for Unmatched Users	The ou component of the DN to use for users not matched. For instance if SSL is specified the user’s dn would be uid=user,ou=SSL,o=Tremolo	SSL
Allowed Issuers	List of DN’s of trusted certificates that the chain will accept

Username Only Login

An HTML login form that ONLY collects a username. This mechanism is convinient when using a custom authentication scheme or authentication system that doesn’t have a password (like SMS). All login forms must be stored in the apps/tremolo-admin/auth/forms directory. Forms can be static HTML or JSP pages. See apps/tremolo-admin/auth/forms/userOnlyLogin.jsp.

Mechanism

No configuration Parameters

Chain

Option	Description	Example
Username JSP	The URI for the jsp page used to log the user in	/auth/forms/userOnlyLogin.jsp
Username JSP	The URI for the jsp page used when a user can’t be found	/auth/forms/noUser.jsp
User Attribute Name/LDAP Filter	Either an attribute name OR an ldap filter mapping the form parameters. If this is an ldap filter, form parameters are identified by ${parameter}	Attribute name : uid Filter : (&(uid=${username})(l=${locationName}))
Search Using LDAP Filter	If true, the user is determined based on an LDAP filter rather than a simple user lookup

Banner Acknowledgement

The Banner Acknowledge mechanism provides a way to make a user acknowledge a set of policies prior to logging in. Adding this mechanism to a chain to record the acknowledgement in the authorization logs. The stock acknowledgement form is in /auth/forms/acknowledge.jsp.

Mechanism

No configuration Parameters

Chain

Option	Description	Example
Banner JSP	The URI for the jsp page to host the banner and request acknowledgement	/auth/forms/acknowledge.jsp
Banner	The text of the banner, may be HTML	I acknowledge that I am accessing a secured system and will not do anything I know I shouldn’t.

SMS Token Authentication

This mechanism allows for single use password to be used and dent over SMS to a user’s mobile phone via Twilio. Note, a Twilio account is required to use this mechanism.

Mechanism

There are no mechanism level configurations

Chain

When using this mechanism in a chain, it MUST come after a mechanism that collects the user’s login such as the username only or login form.

Option	Description	Example
Account SID	Twilio Account SID
Authentication Token	Twilio Account token
SMS Source Phone Number	Twilio Source Phone Number	1234567890
User Attribute That Stores User’s Phone Number	The attribute that stores the user’s phone number	mobile
Key Collection Form	URI for the form to collect the login key	/auth/forms/smsKey.jsp
Message (for the OTP)	The message to be sent to the user. “${key}” is used to represent the single use password.	Please login with ${key}
Key Size	The length of the single use password	10
Use Upper Case Letters	Checked if the single use password will have upper case letters	checked
Use Lower Case Letters	Checked if the single use password will have lower case letters	checked
Use Numbers	Checked if the single use password will have numbers	checked

Secret Question Authentication

This mechanism allows for secret or “golden” to be used as a password. The answers are stored in JSON as an attribute on the user’s object and are hashed. All questions and answers are encrypted.

Mechanism

Questions users may choose from are configured on the mechanism.

Chain

When using this mechanism in a chain, it MUST come after a mechanism that collects the user’s login such as the username only or login form.

Option	Description	Example
Login JSP	The URI of the secret question answer form	/auth/defaultForms/secretQuestions.jsp
LDAP Attribute	The attribute that stores the base64 encoded json	jpegPhoto
Hash Algorithm	One way hash to use	SHA-512
Salt	Used to randomize the hash	sdfgsFGSDFGdsfgsdfgSDFGSDfgrterwt

The com.tremolosecurity.proxy.auth.secret.CreateSecretQuestionsTask custom provisioning task should be used to create the secret questions on a user’s object. It has the following initialization parameters:

Option	Description	Example
numQuestions	How many questions must the user have?	3
questionNamePrefix	What is the prefix for attributes representing questions?	If the attributes are questionName1, questionName2, etc this should be “questionName”
questionValuePrefix	What is the prefix for attributes representing question’s answers?	If the attributes are questionVal1, questionVal2, etc this should be “questionVal”
chainName	The name of the authentication chain that secret questions are configured on	Portal Login

Login Service

The Login Service mechanism provides a way to give users a choice in how they login. This is useful in situations where the user could have multiple tokens and different levels of authentication. For instance, in a scenario where a user might be able to use 2-factor authentication when they have a token or a single factor when they don’t.

The way the login service works is it redirects the user to another Application URL for authentication. Once the chain for that application URL is completed the user is re-directed back to the original request (with post preservation). This provides the advantage of providing the authentication level of the desired chain. Each application URL should be configured with the com.tremolosecurity.prelude.filters.CompleteLogin filter. This will complete the login process.

Note	If only one option is configured in the service it will NOT prompt the user to choose.

Mechanism

There are no mechanism level options.

Chain

This mechanism should be the ONLY mechanism on a chain. In addition, the chain should be set at the lowest level of the other authentication chains involved. For instance if a chain on /login/ssl is set at 40 and another chain on /login/form is set at 20 then this chain should be 20.

Option	Description	Example
Login JSP	The URI of the login method select page	/auth/forms/chooseLogin.jsp
"Remember Decision" Cookie Name	The name of the cookie to store the user’s decision to keep the user’s decision to save the choice.	LoginChoice
"Remember Decision" Cookie Days Valid	The number of days the cookie that determines if the user wants to remember their login choice will be valid.	90

For each login choice, the steps are

Create an authentication chain
Create an Application URL
Associate the URL with the chain
On the Application URL, add the com.tremolosecurity.prelude.filters.CompleteLogin filter
Add the URI for this URL to the chain configuration for the login service:

Option	Description	Example
Label	Descriptive name for the login choice	PIV Authentication
URI	What is the URI for the choice	/login/piv

The com.tremolosecurity.prelude.filters.CompleteLogin filter has no configuration options.

OAuth2 Bearer - Last Mile

This mechanism allows for the use of a Unison Last Mile token to be used as a bearer token for OAuth2. The token must have one attribute named dn that maps to the user’s DN in Unison’s virtual directory.

Mechanism

There are no mechanism level configuration options.

Chain

This chain adheres to the OAuth2 Bearer Token standard. The Realm Name and encryption key are required. The scope is optional. Note that the keys listed are Last Mile encryption keys. One must be configured on the "Last Mile" keys list in the "CERTS" section of the admin interface.

Option	Description	Example
Realm Name	The name of the realm to respond with to failed authentication attempts	MyRealm
Scope	An optional attribute that provides additional context to the Realm Name	urn:myscope:myval
Encryption Key	A key from the Last Mile key list used to encrypt and decrypt the last mile token	mykey
Lookup User by Attribute?	Determines if the user is found based on a user attribute or the user’s DN	Checked
Lookup Attribute Name	If looking up by attribute, which attribute to search?	uid
Use URI to Verify LastMile?	If checked, Unison will look at the URI instead of the scope to verify the LastMile	Checked

Just-In-Time Provisioning

This mechanism executes a workflow on the currently logged in user.

Mechanism

There are no mechanism level configuration options.

Chain

This mechanism should only be configured AFTER the chain has established a user

Option	Description	Example
User Name Attribute	The name of the attribute used to identify the user on the user’s object.	uid
Workflow Name	The workflow to execute	MyWorkflow

Persistent Cookie

The persistent cookie mechanism is used in situations where a heavy gui client (such as Office or Windows Explorer) uses http calls to do work but is unable to handle redirects or form based authentication. For instance when integrating with a webdav system that is protected by Unison. Using this mechanism, a user can be authenticated in a web browser but use Explorer or Office using a persistent cookie. This cookie is encrypted and has a certain lifespan beyond the life of the user’s Unison session.

To enhance security this mechanism uses three levels of security:

Layer	Description
AES-256 Encryption	The cookie is encrypted using industry standard AES with 256 bit keys
Client IP Address	The user’s IP address is stored in the cookie, if the IP of the source of a request doesn’t match this value the cookie is rejected
Optional - SSL Session ID	The session id for the current SSL session can be stored as an extra layer of validation

When using this mechanism, the com.tremolosecurity.proxy.auth.persistentCookie.PersistentCookieResult custom result must be a cookie result on a Result Group that is on the Authentication Success result of the application configured with this mechanism.

Finally, when using with internet explorer the site that will generate and use this cookie MUST be "Trusted".

Mechanism

There are no configuration options on the mechanism.

Chain

When using this mechanism in a chain it MUST be used with some other mechanism (ie form or saml2), must be configured BEFORE any other mechanisms and all mechanisms MUST be marked as "sufficient".

Option	Description	Example
Cookie Name	The name of the cookie to generate. Scoping information is taken from the application’s cookie configuration.	loginCookie
Include SSL Session ID?	If checked, the user’s ssl session id is included in the validation process.	checked
Time to Live (milliseconds)	The number of milliseconds before this cookie needs to be re-generated. Defaults to 4 hours.	14400000
Encryption Key Alias	The name of the Last Mile Key from the Certificate Management screen to use to encrypt the cookie

Time Based One Time Password

This mechanism provides a one-time-password using the OATH time based protocol (sometimes referred to as Google Authenticator). This mechanism needs to be paired with a workflow that contains the com.tremolosecurity.provisioning.customTasks.CreateOTPKey custom task for setting the user’s encrypted key.

Mechanism

There are no mechanism level configuration options.

Chain

This mechanism should only be configured AFTER the chain has established a user.

Option	Description	Example
Form URI	The path to the form for entering the one-time-password	/auth/forms/otp.jsp
Encryption Key Name	The last mile key used to encrypt the user’s token	MyWorkflow
Full Encryption Key Name	The full name to be used in the `encryptionKey` property of the `com.tremolosecurity.provisioning.customTasks.CreateOTPKey` provisioning task	Based on the Encryption Key Name
Base64 Encoded Encryption Key	The base64 value of the key used for encrypting the user’s token, useful for applications that will display the token or a QR Code for importing the token into a mobile device
Directory Attribute Name	The name of the attribute to retreive the user’s token from, should be the same as the `attributeName` property of the `com.tremolosecurity.provisioning.customTasks.CreateOTPKey` custom task	l
Valid 30 Second Windows	Number of valid 30 second windows that a token should remain usable for cases where clocks aren’t exactly in-sync or to forgive codes entered over a windows switch	3

Password Self Reset

The PasswordReset mechanism is meant to provide a short lived token that is sent over email. The mechanism was designed to work with a password reset application, like ScaleJS Password. This mechanism requires a database. No schema needs to be loaded into the database since Unison will create the schema on startup if the table doesn’t exist.

Mechanism

Table 1. General Config
Option	Description	Example
Enabled	Check to enable this mechanism	Checked
User ID Attribute Name	The name of the attribute to look users up by, defaults to "mail"	mail

Table 2. Database Config
Option	Description	Example
Driver	Database driver	com.mysql.jdbc.Driver
Dialect	The HibernateSQL dialect	org.hibernate.dialect.MySQL5Dialect
Hibernate Mapping File	Optional - The mapping file (.hbx.xml) to use if the default mapping doesn’t work, must be loaded like a jar file	oracle12c.hbm.xml
Let Hibernate Create Schema	If checked, create tables. After initial configuration, you may want to disable this depending on the dialect.	Checked
URL	JDBC URL	jdbc:mysql://dbs.tremolo.lan/myvddata
User Name	DB User	user
Password	DB Password
Verify
Maximum Connections	Maximum number of connections	10
Maximum Idle Connections	Maximum number of connections not actively working	10
Password Reset Form URI	The URI to redirect users to after being authenticated if the user’s session is over	/echo/echo?roles=admin&myparam=value
Number of Minutes Token is Valid	The number of minutes a key is valid	20
Validation Query	Validation query to make sure the connection is still available	SELECT 1

Table 3. Email Config
Option	Description	Example
Host	SMTP Host	smtp.gmail.com
Port	SMTP port	587
User	SMTP user	user@gmail.com
Password	SMTP Password
Verify
From	The email address for the "From"	user@gmail.com
Subject	Email with key subject line	Password Reset
Message Template
Enable TLS	Set to true if using TLS	Checked
SOCKS5 Host	Host for SOCKS5 proxy
SOCKS5 Port	Port for SCOKS5 proxy
EHLO Localhost	How the Unison identifies itsself to the SMTP server

Chain

Option	Description	Example
Email Collection Redirect URI	The page to collect the user’s email address	/auth/forms/pwdResetEmail.jsp
Splash Page Redirect URI	The splash screen telling the user a reset message has been sent	/auth/forms/pwdResetSplash.jsp
No User Splash Page	Page to show the user when an email address can’t be found	/auth/forms/pwdResetNoUser.jsp
Maximum Times URL may be used	Maximum number of times a request can be made with a url	1

Log UserAgent

This mechanism will log the user’s browser (UserAgent header).

Mechanism

There are no mechanism level configuration options.

Chain

There are no mechanism level configuration options.

Mapping

This mechanism will perform a simple mapping of the user’s authenticated object. Its useful when using with SAML/OIDC before calling Just-In-Time provisioning. This way the provisioning engine can properly log all the attributes.

Mechanism

There are no mechanism level configuration options.

Chain

Configure this chain AFTER validating the user’s identity and BEFORE calling the JIT mechanism

Option	Description	Example
New Name	The new name of the attribute	givenName
Current Name	The current name of the attribute	https://schames.xml.com/firstName

OpenID Connect

This authentication mechanism is designed to support an OpenID Connect Provider (OP) such as Google, LinkedIn and KeyCloack (as with others). This implementation does not implement the full standard, only enough to allow authentication against an OP.

Mechanism

There are no mechanism level configuration options.

Chain

Option	Description	Example
Bearer Token Name	Name of the request object the bearer token should be stored in	kcBearerToken
Client ID	The client_id supplied by the OP	unison
Secret ID	The client_secret supplied by the OP	XXXXX
Response Type	What to request from the OP	code
Authentication Request URL	The authentication request url of the OP	http://keycloak.tremolo.lan:8080/auth/realms/unison/protocol/openid-connect/auth
Load Token URL	The URL to load the token from	http://keycloak.tremolo.lan:8080/auth/realms/unison/protocol/openid-connect/token
Scope	Claims to request from the OP	openid name offline
Link User to Directory	If true, the mechanism will attempt to find the user inside of OpenUnison’s internal virtual directory	true
Do Not Match OU Name	If a user isn’t matched in the virtual directory, ou to be assigned to	keycloak
User Lookup Filter
Default Object Class	If the user’s object isn’t matched in the virtual directory, the objectClass to assign	inetOrgPerson
User Attribute Name	The name of the attribute in the id_token that identifies the user	name
Optional Domain Limit	Optional - If you want to limit which user domains to authenticate by the OP, specify that domain here
Pull Claims from Access Token	If checked, the id_token is pulled from the token response	Checked
Token Attribute Name	Attribute in token response that contains the id_token	id_token
Id Token Lookup URL	If looking up the id_token, the url to use

GitHub

Provides authentication using GitHub. Prior to setup create a new OAuth2 Application in GitHub. This mechanism should be paired with the AuthorizationAuthMech mechanism to limit the teams and organizations that can authenticate the user. GitHub provides no way to limit who can authenticate to an OAuth2 Application. The user’s organizations are stored in the attribute githubOrgs and all teams are stored in the attribute githubTeams in the form org/team.

Mechanism

There are no mechanism level configuration options.

Chain

Option	Description	Example
Bearer Token Name	Name of the request object the bearer token should be stored in	kcBearerToken
Client ID	The client_id supplied by the OP	unison
Secret ID	The client_secret supplied by the OP	XXXXX
Scope	Claims to request from the OP	openid name offline
Link User to Directory	If true, the mechanism will attempt to find the user inside of OpenUnison’s internal virtual directory	true
Do Not Match OU Name	If a user isn’t matched in the virtual directory, ou to be assigned to	keycloak
User Lookup Filter
Default Object Class	If the user’s object isn’t matched in the virtual directory, the objectClass to assign	inetOrgPerson
User Attribute Name	The name of the attribute in the id_token that identifies the user	name

Authorization Rules

This mechanism provides an authorization check prior to completing a chain. This can be important when you want to limit who can authenticate when integrating an external provider without that remove provider providing a way to limit which users can be authenticated.

Mechanism

There are no mechanism level configuration options.

Chain

List of authorization rules. Any of the rules need to be satisfied to pass authorization.

Option	Description	Example
Constraint Scope	Type of rule	Group
Constraint	How the rule will be evaluated	(objectClass=*)

Generate OpenID Connect Session Token

This mechanism will generate an OpenID Connect session on behalf of an authenticated user. This is useful when using Unison with Kubernetes to authenticate users or proxy authentication with other identity providers and using Unison’s session specific client secrets with kubectl. Use this mechanism by adding it to the end of the chain to generate the proper session.

Mechanism

There are no mechanism level configuration options.

Chain

Option	Description	Example
Identity Provider	The name of the OpenID Connect identity provider to use	oidc
Trust	The name of the trust to generate a session for	kubernetes

U2F Authentication

This mechanism provides Universal Second Factor (U2F - https://fidoalliance.org/specifications/overview/) authentication. It MUST be on a chain AFTER the user is identified by another means (such as via a username and password, federation, etc). It is designed to work with the U2F Registration filter to set the user’s keys.

Mechanism

There are no mechanism level configuration options.

Chain

Option	Description	Example
Key Attribute	The name of the attribute to retrieve the registered keys from	carLicense
Encryption Key Name	Last Mile encryption key for encrypting/decrypting the attribute that stores the user’s tokens	someKey
Workflow	The name of the workflow to run to update the keys attribute	someWorkflow
Form URI	The URI of the JSP page that will challenge the U2F device during authentication	/auth/forms/u2fAuth.jsp
Username Attribute	The attribute to identify the user during the challenge and in the workflow	uid

Filters

Unison provides the capability to make changes to each request. For an identity provider this typically means adding additional attributes to an assertion. For a reverse proxy, this generally means adding headers or executing workflows based on the user’s choices. The below filters come standard in Unison.

Create an attribute from a group membership

This filter allows for an attribute to be added to an assertion if the user is a member of a particular group in your directory. This could be useful when providing service providers entitlement information. This filter can be added multiple times and if the user is a member of the specified group AND the attribute already exists the specified value is added to the attribute, it does not replace it.

Option	Description	Example
Group DN	The full LDAP DN of the group being checked. This DN must be the mapped DN from inside of Unison. The “…” button next to this option may be used to search for the group based on it’s CN.	Cn=mygroup,cn=Users,ou=MyEnterprise,O=Tremolo
Attribute Name	The name of the attribute to create if the user is a member of this group	Role
Attribute Value	The value to be added or set if the user is a member of the specified group	Users

Create an attribute from a base DN

This filter allows for an attribute to be added to an assertion if the user’s DN in the virtual directory is a child of the specified DN. This could be useful when providing service providers entitlement information. This filter can be added multiple times and if the user is a member of the specified DN AND the attribute already exists the specified value is added to the attribute, it does not replace it.

Option	Description	Example
Base DN	The full LDAP DN of the base being checked. This DN must be the mapped DN from inside of Unison. The “…” button next to this option may be used to find it.	cn=Users,ou=MyEnterprise,O=Tremolo
Attribute Name	The name of the attribute to create if the user is a member of this group	Role
Attribute Value	The value to be added or set if the user is a member of the specified group	Users

Login Test

This filter will echo the attributes of the currently logged in user. It’s a convenient way to test the login process without having to have an application to proxy or an identity provider configured. Configure this filter on a URL and that URL will use this filter to provide content back to the web browser. No filters configured after this filter are executed.

Option	Description	Example
JSP URI	The path of the JSP page that will show the logged in user’s information	/auth/forms/loginTest.jsp
Logout URI	The path of the logout URI	/logout

Create XForward Headers

The X-Forward headers (X-Forwarded-For, X-Forwarded-Host and X-Forwarded-Proto), are a defacto standard for supplying down-stream servers with information as a reverse proxy would see it. This filter will create these attributes for use as headers.

Option	Description	Example
Create Standard Headers	Determine if plean HTTP Headers or Secure Headers should be used. If checked, standard headers are created, if not checked then attributes are created with the same names that can be added as Secure Headers to the LastMile filter.	true

Create AWS Role Attribute

This filter is designed to be added to an identity provider for the AWS console to create an attribute that is acceptable to AWS out of human readable role names.

Option	Description	Example
Source Attribute Name	The name of an attribute on the user object that contains all of the names of roles to be included in the assertion. NOTE: each role should exist in IAM or the authentication will fail.	roleNames
AWS Account Number	The AWS account number that should be included in the role mapping.	1234567
Identity Provider Name	The name of the identity provider in your AWS IAM configuration to bind to.	MyIdp

Stop Processing

The “Stop Processing” filter will stop all processing, not executing any filters configured after it or sending a request to the proxied server. This filter has no configuration options

Execute Workflow

This insert will execute a workflow using the user loaded by the authentication process.

Option	Description	Example
Workflow	The name of the workflow to execute	Create Shadow Users
Username Attribute	The name of the attribute on the user object used to identify the user	Uid

User to JSON

This filter will create a JSON object based on the user’s attributes. The class com.tremolosecurity.proxy.auth.AuthInfo is serialized into JSON into the attribute UserJSON. This attribute can then be used as a header in a result or a LastMile attribute.

Option	Description	Example
Proxy Request	If set to “true” the request is continued to be proxied. If set to false, the request completes	True/False

Check Authorizations

If an application is configured to not use a session, the user’s context may be set in a filter but the authorization process will not be executed. This filter will execute authorization rules and execute result groups in this scenario. There are no configuration options for this filter, as it uses the rules configured on the application.

Remote Basic Authentication

This filter will authenticate users by executing a basic authentication request against a remote server using the Authorization header inbound from the browser. The filter will then set the user’s context. Its designed to work with an application’s session disabled.

Option	Description	Example
Realm Name	The name of the realm on the remote web server the authentication is against	My Realm
URL	The url to use to test the authentication	https://www.mydomain.com/auth

Last Mile Security

The last mile security filter generates the token utilized to validate the request by the Last Mile system deployed on the application. This filter can be configured to add attributes, roles and other information to the last mile token. It also supplies the configuration needed for the application’s last mile configuration.

Option	Description	Example
Encryption Key	The key used to encrypt the last mile header	Header-encryption-key
Specify New Encryption Key	If the key doesn’t exist, specifying this field will create a new key	Header-encryption-key
Encryption Key Password	The password used to unlock the key by the last mile system
Time Scew	The number of milliseconds that the last mile token is valid	1000
Header Name	The name of the header	tremooHeader
Optional Header Prefix	Static text to put in front of the token, ie for OAuth2 bearer tokens	Bearer
Attribute Mapping	Specify mappings from user attributes to headers, also choose which attribute is used to identify the user and which to identify roles (optional)
Create Headers	Specifies if the last mile system should create headers in the application	True/False
Keystore Path	The relative path to the keystore	WEB-INF/lastmile.jks
Ignore URI	A uri that is ignored by the last mile system, often used to unprotect web services	/path/to/ws
Filter Type	The type of last mile system to be used

Check Shadow Account

When integrating with an AD environment that is used for both shadow accounts and real accounts this filter is used to transition from real account in an external forest to a shadow account.

Option	Description	Example
Local UPN Suffix	The UPN suffix for AD forest storing shadow accounts	shadows.ad.local
New UPN Source Attribute	The attribute that’s used for the source of the shadow account’s UPN	Mail
Flag Attribute Name	Attribute to store a flag value if the account is to be a shadow account	Description
Flag Attribute Value	Flag value if the user will become a shadow account	shadow

Basic Authentication

This filter is used in conjunction with an application with a disabled session. It will perform a basic authentication against the internal virtual directory.

Option	Description	Example
Realm Name	The name of the realm to be presented to the browser	My Realm
Username Attribute	The name of the attribute to use to lookup the user	Uid

Anonymous Authentication

This filter is used in conjunction with an application with a disabled session. It will create an AuthInfo object based on an anonymous user. There are no configuration options.

Hide Cookies from Client

This filter will remove all cookies set by the proxied applications prior to being sent to the client. The cookies are stored in an internal cookie jar in the user’s session. There are no configuration options.

Decode Form Parameter Name

This filter will decode any form parameters that are already URLEncoded. This is useful for applications like Drupal that relies on form parameters that were URL encoded.

Last Mile JSON IdP

Used in conjunction with the OAuth2 Last Mile Bearer Token authentication scheme, this filter will create an HTML page with an OAuth 2 access token inside of a div called "json".

Option	Description	Example
Encryption Alias	Last Mile encryption key	oauth2-key
Seconds Valid	The number of seconds the returned token is valid	6000
Scew Seconds	The number of seconds to adjust for if clocks are not synced	300

Pre-Authentication

Some applications do not work well with a reverse proxy and require an explicit "login" step. In these scenarios the Pre-Authentication filter can be used to create a session prior to the first time a user accesses the website. This filter does a Last Mile login to the url and can optionaly generate a SAML2 assertion and perform an IdP initiated SSO. Once the login is complete the cookies from the request are added to the user’s cookie jar.

Option	Description	Example
Pre-Auth URL	The fully qualified domain name (FQDN) and uri of the URL in Unison configured with a LastMile filter configured.	https://mysite.company.com/myapp/login
Post SAML?	Determines if a SAML assertion should be generated and posted to the Pre-Auth URL. If checked an Identity Provider MUST be created to supply the configuration information to generate the assertion.	true
IdP Name	The name of the identity provider that has the configuration information for generating the assertion	MyIdP
Issuer Host	The host name that should be in the issuer	idp.mycompany.com
Issuer Port	If the issuer is on a non-standard port, it can be specified here. This field is optional	8443
Issuer SSL	If the issuer should be https (checked) or http (not checked)	checked

Create attribute from group memberships

This filter will create an attribute with the names of groups the user is a member of. An optional regular expression can be used to specify only a certain number of groups.

Option	Description	Example
Base	The base in the virtual directory to begin searching for groups.	o=Tremolo
Attribute Name	Name of the attribute to create	roles
Optional Pattern	A regular expression to filter out group memberships	groups-(.*)
Group Number from Pattern	If a pattern is specified, the group from that pattern to add to the attribute	1

Cookie Filter

This filter will stop all cookies, except those configured, from being sent to downstream applications. This can be used to stop third party cookies, attempts to spoof or cookie collisions.

Option	Description	Example
Support Cookie Name Regular Expressions	If checked, the values to filter are treated as Java regular expressions. (http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html)	Unchecked
Cookies to Filter	List of cookie names (or regular expressions) to filter	SomeCookieName

Header Filter

Removes an inbonud header from a request. Header names are NOT case sensistive

Option	Description	Example
Headers to Filter	List of header names to filter	Accept-Encoding

Set No Cache Headers

This filter will set response headers that will tell browsers not to cache the content.

Add HTTPS To Redirects

This filter will replace http:// with https:// in the Location response header. Useful when overiding the Host header is disabled but the proxy transitions from https to http.

Check Session

This filter will check to see if the user’s session is active, and if so how much longer the user’s session is. This filter should be configured on its own application, seperate from the application being tested and with its own session cookie. This way the user’s session is not reloaded when checked.

Option	Description	Example
Application	The name of the application who’s session cookie data to check	ScaleJS

Remove Prefix

The Remove Prefix filter will remove the beginning of the URI and put it into an attribute that can be included in the Proxy To Application.

Option	Description	Example
Prefix	The part of the URI to trim off	/scale
Attribute Name	The attribute to set with the new URI	trimmedURI

Retrieve OpenID Connect Id Token

Kubernetes does not retrieve your id_token using the authorization flow, it assumes that the bearer token provided is an id_token with a short expiration date. In this filter provides a simple service that will generate the id_token for an authenticated session based on the session’s refresh_token. Configure this filter on an anonymous URL and pass a single parameter, refresh_token, to get a proper id_token:

$ kubectl --token=$(curl https://openunison.server/service/idtoken?refresh_token=....) get nodes

Note	This will not generate a new token once the current one has expired. That requires going to ScaleJS and refreshing the token screen to get a new id_token.

Option	Description	Example
Identity Provider	The name of the identity provider to pull the id_token from	oidc
Trust	The name of the trust to pull the id_token from	kubernetes

Call Workflow

Allows for a remote Unison to call a workflow by calling a PUT of a workflow request. Recommended to use with an OAuth2 authentication chain.

Option	Description	Example
Allowed Workflows	Determines which workflows can be called	someWorkflow

U2F Registration

This filter provides services for registering U2F keys (https://fidoalliance.org/specifications/overview/). Its designed to work with the U2f Authentication mechanism.

Option	Description	Example
Key Attribute	The name of the attribute to retrieve the registered keys from	carLicense
Encryption Key Name	Last Mile encryption key for encrypting/decrypting the attribute that stores the user’s tokens	someKey
Workflow	The name of the workflow to run to update the keys attribute	someWorkflow
Challenge URI	The URI of the JSP page that will challenge the U2F device and provide the registration response	/auth/forms/u2fRegistration.jsp
Username Attribute	The attribute to identify the user during the challenge and in the workflow	uid
Registration Completed URI	The URI of the jsp page to send the user to once the regitration process is completed	/auth/forms/u2fRegistrationComplete.jsp
Require Trusted Attestation	If you only want to allow certain devices or manufacturers	checked
Trusted Attestation Certificates	If requiring attestation of the device, list of certificates used to check the attestation	yubico

LDAP RESTful API

The LDAP RESTful API filter will provide LDAP like functionality via a RESTful JSON interface. The filter provides search and bind capabilities only. Unlike LDAP, searches and binds are NOT tied together. This is a convenience for accessing Unison’s internal virtual directory without using the LDAP protocol. It is not a replacement for LDAP.

Swagger Definition

swagger: '2.0'
info:
  version: "1.0.15"
  title: Unison LDAP RESTful API

definitions:
  Attributes:
    type: object
    additionalProperties:
      type: array
      items:
        type: string
    description: Map of attribute name --> multiple values

  LdapJsonBindRequest:
    type: object
    properties:
      password:
        type: string
        description: Secret for authentication
    description: in java package com.tremolosecurity.ldapJson

  LdapJsonError:
    type: object
    description: in java package com.tremolosecurity.ldapJson
    properties:
      responseCode:
        type: integer
        description: LDAP Response code
      errorMessage:
        type: string
        description: response message

  LdapJsonEntry:
    type: object
    description: in java package com.tremolosecurity.ldapJson
    properties:
      dn:
        type: string
        description: The distinguished name of the entry
      attrs:
        $ref: '#/definitions/Attributes'

paths:
  /{base_dn}/{search_scope}:
    get:
      description: performs an LDAP Search
      parameters:
        -
          name: base_dn
          in: path
          description: Search base
          required: true
          type: string
        -
          name: search_scope
          in: path
          description: One of base, sub, one
          required: true
          type: string
        -
          name: filter
          in: query
          description: LDAP Filter
          required: true
          type: string
        -
          name: attributes
          in: query
          description: each value is an attribute to be returned
          type: string
          minimum: 0
      responses:
        200:
          description: list of entries
          schema:
            type: array
            items:
              $ref: '#/definitions/LdapJsonEntry'
        500:
          description: error
          schema:
            $ref: '#/definitions/LdapJsonError'

  /{user_dn}:
    post:
      description: performs an LDAP Bind to verify the user's credentials
      parameters:
        -
          name: user_dn
          in: path
          description: The distinguished name of the user to check
          type: string
          required: true
        -
          name: body
          in: body
          schema:
            $ref: '#/definitions/LdapJsonBindRequest'
          description: Bind request
      responses:
        200:
          description: valid credentials
          schema:
            $ref: '#/definitions/LdapJsonError'
        500:
          description: error
          schema:
            $ref: '#/definitions/LdapJsonError'

JMS Metrics Pull Configuration

This filter is designed to open access to Prometheus metrics that are not directly acessible from Prometheus. Instead of a direct connection to metrics, this filter will proxy the request to a remove OpenUnison via a common message queue and wait for a response via a seperate queue. This filter should be paired with an OpenUnison instance that has the com.tremolosecurity.prometheus.aggregate.PullListener deployed.

Option	Description	Example
Request Queue	Request queue	request-queue.fifo
Response Queue	Response queue	response-queue.fifo
Instance	Instance	some-instance
Job	Job description	Test job
Additional Metrics Class	Implementation of com.tremolosecurity.prometheus.sdk.AdditionalMetrics for additional metrics	com.test.metrics.Metrics
Additional Metrics Initialization Parameters	List of additional prameters for the additional metrics implementation

Identity Provider Configuration

Unison supports multiple identity provider implementations. Each identity provider has its own configuration. This section details how to configure an individual type of identity provider. Each identity provider type has a global configuration, which is on the “URL” screen, and a trust configuration which tells Unison how to provide information for a particular partner.

SAML2

SAML2 is a standard form of federation that is very popular in enterprise environments. Unison can act as a SAML2 identity provider providing SAML2 assertions, attributes and strong security. The SAML2 identity provider supports signing and encrypting of assertions.

Access URLs

There are three primary URLs for accessing the identity provider:

URL Type	Function	Format	Example
HTTP-POST Authentication Requests	Accepts authentication requests as an HTTP Post	https://host:port/auth/idp/IDPNAME/httpPost Where IDPNAME is the name of the identity provider under the APPS system	https://host:port/auth/idp/saml2/httpPost
HTTP-Redirect Authentication Requests	Accepts authentication requests as an HTTP Get	https://host:port/auth/idp/IDPNAME/httpRedirect Where IDPNAME is the name of the identity provider under the APPS system	https://host:port/auth/idp/saml2/httpRedirect
Identity provider initiated federation	Start a federation without an authentication request from the SP	https://host:port/auth/idp/IDPNAME/idpInit?sp=TRUST where IDPNAME is the name of the identity provider under the APPS system and TRUST is the name of the trust	https://host:port/auth/idp/saml2/idpInit?sp=https://saml2.salesforce.com

Global Configuration

The global configuration on the “URL” is for determining how to accept authentication requests.

Option	Description	Example
Signature Key	The key used for verifying signed authentication requests. The key should be listed under the “Signature and Encryption Keys” in Certs	Idp-cert-key
Encryption Key	The key used for encrypting authentication requests. The key should be listed under the “Signature and Encryption Keys” in Certs
Require Signed Authentication Requests	Must the identity provider require signed authentication requests? If not checked, signed authentication requests will still be accepted and verified.
Require Signed MetaData	Must the identity provider require signed metadata? If not checked, signed metadata will still be accepted and validated.
Post Response Template	A template that is used when sending the response via HTTP Post

Generating Metadata

SAML2 metadata can be generated from the global identity provider section. Metadata can be signed using the specified key.

Trust

A trust establishes a connection between the SAML2 IdP and a SAML2 SP. The trust configuration establishes this connection by specifying URLs, certificates and mappings from nameid and authentication types to attributes and authentication chains respectively. The name of the trust must match with the issuer in a saml response or assertion. The only profile supported by Unison is the HTTP-POST profile.

Option	Description	Example
HTTP Post Response URL	The URL used to post the response to. This is optional if included in the authentication request.	https://www.mysp.com/saml2/sp/post
SP Signature Key	The key used to sign the response or assertion
SP Encryption Key	The key used to encrypt assertions
Sign Assertions	Determine if the assertion should be signed. If encrypting assertions, its expected that the assertion will be signed.
Encrypt Assertions	Should the assertion be encrypted?
Sign Responses	Should the entire response (including the assertion)
Default NameID Format	If no nameid format is specified in the authentication request or in the idp initiated request this setting specifies which attribute to use to identify the user	urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
Default Authentication Context Class	If no authentication class context reference is specified in the authentication request or in the idp initiated request specifies how to authenticate the user	urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified

NameID to Attribute Mapping

Each accepted nameid format must be mapped to a user attribute. The attribute must be present in the “Mapping” section on the Identity Provider. The default nameid type defined above MUST be included.

SAML2 Authentication to Auth Chain Mapping

This section defines how Unison will authenticate users. Each authentication context class reference is mapped to a an authentication chain. The default context class ref defined above MUST be included in this mapping. Prior to configuring this mapping the authentication chain must be defined.

SAML2 SP MetaData

SAML2 metadata may be used to auto configure much of the trust. Copy and paste the metadata into this field. Once processed the trust will be renamed based on the entity id, nameid mappings will be created, certificates will be trusted and urls will be configured. If the metadata is signed, the certificate must be trusted in the Certs system.

Option	Description	Example
Import Meta Data	Check this box if you plan to upload metadata. Otherwise validation will fail. NOTE: uploading new metadata will overwrite the trust configuration.	Checked
Option 1 - Import from URL	If your service provider has published its SAML2 metadata, the url can be put into this option and will be loaded into Unison.	https://www.tremolosecurity.com/anon/www.tremolosecurity.com-saml2-metadata.xml
Option 2 - Upload	If you would like to upload a file containing the metadata choose this option	C:\Downloads\www.tremolosecurity.com-saml2-metadata.xml
Option 3 - Copy and Paste Meta Data	You may copy and paste the text of the metadata file into this option	meta data contents

OpenID Connect

The OpenIDConnect Identity Provider provides the features of OpenID Connect most often parts of the Authorization code flow used by applictions. This implementation is designed to be compatible with Google’s documentation for OpenID Connect integration. OpenUnison provides authentication, token validation and refresh. Additionally, the OpenID Connect discovery profile is supported. Once configured, the com.tremolosecurity.idp.providers.oidc.model.jobs.ClearSessions job should be configured in the scheduler to make sure that old sessions are properly cleared out.

Access URLs

URL Type	Function	Format	Example
OpenID Connect Discovery	List of all available URLs	https://host:port/auth/idp/IDPNAME/.well-known/openid-configuration Where IDPNAME is the name of the identity provider under the Applications system	https://host:port/auth/idp/oidc/.well-known/openid-configuration

Global Configuration

The global configuration on the “URL” is for determining how to secure keys and connect to the database to store user sessions. Tables are created on the first connection to the database.

Option	Description	Example
JWT Signing Key	The alias of the TLS key to use for signing JWTs	sig-key
Session Storage	How oidc sessions will be stored	Database, Kubernetes, None
For Database Sessions
Driver	Database driver	com.mysql.jdbc.Driver
Dialect	The HibernateSQL dialect	org.hibernate.dialect.MySQL5Dialect
Hibernate Mapping File	Optional - The mapping file (.hbx.xml) to use if the default mapping doesn’t work, must be loaded like a jar file	oracle12c.hbm.xml
Let Hibernate Create Schema	If checked, create tables. After initial configuration, you may want to disable this depending on the dialect.	Checked
URL	JDBC URL	jdbc:mysql://192.168.99.100:3306/unison?useSSL=true
User Name	DB User	root
Password	DB Password
Verify
Maximum Connections	Maximum number of connections	10
Maximum Idle Connections	Maximum number of connections not actively working	10
Validation Query	Validation query to make sure the connection is still available	SELECT 1
For Kubernetes Sessions
Kubernetes Target	OpenShift (Kubernetes) Provisioning Target	kubernetes
Namespace	The namespace to store/retrieve sessions from	unison

Trust

Each trust configures a client that can authenticate to this identity provider.

Option	Description	Example
Client ID	Used to identify the client, use this name when configuring filters that reference this trust	mod_oidc_test
Public Endpoint	If checked, a client secret isn’t used to authenticate requests	Client Secret
A secret shared by both Unison and the client	XXXXXXXXX	Redirect URL
The URL Unison will redirect users to after authentication	http://192.168.99.100/redirect_uri	Code Last Mile Key
LastMile key used to encrypt code and refresh tokens	tokens	Authentication Chain
The authentication chain to use for authentication	Default Login Form	Access Token Time to Live (millis)
Milliseconds an access token and id_token lives until it needs to be refreshed	60000	Access Token Skew (millis)
Milliseconds that a token can be off from the current time that will be accepted	120000	Code Token Skew (millis)
he number of milliseconds the code token is valid	60000	Validate redirect_uri
If checked (UNLESS IN A DEVELOPMENT ENVIRONMENT IT SHOULD ALWAYS BE CHECKED) the redirect_uri is checked against the one configured	checked	Sign User Info Endpoint

Custom Authorization Rules

This section details the pre-built Unison custom authorization rules. These rules can be used in your deployments without change. Consult the Unison SDK for instructions on how to create custom custom authorization rules.

All custom authorization rules have a common interface for specifying configuration options. Each rule can take any number of name/value pairs. A single configuration option can have multiple values by listing the name/value pair for each value.

Manager Authorization

Class Name - com.tremolosecurity.provisioning.az.ManagerAuthorization

This rule provides a mechanism for allowing a user’s supervisor or manager to approve a request. The approver is authorized based on the user’s data in Unison’s internal virtual directory.

Option	Description	Example
Number of Levels (Start with 1)	Use this to define who "distant" of a manager is authorized. For instance to allow the user’s manager’s manager to perform the authorization specify "2". This allows for escalations to be processed with multiple tiers of managers.	1
Manager Attribute Name	The name of the attribute on the user’s directory object that will tell Unison who their manager is.	manager
Is Manager Attribute a DN?	If checked, Unison will assume that the attribute defined in "Manager Attribute Name" is the distinguished name of the user’s manager. If not checked, then Unison will use a filter built from the "User Identifier Attribute" from the Approvals screen and the value of the "Manager Attribute Name"	Checked
Allow Lower Level Managers to Approve?	Used when the number of levels is greater then one, allowing all the managers between the user and the current step to approve. For instance of an approval is escalated to a user’s manager’s manager checking this option will allow both the user’s manager AND the user’s manager’s manager to approve.	Checked

Provisioning Targets

This section details the pre-built provisioning targets that are available for Unison. In addition to these targets, custom targets may be created. Consult the Unison SDK for instructions on how to create a custom target.

All targets have a common interface for specifying mappings from Unison’s current user object and how attributes will be pushed to the target. Only mapped attributes will be utilized by a provisioning target.

Source Type	Description	Source	Example
user	Map an attribute form the user’s directory object	Name of an attribute	givenName
static	A static value that doesn’t change	The static value	Myvalue
custom	A class that is used to determine the mapping	Class name, see the SDK for details on how to implement	com.mycompany.mapper.Mapper
composite	A composite of attributes and static values. Attributes are defined with ${attributename}. Only attributes that exist before the mappings are run are available	Static and attribute data	${givenName}.${sn}@mydomain.com

Note that if the source attribute is TREMOLO_USER_ID then the user object’s id is used. When TREMOLO_USER_ID is the target attribute it sets user object’s id.

@PRODUCT@ tests the target’s configuration whenever it is saved. If there is an error in testing the connection, it will be displayed.

LDAP Directory

This target provisions identities to a generic LDAPv3 directory.

Option	Description	Example
Name	A descriptive name for the target	LDAP
User Object Class	The object class for new user objects	inetOrgPerson
Host	Host for the ldap server	ldap.enterprise.com
Port	The port to connect to	636
Administrator DN	A DN for a user with administrator rights to create and update accounts	Cn=Directory Manager
Administrator Password	Credential passwords
New User DN Pattern	The DN pattern for new users with user attributes in ${}	uid=${uid},ou=users,dc=domain,dc=com
Search Base	The base that should be used for searching for users and groups	Dc=domain,dc=com
Use SSL	If set to true SSL is used for the connection	True/False
UserID Attribute	The name of the attribute used to identify the user	Uid
Maximum Connections	Maximum number of connections to the directory	10
Maximum Sessions per Connection	Maximum number of individual operations per connection	10
Manage Groups for External Users	If checked, this directory is able to store users that are NOT stored in the directory. For instance if linked to an Active Directory via the internal virtual directory. If a user is not found in the target, the virtual directory is searched from o=Tremolo using the user’s ID. ONLY group memberships will be provisionined and they’ll be provisioned using the DN from the virtual directory.	Checked

Note	To specify an alternate dnPattern in a workflows, specify it in the request object with the key `LDAPProvider.NEW_USER_DN` or `com.tremolosecurity.unison.provisioning.ldap.newUserDN`

Active Directory

This target provisions identities to a Microsoft Active Directory. Note that unlike the Active Directory directory type, the provisioning target does NOT automatically map to an inetOrgPerson object class.

Option	Description	Example
Name	A descriptive name for the target	MyDomain
Host	Host for the ldap server	ldap.enterprise.com
Port	The port to connect to	636
Administrator DN	A DN for a user with administrator rights to create and update accounts	Cn=Directory Manager
Administrator Password	Credential passwords
New User DN Pattern	The DN pattern for new users with user attributes in ${}	uid=${uid},ou=users,dc=domain,dc=com
Search Base	The base that should be used for searching for users and groups	Dc=domain,dc=com
Create Shadow Accounts	If set to true a shadow account is created. A shadow account is just like a regular account except the password is randomly generated.	True/False
Use SSL	If set to true SSL is used for the connection	True/False
UserID Attribute	The name of the attribute used to identify the user	Uid
Maximum Connections	Maximum number of connections to the directory	10
Maximum Sessions per Connection	Maximum number of individual operations per connection	10

Relational Database

This target can be used to create users and update their attributes in a relational database. The target can either use a generic model or a custom model can be updated by implementing a specific interface. For instructions on how to manage a custom database, see the Unison SDK. This target can also optionally create PBKDF2 passwords with a 64 byte salt.

Figure 1 – Group Management Mode: None

Figure 2 – Group Management Mode: Many to Many

Figure 3 - Group Management Mode: One to Many

Option	Description	Example
Name	A descriptive name for the target	MyDB
Driver	The class of the JDBC driver	com.vendor.jdbc.Driver
URL	The JDBC URL for accessing the database	jdbc:driver://host/db
Begin Escape Character (Optional)	An optional character used to escape field names in SQL	`
End Escape Character (Optional)	An optional character used to escape field names in SQL	`
User Name	The user for connecting to the database
Password	The password for the database
Maximum Connections	The maximum number of connections to the database	10
Validation Query	A query that will be used to test if a connection is active on checkout	SELECT 1
Idle Connection Test Period (Seconds)	Number of seconds unchecked out connections are tested	30
Unreturned Connection Timeout (Seconds)	Number of seconds a connection can checked out before the connection is closed and returned to the pool. 0 means it will not be forced.	0
Checkout Timeout (Milliseconds)	Number of milliseconds to wait for a connection to be available.	30000
Users Table	The name of the table that stores the user objects	Users
User SQL	If a custom group management is used this option is used to specify how users are looked up. Use %S to specify the fields being looked up, %I for the user’s numeric ID and %L for the user’s login	SELECT %S FROM users WHERE login=%L
User Table Primary Key Field	The name of the column in the user table that is the primary key	Id
User Table Login Name Field	The field that stores the user’s login id	login
Support Passwords	Check if you want to provision passwords to the database in PBKDF2 format with a 64 byte salt	Unchecked
Password Column	If Support Passwords is checked, the column to store the password in	password
Group Management Mode	Determines how to manage the relationship between users and groups:	None – No group information is stored ManyToMany – Assumes there is a table of users, table of groups and a table that links them OneToMany – Assumes there’s a table of users with a one-to-many relationship with a groups table Custom – Use a custom class to update user attributes and group memberships. See the SDK for implementation details
Group Table Name	The name of the table that stores group information	Groups
Group SQL	If a custom group management is used this option is used to specify how groups are looked up. Use %S to specify the fields being looked up, %I for the user’s numeric ID and %L for the user’s login	SELECT %S FROM wp_usermeta INNER JOIN users ON users.id=wp_usermeta.user_id AND wp_usermeta.meta_key=wp_capabilities where users.id=%I
Group Table Primary Key	The name of the primary key of the group table	Id
Group Table Name Field	The field start stores the name of the group	name
Group Link Table Name	The name of the table used to link users and groups	LinkTable
Group Link User Field	The name of the column in the link table that maps to the user’s primary key	User
Group Link Group Field	The name of the column in the link table that maps to the group’s primary key	Groups
Custom Provider	The class name for a custom provider. See the SDK for how to implement a custom provider

Amazon SimpleDB

If utilized as the basis for user data in the cloud this target can be used in a workflow to populate the database.

Option	Description	Example
Name	A descriptive name for the target	MyAmazonDB
User Domain	Domain for storing user information	Users
Group Domain	Domain for storing group information	Groups
Access Key	Access Key
Secret Key	Secret Key
User Identifier Attribute Name	The attribute that stores the userid	uid

Tremolo Unison

In addition to provisioning to specific targets, Unison can provision to other Unison clusters. This can be used to separate out functions, separating provisioning from access management. Note that all authentication is done via SSL. Before connecting to another Unison instance an SSL certificate must be generated and signed by the valid CA.

Option	Description	Example
Name	A descriptive name for the target	MyUnison
UID Attribute Name	The attribute name for the user identifier	Uid
URL Base	The url for the unison web service	https://www.tremolosecurity-test.com:9093
Create User Workflow Name	The name of the workflow used to create new users
Delete User Workflow Name	The name of the workflow to delete users
Set User Password Workflow Name	The name of the workflow to set a user’s password
Synchronize User Workflow Name	The name of the workflow to synchronize a user

SugarCRM

The SugarCRM target can be used to update contacts inside of SugarCRM. It does not, at present support the creating of users.

Option	Description	Example
Name	A descriptive name for the target	SugarCRM
URL	The SugarCRM web services URL	http://sugarcrm.domain.com/sugarcrm/service/v2/rest.php
Admin User	Administrative username
Admin Password	The user’s password

SharePoint Groups

This target allows for a user’s groups in SharePoint to be managed by Unison. For Just-In-Time provisioning it requres that:

The LastMile filter is configured on a URL with access to the usergroup.asmx web service
The internal host name (as it is visible to Unison) is configured as a host on this URL
That all users managed in sharepoint are already in Active Directory and have logged in once into SharePoint

If not being used for JIT provisioning, or when Last Mile is not yet available NTLM authentication can be used. This requires that identites be already in AD and synced into sharepoint.

Multi Site Integration

If a SharePoint site is made of multiple sites, but NOT subsites off the main site, then Unison must be configured to "know" about these sites. Each Site has its own roles and those roles can only be manipulated by accessing the webservices associated with each individual site.

Option	Description	Example
Name	A descriptive name for the target	SharePoint
Authentication to SharePoint Mode	Mechanism for authentication to SharePoint. For JIT provisioning you must use Unison Last Mile.	Unison Last Mile or NTLM
SharePoint Users and Groups Service URL	The URL, from Unison’s perspective, of the web services url	http://sharepoint-internal.domain.com/_vti_bin/usergroup.asmx
Administrator UPN	Full user principal name of an administrative user	administrator@domain.com (when using NTLM this should be in the form domain\user, ie DOMAIN\Administrator)
Administrator Password	Password for NTLM access
Multi Site	Tell Unison if all subsites are a member of the root site or are distinct sites with their own web services endpoints	Unchecked
Sites	List of paths for each site. For instance "/", "/MySite" without quotes

FreeIPA / Red Hat Identity Management

This target is for FreeIPA / Red Hat Identity Management (http://www.freeipa.org/page/Main_Page / https://access.redhat.com/products/identity-management-and-infrastructure). The provisioning target allows for the creation of users, updating of attributes and groups as well as setting passwords. In addition, the target can generate "shadow objects" designed to work with SSO and constrained delegation where a password shouldn’t be known.

Option	Description	Example
FreeIPA URL (Do NOT include the trailing slash)	The protocol and host of the FreeIPA IPA-Web server. Do NOT include any path information	https://freeipa.rhelent.lan
Admin User Name	The user name (uid attribute) of a member of the admins group	admin
Password	The password of the service account used to create accounts
Verify Password
Create Shadow Account	If true, when a user is created a random password is generated so that the account is active and ready for use, but not usable with a password	Checked
Support Multiple Domains	If true, this freeipa target will work with cross domain trusts. The userid will need to be the user’s userPrincipalName, not uid	unchecked
Primary Domain	If Support Multiple Domains is checked, this will tell the target the primary domain	rhelent.lan
Trust View	Determines the Trust View to use with multiple domains, default to Default Trust View	Default Trust View

OpenShift

This target provides provisioning capabilities for Red Hat’s OpenShift (http://openshift.com and http://openshift.org) Platform as a Service. With this target you can create and delete users, update a user’s Full Name and update groups. In order for the target to work, you need an account with cluster administration privileges.

There are two options for this account. The first is to use a user account that is either a member of a group that has been assigned or is individually assigned to the cluster-admin role. Alternatively, an OpenShift service account can be created and assigned to the cluster-admin role. An OpenShift service account is recommended over a user account as that will work regardless of how OpenShift authenticates users (ie if OpenID Connect or SAML2 is used to authenticate users). If running in a pod, its better to use a service account assigned to the pod instead of embeding a token.

Create an OpenShift Service Account

$ oc new-project unison-service
$ oc project unison-service
$ cat <<EOF | oc create -n unison-service -f -
kind: ServiceAccount
apiVersion: v1
metadata:
  name: unison
EOF
$ oc adm policy add-cluster-role-to-user cluster-admin system:serviceaccount:unison-service:unison
$ oc describe serviceaccount unison
Name:           unison
Namespace:      unison-service
Labels:         <none>

Image pull secrets:     unison-dockercfg-oe7gj

Mountable secrets:      unison-token-gmhdw
                        unison-token-vdbkq
                        unison-dockercfg-oe7gj

Tokens:                 unison-token-gmhdw
                        unison-token-vdbkq
                        unison-token-x5y1y

$ oc describe secret unison-token-x5y1y

Name:           unison-token-x5y1y
Namespace:      unison-service
Labels:         <none>
Annotations:    kubernetes.io/service-account.name=unison,kubernetes.io/service-account.uid=bda8c387-58ea-11e6-b7c9-525400b18ee2

Type:   kubernetes.io/service-account-token

Data
====
token:          eyJhbGciOiJS...
ca.crt:         1066 bytes
namespace:      14 bytes

Use the token above in the token option below.

Option	Description	Example
OpenShift RESTful Base URL (Do NOT include the trailing slash)	The protocol and host of the OpenShift web services server. Do NOT include any path information. If running inside a pod leave this field empty and OpenUnison will determine the url based on environment variables	https://openshift.rheldemo.lan:8443
Use Token	Check if using an OpenShift service account instead of a user account	Checked
Authentication Token	IF Use Token is checked, set this to the token. See "Creating a Service Account". If running inside of a pod, leave this field empty and OpenUnison will use the pod’s service account.	eyJhbGciOiJSUz…
Admin User Name	IF Use Token is not checked, the user name of a user with cluster admin privilages	admin
Password	The password of the service account used to create accounts
Verify Password

OpenStack Keystone v3

The OpenStack Keystone target provides the ability to manage users inside of OpenStack. The target will create users, add them to groups and roles for a SQL domain. For LDAP domains it will provision users into roles. This target only supports the following attributes:

name
email
description
enabled
roles

The roles attribute is made up of JSON values that express the role in Keystone tearms. The JSON looks like:

{
  name : "name_of_role",
  scope : "project",
  domain : "mydomain",
  project : "myproject"
}

If scope is domain, then the project attribute is ignored. The id for all users in this target is the name attribute.

Option	Description	Example
OpenStack Keystone V3 Base URL (Do NOT include the trailing slash)	The protocol and host of the Keystone v3 web services server. Do NOT include any path information	http://rdo.rheldemo.lan:5000/v3
Admin User Name	The user name of a user with admin privilages	admin
Password	The password of the service account used to create accounts
Verify Password
Domain	The domain holding the service account used to connect to Keystone	default
Project Name	The admin project for OpenStack	admin
Project Domain Name	The domain holding the admin project	default
Users Domain	The id domain holding the users to manage	e9518777a4294c6d9cbe942b2f409830
Roles Only	Set to true if the usersDomain is not a SQL domain so that you can manage role memberships for domain members	true

MongoDB

The MongoDB provisioning target provides the capability to provision users and user groups in a single database. It is meant to work with the virtual directory insert. Both users and groups can be in any collection. While MongoDB has no sense of an "objectClass", this attribute is used to distinguish between users and groups. Group memberships are stored as an attribute value on a group with an identifier, NOT a distinguished name.

Creating Groups

To create a group in MongoDB make sure the following attributes are added:

unisonRdnAttributeName - Tells Unison what the rdn will be
The attribute named in unisonRdnAttributeName
objectClass - To identify groups

Option	Description	Example
MongoDB URL	The MongoDB connection url per https://docs.mongodb.com/manual/reference/connection-string/	mongodb://dbs.tremolo.lan:27017"
Database	The name of the database to use	unisonprov
User RDN	The rdn attribute for users	uid
User ID Attribute	The user identifier attribute	uid
User Object Class	The value of the "objectClass" attribute for users	inetOrgPerson
Group RDN	The rdn of group objects	cn
Group ID Attribute	The group identifier attribute	cn
Group Object Class	The group objectClass	groupOfUniqueNames
Group Member Attribute	Group attribute that stores members	uniqueMember
Group User ID Attribute	The user attribute used as the value for group membership	uid
Support External Users	If true, groups may point to users in the virtual directory that are NOT in MongoDB	true
Collection Attribute Name	The name of the attribute to store the object’s collection in	collection

Kubernetes CRD Users

This target will create objects User objects in Kubernetes. Its meant to be used with K8sCrdInsert in the virtual directory. Prior to using this insert the below CRD MUST be created.

Option	Description	Example
Kubernetes Target	The name of the openshift provisioning target to use	k8s
Namespace	The namespace to create users in	unison

Custom Resource Defenition

---
apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
metadata:
  name: users.openunison.tremolo.io
spec:
  group: openunison.tremolo.io
  versions:
    - name: v1
      served: true
      storage: true
  version: v1
  scope: Namespaced
  names:
    plural: users
    singular: user
    kind: User
    shortNames:
    - usr
  validation:
   # openAPIV3Schema is the schema for validating custom objects.
    openAPIV3Schema:
      properties:
        spec:
          properties:
            sub:
              type: string
            groups:
              type: array
              items:
                type: string
            first_name:
              type: string
            last_name:
              type: string
            email:
              type: string

Drupal 8

Create and manage users using JSON via the restful interface

Option	Description	Example
Drupal 8 Base URL	URL for Drupal	https://drupal.domain.com
Admin User Name	The admin username	admin
Password	Admin user’s password	*

Provisioning Custom Tasks

This section details the pre-built provisioning custom tasks. These tasks can be used in your deployments without change. Consult the Unison SDK for instructions on how to create a custom task.

All tasks have a common interface for specifying configuration options. Each task can take any number of name/value pairs. A single configuration option can have multiple values by listing the name/value pair for each value.

Filter Groups

Class Name - com.tremolosecurity.provisioning.customTasks.FilterGroups

This task can be used to limit the groups that are available to a target. For instance if a user could have the groups "Admin","Developer" and "User" but the target only has the groups "Admin" and "User" this task can be used to filter out "Developer". This way no "rogue" groups are presented to a target. This task should be used inside of a mapping task to make sure that other tasks are not effected.

Option	Description	Example
name	A group name that should pass through this filter, case sensitive and can be listed multiple times	User

Load User Attributes

Class Name - com.tremolosecurity.provisioning.customTasks.LoadAttributes

This task will load attributes from a user’s entry in the virtual directory. It’s useful when a workflow is only being called with a user identifier or a subset of attributes and additional attributes are needed for reporting or decision making.

Option	Description	Example
name	An attribute name to load, case sensitive and can be listed multiple times	sn
nameAttr	The name of the attribute that identifies the user in the virtual directory	mail

Map User Groups

Class Name - com.tremolosecurity.provisioning.customTasks.MapGroups

The Map User Groups task will map group names from a "global" name to a target specific name. For instance if there is a generic group called "Administrator" but the target stores administrators in the group "SYS_ADMINS" this task can be used to create that mapping. It should be deployed inside of a mapping to make sure that global groups are not effected.

Option	Description	Example
map	A mapping of target from source. To map Admins -→ SYS_ADMIN the value should be SYS_ADMIN=Admins. This attribute can be mapped multiple times.	SYS_ADMIN=Admins

Complete Registration / Set User’s Password

Class Name - com.tremolosecurity.provisioning.customTasks.SetPassword

This task is useful in user registration scenarios where a user’s password must be set but the email address needs to be verified. It triggers a password reset through the password reset authenticaiton mechanism. In order for this task to work, it MUST have a password reset authentication mechanism configured where the workflow is configured.

Option	Description	Example
mechName	The name of the password reset mechanism as defined in the Auth Mechs section.	PasswordReset

Set Groups from Attribute

Class Name - com.tremolosecurity.provisioning.customTasks.Attribute2Group

This task takes the values of an attribute and adds them to a user’s groups. This is useful when building generic workflows.

Option	Description	Example
attributeName	The name of the attribute to get the group values from. Once the values are added, the attribute is removed from the user.	roles

Ignore Groups

Class Name - com.tremolosecurity.provisioning.customTasks.JITIgnoreGroups

This task will allow for a group to be ignored during a just-in-time provisioning process. If the user is a member of the named group in named target the user’s provisioning object is also given the group. This way when the synchronization occurs the group is ignored.

Option	Description	Example
groupName	The name of the group to ignore	Administrators
targetName	The name of the provisioning target to search	adUsers

Load Groups

Class Name - com.tremolosecurity.provisioning.customTasks.LoadGroups

The Load Groups task will load all the groups a user is a member of in Unison’s virtual directory. It can also optionally load the "inverse", only groups the user is NOT going to be a member of after this task. This can be useful when deleting a user from a group.

Option	Description	Example
nameAttr	The attribute name to search for on the user’s account	mail
inverse	If set to true, only loads the groups from the virtual directory that the user’s object is NOT already a member of	false

Load Groups from Target

Class Name - com.tremolosecurity.provisioning.customTasks.LoadGroupsFromTarget

The Load Groups from Target task will load all the groups a user is a member of from a specific provisioning target. It can also optionally load the "inverse", only groups the user is NOT going to be a member of after this task. This can be useful when deleting a user from a group.

Option	Description	Example
nameAttr	The attribute name to search for on the user’s account	mail
inverse	If set to true, only loads the groups from the virtual directory that the user’s object is NOT already a member of	false
target	Name of the target	my-target

Just-In-Time Create Groups

Class Name - com.tremolosecurity.provisioning.customTasks.JITBasicDBCreateGroups

The Just-In-Time Create Groups task can create groups in a database table if they aren’t present. This is useful when using a database to store group information in a cloud situation where the list of groups is unknown at deployment time. It is used in conjunction with a database provisioning target that has a group table defined.

Option	Description	Example
targetName	The name of a database provisioning taget	jitdb

Print User Info

Class Name - com.tremolosecurity.provisioning.customTasks.PrintUserInfo

The Print User Info task is useful when developing and debuging workflows. It will pring the user’s attributes to the Unison log file.

Option	Description	Example
message	An optional label to add to the log message	"After approval"

Create OTP Key

Class Name - com.tremolosecurity.provisioning.customTasks.CreateOTPKey

Creates an OATH key, used with the Time Based One Time Password authentication mechanism.

Option	Description	Example
attributeName	The name of the attribute to store the token in	l
hostName	The host name of the service, used for identification in the authenticator	www.someplace.com
encryptionKey	The name of the key used to encrypt and decrypt the user’s token. Can be obtained from the TOTP Authentication Mechanism on your Authentication Chain.	lastmile-enc-totp

OpenStack Ketstone AddRoleTask

When used with the OpenStack Keystone provisioning target, this task makes it easier to add (or remove) a role from the user’s roles attribute. This task will generate the proper JSON. All of the configuration options are parameter aware. It is recommended to use this task rather then the standard add attribute task when working with OpenStack roles.

Option	Description	Example
name	The name of the role, if not specified defaults to $role_name$	$role_name$
scope	The scope of the role, may be project or domain	project
domain	The name of the domain, defaults to $project_domain_name$ if not specified	$project_domain_name$
project	The name of the project, defaults to $project_name$	$project_name$
remove	Set to true if the role should be removed from the user’s object	false

Create Mongo Groups

This custom task can be used in a workflow to create groups in your Mongo database that don’t exist. This is useful if you are letting users dynamically determine what groups are used for authorizing access using dynamic workflows.

Class Name - com.tremolosecurity.mongodb.unison.CreateMongoGroups

Option	Description	Example
collectionName	Collection to create groups in if not found	groups
targetName	The target to search and create groups in	mymongodb
requestAttributes	Check a request attribute for a group name, like what might by used in a dynamic workflow	approvalGroup

Call Remote Workflow

Calls a remote Unison to execute a workflow. Authentication is done via lastmile. This task is built to work with the com.tremolosecurity.proxy.filters.CallWorkflow filter configured on a url with the OAuth2 authentication mechanism.

Option	Description	Example
workflowName	Name of the workflow to call on the remote Unison server	updateLockout
lastMileKeyName	Static key used to encrypt the LAstMile token	lastmile-workflowkey
url	URL to call	https://openunison.domain.lan/workflows/call
lastMileUid	Attribute from LastMile user to identify the LastMile account	uid
staticRequestValues	List of request variables to include	UNISON.EXEC.TYPE=UNISON.EXEC.SYNC
lastMileUser	Name of the user to use in the LastMile request	system
timeSkew	skew to allow for time drift across servers in millis	60000
uidAttributeName	name of the attribute in the workflow object that identifies the user	uid

Add Group to Target

This task will add a group to a named data store. The data store MUST implement com.tremolosecurity.provisioning.core.UserStoreProviderWithAddGroup.

Option	Description	Example
target	The name of the target to create the group in	rhelent.lan
name	The name of the group(s) to add, may be listed multiple times. Values can use values from the request object	created-$DYN_NAME$-workflow

OpenShift Add Group to Role

Class Name - com.tremolosecurity.unison.openshiftv3.tasks.AddGroupToRole

The Add Group To Role task will add a group to a project role. Useful when onboarding a new project.

Option	Description	Example
targetName	Target to run against	openshift
projectName	Project to add to, supports request parameters in between dollar signs	$project$
groupName	Group to add supports request parameters in between dollar signs	$project$
roleName	Role to add to, supports request parameters in between dollar signs	view

OpenShift Create Project

Class Name - com.tremolosecurity.unison.openshiftv3.tasks.CreateProject

This task creates an OpenShift project.

Option	Description	Example
targetName	Target to run against	openshift
template	The JSON template of a ProjectRequest object, supports request parameters in between dollar signs	{"kind":"ProjectRequest","apiVersion":"v1","metadata":{"name":"$project$","creationTimestamp":null}}

Copy From User to Request

Class Name - com.tremolosecurity.provisioning.customTasks.CopyFromUserToRequest

This task will copy attributes from a user object to the request object.

Option	Description	Example
attribute	The name of the attribute to copy, may be listed multiple times	projectName
keepInUser	If false, the attribute is removed from the user object	false

Create Kubernetes Object

Class Name - com.tremolosecurity.provisioning.tasks.CreateK8sObject

Creates an object in Kubernetes using an OpenShift provisioning target.

Option	Description	Example
targetName	An OpenShift provisioning target configured to connect to a Kubernetes API server	k8s
template	Template for object to create, can container parameters from the request and user’s object between $ symbols	{"kind":"Namespace","apiVersion":"v1","metadata":{"name":"$nameSpace$","labels":{"name":"$nameSpace$"}}}
kind	The type of object to create	Namespace
url	The URI of the service to call	/api/v1/namespaces

Clear Groups

Class Name - com.tremolosecurity.provisioning.tasks.ClearGroups

Deletes all groups from a user’s object

Option	Description	Example

Environment2Request

Class Name - com.tremolosecurity.provisioning.tasks.Env2Req

Coppies environment variables to the workflow’s request object. The name of the parameter is the name of the object in the workflow request to create, the value is the name of the environment variable to get the value from.

Option	Description	Example
for_request		from_environment

ClearPasswordResets

Class Name - com.tremolosecurity.provisioning.customTasks.ClearPasswordResets

This task will clear out all password reset requests for the user.

Option	Description	Example
mechName	The name of the password reset mechanism	passwordReset

CopyGroupMembers

Class Name - com.tremolosecurity.provisioning.customTasks.CopyGroupMembers

CopyGroupMembers will copy the members from one group to another. This is useful when dynamiclly generating access control groups from a workflow.

Option	Description	Example
copyWorkflow	A workflow for performing the copy (see example)	addApproverUsers
copyTo	The name of the group to copy members to inside of a provisionng target	copyTo
copyFrom	The group in the virtual directory that is the source for members	cn=administrators,ou=groups,ou=shadow,o=Tremolo
uidAttributeName	The name of the user id attribute	uid
requestor	The requester for the audit trail	system

Example copyWorkflow:

<workflow name="addApproverUsers" label="Add approver users" description="Add new approval users" inList="false" orgid="63ada052-881e-4685-834d-dd48a3aa4bb4">
    <tasks>
        <mapping  strict="true">
          <map>
            <mapping targetAttributeName="sub" sourceType="user" targetAttributeSource="uid"/>
          </map>
            <onSuccess>
                <provision sync="false" target="jitdb" setPassword="false" onlyPassedInAttributes="false">
                    <attributes>
                        <value>sub</value>
                    </attributes>
                </provision>
            </onSuccess>
        </mapping>
    </tasks>
</workflow>

DoesGroupExist

This task will check to see if a group exists in a target, and put the result in a request parameter.

Option	Description	Example
target	The provisioning target to chec	openshift
groupName	The group name to check	approvers-openshift-$name$
attributeName	The name of the request attribute to create	tremolo.approval.group.exists

Message Listeners

This section details the pre-built message listeners. These tasks can be used in your deployments without change. Consult the Unison SDK for instructions on how to create message listeners.

All listeners have a common interface for specifying configuration options. Each task can take any number of name/value pairs. A single configuration option can have multiple values by listing the name/value pair for each value.

Update Approvals Authorizations

Class Name - com.tremolosecurity.provisioning.listeners.UpdateApprovalAZListener

This listener is used in conjunction with the Update Authorizations scheduled task. The scheduled task identifies open approvals and places those approvals on the queue. This listener picks those approvals up and re-sets the allowed approvers.

Automatically Fail Open Approvals

Class Name - com.tremolosecurity.provisioning.listeners.AutoFailApprovalListener

This listener is used in conjunction with the Automatically Fail Open Approvals scheduled task. The scheduled task identifies which open approvals are assigned to the failure user and adds those approvals to the queue. This listener executes the failure of those requests.

Execute Workflows Asynchronously

Class Name - com.tremolosecurity.provisioning.listeners.AsyncExecuteWorkflow

Use this listener to execute workflows asynchronously, usually from a scheduled jobs. In order to run a workflow, enqueue a WFCall object.

Metrics JMS Pull Listener

The Metrics JMS Pull Listener receives Prometheus metrics requests via a JMS queue instead of HTTP and then based on the configuration will pull in metrics requests for several remote instances. This is designed to provide the ability to have a remove Prometheus monitor an environment without an ingress into the network.

Option	Description	Example
Send To Queue	Response queue message listener is configured on	MyQueue
URLs for Testing	url data for what metrics endpoings to check	see below
Additional Metrics Class	Implementation of com.tremolosecurity.prometheus.sdk.AdditionalMetrics
Additional Metrics Initialization Parameters	Additional parameters for extra metrics

The URLs for Testing setting

This setting is JSON describing what metrics endpoints should be pulled. Below is an example of the JSON:

[ { "url": "https://X.X.X.X:8443/metrics", "cluster": "unison", "ipAddress": "X.X.X.X", "clusterLabel": "remote_job", "ipLabel": "remote_instance", "lastMileAuthentication": true, "lastMileKeyName": "lastmile-prometheus", "lastMileUidAttributeName": "uid", "injectIpAndCluster": true, "timeout": 2000, "lastMileTimeSkewSeconds": 30, "lastMileUid": "prometheus" }, { "url": "https://X.X.X.X:8443/node-metrics", "cluster": "node", "ipAddress": "X.X.X.X", "clusterLabel": "remote_job", "ipLabel": "remote_instance", "lastMileAuthentication": true, "lastMileKeyName": "lastmile-prometheus", "lastMileUidAttributeName": "uid", "injectIpAndCluster": true, "timeout": 2000, "lastMileTimeSkewSeconds": 30, "lastMileUid": "prometheus" } ]

Jobs

This section details the pre-built Unison jobs. These jobs can be used in your deployments without change. Consult the Unison SDK for instructions on how to create custom jobs.

All jobs have a common interface for specifying configuration options. Each job can take any number of name/value pairs. A single configuration option can have multiple values by listing the name/value pair for each value.

Update Authorizations

Class Name - com.tremolosecurity.provisioning.scheduler.jobs.UpdateApprovalAz

This job evaluates all open approvals and resets the allowed approvers based on the configured authorizations in the workflow. This allows for any changes to members of groups or that a filter would apply to to be reflected in the list of open approvers. This job is used in conjunction with the Update Approvals Authorizations message listener. The job finds all open approvals and adds each approval to the queue. The Update Approvals Authorizations message listener then updates the allowed approvers for each open approval.

Option	Description	Example
Queue Name	The name of the queue the Update Approvals Authorizations message listener is configured on	MyQueue

Open Approvals Reminder

Class Name - com.tremolosecurity.provisioning.scheduler.jobs.RemindApprovers

This job provides a mechanism for reminding users that they have open approvals waiting for their action.

Option	Description	Example
Message to send	The template for the message to send to the approvers. Use %L to represent the label of the workflow that is open and %D to represent the number of days open	The request %L has been open for %D days, please login to act on this request
Number of days open before sending a reminder	The number of days an approval request should be open before sending a reminder	7
Mail Attribute Name	The name of the attribute that stores the approver’s email address	mail

Automatically Fail Open Approvals

Class Name - com.tremolosecurity.provisioning.scheduler.jobs.AutoFail

This job identifies all open approvals assigned to a specific user and marks them to be declined. The job takes these approval requests and puts them on a queue to be picked up by the Automatically Fail Open Approvals listener.

Option	Description	Example
Queue Name	The name of the queue to add approval requests to	autoFailures
Failure Reason	A message to be provided to users as to why the request failed	Your request was not approved within one week
Auto Fail User	The name of the user whom all failures are assigned, must be the value of the user identifier attribute configured on the audit database	failUser

Clear OpenID Connect Sessions

This scheduled job will clear our stale sessions.

Option	Description	Example
Identity Provider	The name of the identity provider to clear sessions for	MyOpenIDConnectIDP

Delete Kubernetes / OpenShift Object

This job will delete a Kubernetes/OpenShift object. Its most useful when a distrobution continously creates objects that are not needed or wanted on a consistent basis.

Option	Description	Example
OpenShift / Kubernetes Target	The name of the provisioning target	openshift
URI of Object To Delete	The URI of the object to delete	/apis/authorization.openshift.io/v1/clusterrolebindings/self-provisioner

Dynamic Workflows

LDAP Groups

The LDAP Groups dynamic workflow generator lets you create a set of workflow instances dynamically from a set of groups in the virtual directory. This dynamic workflow can pull a description, approver, and name out of each group.

Option	Description	Example	Parameter Name in Workflow
Search Base	Where to start searching for groups	ou=ldap,o=Tremolo
Search Filter	Filter to use when searching for groups	(objectClass=groupOfNames)
Group Name Attribute	Name of the attribute that stores the group’s name, required	cn	groupName
Description Attribute	Name of the attribute that stores a description, optional	description	descriptionAttribute
Approver Attribute	Name of the attribute that stores the approver for access to this group	owner	approver

OpenShiftv3

The OpenShiftv3 dynamic workflow generator will create workflows based on any list from OpenShift. Each workflow has access to the name of the item, as well as all annotations. Any annotations with a "-" or "." in the name will be replaced with a "_". For instance the annotation "openshift.io/description" would referenced in a workflow by "$openshift_io/description$".

Option	Description	Example
OpenShift Provisioning Target	The name of the provisioning target to use to communicate with OpenShift	my-openshift
URI	URI of service to use to build the workflows	/oapi/v1/projects
Filter Out Objects by Name	Filter out objects by name

OpenStack Keystone v3

The OpenStack Keystone v3 can generate workflows based on data inside of OpenStack. It can create workflows for either each domain or project and optionaly for each role. For instance if a workflow is based on both roles and projects then a workflow will be created for each role and each project. If there are 4 roles and 3 projects then 12 workflows will be generated. If not all targets or roles are desired (or only if certain ones are desired) then the list of targets and roles may be filtered. This is useful if you don’t want to expose certain combinations. such as the SwiftOperator or ResellerAdmin roles, for users to request.

Parameters are generated dynamicly based on the objects returned by Keystone. Each parameter starts with either a "role_", "domain_" or "project_" depending on the source object type and then the name of the attribute. For instance a project with the name "myproject" would have a parameter called "project_myproject". Note that Keystone will let you add arbitrary attributes to any role, domain or project but the openstack command line tool only supports adding properties to a project. These extra attributes can be used to define additional data such as approvers or descriptions.

Option	Description	Example
OpenStack Provisioning Target	Name of the OpenStack target used to communicate with Keystone	my-openstack
Scope	Determine which target to list, may be projects or domains	Projects or Domains
Include Roles?	Set to true if roles for each target should be listed, otherwise only one workflow per target is created	Checked
Role Filter Mode	Determinse if a filter should be applied to role names, and if so how: none - Apply no filter include - Include ONLY roles listed in Role Filter exclude - Include roles that are NOT listed in Role Filter
Role Filter	List of role names to filter on	ResellerAdmin,SwiftOperator
Target Filter Mode	Determinse if a filter should be applied to target names, and if so how: - None - Apply no filter - Include Those Listed - Include ONLY roles listed in Target Filter - Exclude Those Listed - Include roles that are NOT listed in Target Filter
Target Filter	List of targets to filter on

Database Target

Useful when generating workflows based on a database. Relies on an existing target. All fields returned by the SQL are available to the workflow

Option	Description	Example
Database Provisioning Target	The target to use	my-db
SQL	SQL to run	SELECT id FROM x

Custom Mappings

This section provides documentation for custom mapping implementations.

Upn2Uid

The com.tremolosecurity.unison.freeipa.mapping.Upn2Uid mapping will take a userPrincipalName with the format user@domain and replace the "@" with a "." to make it compatible with the uid attribute.

Custom Results

This section provides documentation for custom result implementations

com.tremolosecurity.proxy.results.InjectIdToken

This custom result is designed to use an OpenID Connect session when interacting with Kubernetes through a web browser. For instance when using the dashboard this result will inject an id_token that will be validated by the api server providing authenticated access.

High Availability

Overview

Unison can provide services in a HA, or High Availability, environment. This ensures that if there is network infrastructure outage or a hardware failure Unison protected applications will remain available. Unison works in an HA mode at several layers:

Clustering Unison
Load Balancing Unison
Load Balancing Directories and Applications

Each of these topics is discussed in detail in the following sections. When deploying Unison into an HA environment, there are certain points to take into account:

Unison requires "sticky" sessions when behind an HTTP load balancer
Unison does not have an integrated load balancer for backend applications and directories
Unison has a centralized configuration management system

Clustering Unison

Unison can be clustered such that a single configuration change is propagated out to all the members of the cluster. Unison has two potential models for clustering: A master/slave model, where a single server is the configuration "master" while multiple "slaves" consume configuration data or a file system model where Unison listens for changes to certain files to trigger a reload. When a configuration change is made to Unison, the change is not pushed to slaves until it is explicitly pushed.

When Unison pushes a configuration to slaves the following are pushed:

All configurations, including changes to the Proxy, Admin Service and Web Service
All JSP forms and images in the apps/proxy/auth directory
The Keystore used by Unison

When using the web service model the configuration is pushed over port 9090 (the administration port) using certificate authentication. For details on how to add slaves and change the certificate used for securing the admin system, see the administration guide.

The file system model is useful when working in an environment where there’s a shared file system and setting up a static cluster is not possible, such as when deploying Unison in Docker.

There are two methods for configuring Unison clusters:

Peer Mode - All Unison servers in the cluster accept user requests
Client/Server Mode - The configuration master does not serve user requests

Each method has its advantages and disadvantages. Its recommended that port 9090 run on its own network interface with limited access. Each of the two methods are detailed below.

Peer Mode

In Peer Mode all of the Unison servers accept requests, however one is marked as a "master" and is used for configuration. This mode has the advantage of not requiring any additional firewall rules. It does however require that the administrator has direct access to the Unison boxes. It also means that any configuration changes maybe be slowed down by handling user requests.

Client / Server Mode

In Client / Server Mode the Unison servers used to handle user requests are not used to make configuration changes. In this scenario a separate server is used as the master, generally outside of the DMZ used for hosting Unison, with changes being pushed to slaves running in a DMZ. This setup has the advantage of providing a single server for administration that can not be accessed from an external connection and can provide configuration data to multiple physical locations without those locations having direct access to each other. The main disadvantage to this approach is it requires a separate server to run Unison in configuration mode and firewall rules to allow 9090 into the Unison DMZ.

Load Balancing In-bound Connections

Unison handles two types of in-bound connections: LDAP(S) and HTTP(S). Since LDAP is a statefull protocol, once a connection is established with a Unison instance the client will continue to work with that connection. For this reason LDAP connections can be load balanced either via a DNS server, reverse proxy or when running "beside" Unison. HTTP(S) connections are stateless, each individual request requires a new network connection which may be routed to any of the Unison servers in the cluster. Since Unison has an internal session, HTTP requests MUST be load balanced in "sticky" mode. This means that all connections from a client MUST always go to the same server.

Load Balancing Out-bound Connections

Unison relies on external load balancers for lod balancing outbound connections. For LDAP servers either DNS, reverse proxy or running "beside" the LDAP servers is supported. The same is true of HTTP connections, however that is dependent on individual applications.

Tremolo Security Unison Configuration & Deployment

Introduction

What is Unison?

How the Pieces Fit

How Does Unison Fit in Your Enterprise?

What Do You Need to Get Started?

Where Do I Start?

Initial Configuration

Proxy Configuration Wizard

Application Integration

Create the Test User

Create the Test Application

Login to Test Application

What’s Next?

Installing Unison

Installing Unison from RPMs

Installing Unison on Linux

Installing Unison with Docker

Tremolo Security Unison Appliance

Overview

File System Layout

Controlling Unison with the /etc/init.d/unison Script

Unison Utilities

Print Configuration

Save Configuration

Export Server Package

Logs

Creating Services

Red Hat Linux 6.x / CentOS 6.x

Red Hat Linux 7.x / CentOS 7.x

Server Setup Wizard

Proxy First Time Setup

Identity Provider Wizard

Introduction

Welcome

Identity Provider Basic Information

Identity Provider Signing Certificate

Identity Provider Encryption Certificate

Create New Directory?

Directory Information

Directory Configuration Validation

Identity Provider Attributes

SP Meta Data Import

SP Meta Data Import Verification

Next Steps

Application Wizard

Welcome

Application Basic Information

Create New Directory?

Directory Information

Directory Configuration Validation

Authentication Type

Just-In-Time Provisioning

Provisioning Target

Target Configuration Validation

Just-In-Time Provisioning

Attribute Mappings

Group Mappings

Last Mile Configuration

Administration Reference

Servers

Manage Proxy

Restart Proxy

Reload Proxy Configuration

Manage Proxy Libraries

Proxy Libraries

Virtual Hosts

Proxy Virtual Hosts

Virtual Host Configuration

Manage Virtual Directory

Reload Virtual Directory Configuration

Manage Web Services

Reload Web Services Configuration

Manage Admin Service

Administrative Authentication

Update License

Download Server Package

Manage Configuration Slaves

Slaves

Update Cluster Configuration