Copyright 2015-2018, Tremolo Security, Inc.

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:

images/unison-where-unison-fits.png

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

images/unison_scale.png
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.

images/unison-manual-rev-proxy.png
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:

images/unison-manual-ldap-vd.png
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

images/unison-manual-unison-cloud.png
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:

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:

images/unison-first-1.png

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:

images/unison-first-2.png

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.

images/unison-first-3.png

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:

images/unison-first-4.png

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

images/unison-first-5.png

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

images/unison-first-6.png

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

images/unison-first-7.png

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:

images/unison-first-8.png

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

images/unison-first-9.png

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.

images/unison-first-10.png

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"

images/unison-first-11.png

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

images/unison-first-12.png

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

images/unison-first-13.png

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.

images/unison-first-14.png

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"

images/unison-first-15.png

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

images/unison-first-16.png

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:

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.

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

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.

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:

  1. Simple Lookup – Search based on a specific attribute value, for instance uid and myuser

  2. LDAP Filter Lookup – Use an LDAP filter to perform a search, for instance (&(uid=myuser)(objectClass=inetOrgPerson))

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

  1. Application Data – Information such as the name, cookie domain and logout url

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

  1. Add the group MyGroup to the user object

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

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:

  1. Internal Queue

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

images/unison-manual-basicdb-simple.png

Schema for Users and Groups

images/unison-manual-basicdb-groups.png
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

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:

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:

  1. Manually – Provide specific configuration options

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

  1. otherName

  2. email

  3. dNSName

  4. x400Address

  5. directoryName

  6. ediPartyName

  7. uniformResourceIdentifier

  8. iPAddress

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

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

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

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'

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

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

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

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

Alfresco ECM

Alfresco is an open source enterprise content management system that uses a RESTful web service for creating and updating users. This target allows the integration of Alfresco into a workflow.

Option Description Example

Name

A descriptive name for the target

Alfresco

Admin Service URL

The full URL of the admin service

https://alfresco.enterprise.com /alfresco/service/api

Admin User

User with admin privileges

Admin

Admin Password

Password for admin user

Username Attribute Name

The user id attribute

username

Use Last Mile Security?

If set to true, a last mile header will be added to each RESTful request. If false, then the URI of the service api MUST be ignored by the last mile system

True/False

Last Mile Key Alias

If “Use Last Mile Security?” is true, the key to use to generate the header

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.

image

Figure 1 – Group Management Mode: None

image

Figure 2 – Group Management Mode: Many to Many

image

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

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
$ oadm 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

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"

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:

  1. name

  2. email

  3. description

  4. enabled

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

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

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.

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

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

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

image

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

image

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.