Unison 1.0 - Tremolo Security · Alfresco ECM ... High Availability ... Clustering Unison ...

Unison 1.0.6

Administration and Configuration

iii

Table of Contents1. Introduction .................................................................................................................. 1

What is Unison? ......................................................................................................... 1How the Pieces Fit ...................................................................................................... 1How Does Unison Fit in Your Enterprise? ...................................................................... 2What Do You Need to Get Started? ............................................................................... 8

2. Where Do I Start? ......................................................................................................... 9Initial Configuration .................................................................................................... 9Proxy Configuration Wizard ......................................................................................... 9Application Integration ................................................................................................. 9

Creating the Test User ......................................................................................... 9Create the Test Application ................................................................................. 11Login to Test Application ................................................................................... 15

What's Next? ............................................................................................................ 153. Installing Unison .......................................................................................................... 17

Installing Unison from RPMs ...................................................................................... 17Installing Unison on Linux .......................................................................................... 17Using the ISO to create a Unison Appliance .................................................................. 22

4. Tremolo Security Unison Appliance ............................................................................... 23Overview ................................................................................................................. 23Configuring the Appliance .......................................................................................... 23Users ....................................................................................................................... 23File System Layout .................................................................................................... 24Controlling Unison with the /etc/init.d/unison Script ........................................................ 24Unison Utilities ......................................................................................................... 25

Print Configuration ............................................................................................ 25Save Configuration ............................................................................................ 26Export Server Package ....................................................................................... 26

Logs ........................................................................................................................ 26Creating Services ....................................................................................................... 27

Red Hat Linux 6.x / CentOS 6.x .......................................................................... 27Red Hat Linux 7.x / CentOS 7.x .......................................................................... 27

5. First Time setup ........................................................................................................... 28Initial Setup .............................................................................................................. 28

Tremolo Unison First Time Setup ........................................................................ 28Upload Tremolo Server Package .......................................................................... 28Manual Configuration ....................................................................................... 28

6. Server Setup Wizard .................................................................................................... 30Proxy First Time Setup .............................................................................................. 30

7. Identity Provider Wizard .............................................................................................. 31Introduction .............................................................................................................. 31Welcome .................................................................................................................. 31Identity Provider Basic Information .............................................................................. 31Identity Provider Signing Certificate ............................................................................. 31Identity Provider Encryption Certificate ......................................................................... 32Create New Directory? ............................................................................................... 32Directory Information ................................................................................................. 33Directory Configuration Validation ............................................................................... 33Identity Provider Attributes ......................................................................................... 33SP Meta Data Import ................................................................................................. 34SP Meta Data Import Verification ................................................................................ 34Next Steps ................................................................................................................ 34

Unison 1.0.6

iv

8. Application Wizard ...................................................................................................... 35Welcome .................................................................................................................. 35Application Basic Information ..................................................................................... 35Create New Directory? ............................................................................................... 35Directory Information ................................................................................................. 35Directory Configuration Validation ............................................................................... 36Authentication Type ................................................................................................... 36Just-In-Time Provisioning ........................................................................................... 36Provisioning Target .................................................................................................... 36Target Configuration Validation ................................................................................... 37Just-In-Time Provisioning ........................................................................................... 37

Attribute Mappings ............................................................................................ 37Group Mappings ............................................................................................... 37

Last Mile Configuration ............................................................................................. 38None ............................................................................................................... 38Secure Last Mile ............................................................................................... 38Header ............................................................................................................. 38

9. Administration Reference .............................................................................................. 39Servers ..................................................................................................................... 39

Manage Proxy ................................................................................................... 39Manage Virtual Directory ................................................................................... 41Manage Web Services ........................................................................................ 42Generate PaaS Package ...................................................................................... 44Manage Admin Service ...................................................................................... 44Manage Certificates ........................................................................................... 48Admin Service Directories .................................................................................. 50

Access ..................................................................................................................... 51Find Users ........................................................................................................ 51Applications ..................................................................................................... 51User Directories ................................................................................................ 54Authentication Mechanisms ................................................................................. 55Authentication Chains ........................................................................................ 56Result Groups ................................................................................................... 57Custom Authorizations ....................................................................................... 58

Provisioning ............................................................................................................. 58Provisioning Targets .......................................................................................... 58Workflows ........................................................................................................ 59Organizations .................................................................................................... 61Message Queue ................................................................................................. 63Scheduler ......................................................................................................... 64Workflow Tasks ................................................................................................ 66Approvals ....................................................................................................... 70Portal URLs ..................................................................................................... 71Reports ............................................................................................................ 72Database Schema ............................................................................................. 73

10. Directory Configuration ................................................................................................. 77Normalization and DN Mapping .................................................................................. 77Testing Configurations ............................................................................................... 77Inserts ...................................................................................................................... 77

Insert ............................................................................................................... 77Directory Types ........................................................................................................ 78

Active Directory ................................................................................................ 78LDAP Directory ................................................................................................ 79Admin ............................................................................................................. 80

Unison 1.0.6

v

Amazon SimpleDB ............................................................................................ 80BasicDB .......................................................................................................... 81Remote Schema ................................................................................................ 83NoOp .............................................................................................................. 84Joiner .............................................................................................................. 84

Insert Reference Guide ............................................................................................... 84External Group Members .................................................................................... 85Corrupt ObjectGUID .......................................................................................... 85Create UPN ...................................................................................................... 85TOTP Authentication ......................................................................................... 85UUID To Text .................................................................................................. 85

11. Authentication Mechanisms ........................................................................................... 87Form Login .............................................................................................................. 87

Mechanism ....................................................................................................... 87Chain ............................................................................................................... 87

SAML2 .................................................................................................................... 87Mechanism ....................................................................................................... 87Chain ............................................................................................................... 87

Anonymous .............................................................................................................. 90Mechanism ....................................................................................................... 90Chain ............................................................................................................... 90

Basic ....................................................................................................................... 90Mechanism ....................................................................................................... 90Chain ............................................................................................................... 90

IWA ........................................................................................................................ 91Mechanism ....................................................................................................... 91Chain ............................................................................................................... 91

SSL Certificate Authentication ..................................................................................... 91Mechanism ....................................................................................................... 91Chain ............................................................................................................... 92

Username Only Login ................................................................................................ 93Mechanism ....................................................................................................... 93Chain ............................................................................................................... 93

Banner Acknowledge ................................................................................................. 93Mechanism ....................................................................................................... 94Chain ............................................................................................................... 94

SMS Token Authentication ...................................................................................... 94Mechanism ....................................................................................................... 94Chain ............................................................................................................. 94

Secret Question Authentication ................................................................................ 95Mechanism ....................................................................................................... 95Chain ............................................................................................................. 95

Login Service ......................................................................................................... 95Mechanism ....................................................................................................... 96Chain ............................................................................................................. 96

OAuth2 Bearer - Last Mile ...................................................................................... 96Mechanism ....................................................................................................... 97Chain ............................................................................................................. 97

Just-In-Time Provisioning ........................................................................................ 97Mechanism ....................................................................................................... 97Chain ............................................................................................................. 97

Persistent Cookie .................................................................................................... 97Mechanism ....................................................................................................... 98Chain ............................................................................................................. 98

Unison 1.0.6

vi

Time Based One Time Password .............................................................................. 98Mechanism ....................................................................................................... 98Chain ............................................................................................................. 99

12. Filters ....................................................................................................................... 100Create an attribute from a group membership ............................................................... 100Create an attribute from a base DN ............................................................................. 100Login Test .............................................................................................................. 101Create XForward Headers ......................................................................................... 101Create AWS Role Attribute ....................................................................................... 101Stop Processing ..................................................................................................... 102Execute Workflow ................................................................................................... 102User to JSON ....................................................................................................... 102Check Authorizations ............................................................................................ 102Remote Basic Authentication ..................................................................................... 102Last Mile Security ................................................................................................. 103Check Shadow Account ......................................................................................... 103Basic Authentication .............................................................................................. 104Anonymous Authentication .................................................................................... 104Hide Cookies from Client ......................................................................................... 104Decode Form Parameter Name ................................................................................... 104Last Mile JSON IdP .............................................................................................. 104Pre-Authentication ................................................................................................ 104Create attribute from group memberships ............................................................... 105Cookie Filter ........................................................................................................... 105

13. Identity Provider Configuration ..................................................................................... 107SAML2 .................................................................................................................. 107

Access URLs .................................................................................................. 107Global Configuration ........................................................................................ 107Trust .............................................................................................................. 108

14. Custom Authorization Rules ......................................................................................... 110Manager Authorization ............................................................................................. 110

15. Provisioning Targets ................................................................................................... 111LDAP Directory ...................................................................................................... 111Alfresco ECM ........................................................................................................ 112Active Directory ..................................................................................................... 113Relational Database ................................................................................................. 113Amazon SimpleDB ................................................................................................. 116Tremolo Unison ..................................................................................................... 117SugarCRM ............................................................................................................ 117SharePoint Groups .................................................................................................. 118

Multi Site Integration ....................................................................................... 118Reliable Provisioning Provider .................................................................................. 118

16. Provisioning Custom Tasks .......................................................................................... 120Filter Groups ........................................................................................................... 120Load User Attributes ................................................................................................ 120Map User Groups .................................................................................................... 120Complete Registration / Set User's Password ................................................................ 121Set Groups from Attribute ......................................................................................... 121Ignore Groups ......................................................................................................... 121Load Groups ........................................................................................................... 122Just-In-Time Create Groups ....................................................................................... 122Print User Info ........................................................................................................ 122Create OTP Key ...................................................................................................... 122

17. Message Listeners ...................................................................................................... 124

Unison 1.0.6

vii

Update Approvals Authorizations ............................................................................... 124Automatically Fail Open Approvals ............................................................................ 124

18. Jobs .......................................................................................................................... 125Update Authorizations .............................................................................................. 125Open Approvals Reminder ........................................................................................ 125Automatically Fail Open Approvals ............................................................................ 126

19. High Availability ....................................................................................................... 127Overview ................................................................................................................ 127Clustering Unison .................................................................................................... 127Peer Mode .............................................................................................................. 128Client / Server Mode ................................................................................................ 129Load Balancing In-bound Connections ........................................................................ 130Load Balancing Out-bound Connections ...................................................................... 130

1

Chapter 1. Introduction

What is Unison?Tremolo Security’s Unison is powerful way to provide authentication, course grained authorization andidentity 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 identityinfrastructure into the cloud

Unison combines the identity tools needed by applications into a single virtual appliance that can be usedto enhance the implementations of internal applications or provide identity services to applications in thecloud. 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 forindividual configuration options.

How the Pieces FitTremolo Unison combines the functions of many pieces of an identity management infrastructureincluding:

• Authentication System

• Virtual Directory

• Certificate Manager

• Authorization Policy Manager

• Reverse Proxy

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

Introduction

2

Each label in the above diagram corresponds to a configuration section in the administration interface. Thefirst layer has “web servers” for accessing Unison. The administration interface typically runs on port 9090and ALWAYS runs over SSL. The reverse proxy is the main interface that users access. Additional virtualhosts may be configured to support multiple application hosts. An LDAP virtual directory interface allowsapplications to access identity data. The web services interface provides access to Unison workflows via aRESTful web service. These systems all interact with a server core. The core systems organize applicationinteractions and users are authentication. Unison has an internal virtual directory. This virtual directoryhandles all interaction with external data stores. Finally, Unison has an integrated user provisioning systemincluding 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 theidentity functions most commonly needed by applications, including:

• Authentication

Introduction

3

• Federation – Allowing another party to perform authentication for you instead of managing thecredential yourself

• PIV Cards / SSL – Common in the US Federal Government, allows the use of federal ID badges forauthentication

• Username and Password – Commonly used by most applications

• Virtual Directory

• Authorization

• Just-in-Time Provisioning

• Application Integration

• User Provisioning Web Services

• Access Requests

Introduction

4

When your application uses Unison users will interact with your application by putting a url, such ashttps://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

Introduction

5

• 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 leverageUnison as an LDAP virtual directory without using the reverse proxy as in the below diagram:

Introduction

6

In the above scenario Unison is acting as an LDAP virtual directory to provide identity data to anapplication using the LDAP standard. This provides a simple integration method for applications that

Introduction

7

need to authenticate users using a username and password. In this scenario the user authentication occursaccording 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 thisdeployment scenario much of the functionality that Unison offers cannot be utilized. This includes:

• Federation

• PIV / SSL Authentication

• Common Access Controls

Unison is purpose built for deployment in the cloud. Unison is able to provide the identity integrationfeatures 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

Introduction

8

• LDAP virtualization of cloud databases to provide dynamic identity data to applications without settingup 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 alocal network.

• Cloud Provider Image – If Unison is to be installed into a cloud environment retrieve the cloud providerspecific 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’sdocumentation for integration with an SSO system.

9

Chapter 2. Where Do I Start?Getting Unison from installed to operational is a very simple process:

• Run through the initial configuration process

• Run the "Proxy" configuration wizard

• Integrate an Application

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

Proxy Configuration WizardOnce 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 tosupport logins and logouts.

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

Creating the Test User

The first step is to create a test user to be able to login with. Unison manages an internal LDAP VirtualDirectory to manage all user authentication and authorization requests. One of the supported directorytypes 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:

Where Do I Start?

10

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

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

Where Do I Start?

11

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

Create the Test Application

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

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

Where Do I Start?

12

On the "Edit URL" screen, fill out the information as per below. This main information tells Unison howto 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 intothe browser).

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

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

Where Do I Start?

13

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

Under "Hosts" click "Add Host":

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

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

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

Where Do I Start?

14

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

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

On the Edit Rule screen choose "dn" as the LDAP Scope and o=Tremolo as the Constraint. This tellsUnison 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.

Where Do I Start?

15

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

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

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

What's Next?Now that you have Unison running you can start integrating new applications and authenticationmechanisms. The rest of this manual contains all of the configuration information for Unison. In addition:

Where Do I Start?

16

• Tremolo Security SAML2 Playground - https://www.tremolosecurity.com/support/ - Use TremoloSecurity's testing identity provider to test applications without setting up your own identity provider

• Application Integration Wikis - https://www.tremolosecurity.com/wiki/ - See how-to's and videos onhow to integrate with various applications

17

Chapter 3. Installing Unison

Installing Unison from RPMsAny RHEL based system (RHEL 6/7, CentOS 6/7, Amazon Linux) can become a Unison virtual applianceby installing the RPM. To install the rpm, first add tremolosecurity.com's RPM repository to your yumrepositories and then install the unison package.

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

Unison is ready to be configured on port 9090

Installing Unison on LinuxIf you are deploying Unison on a cloud hosted system and are unable to use the ISO you can install unisondirectly. Before installing a base line system must have:

The following minimum hardware (or virtual hardware):

• 8GB of hard disk space

• 1GB RAM

• a network connection

In addition, Unison requires these minimum packages:

• openssh-clients

• sudo

• ntp

• xorg-x11-server-Xvfb

• libXext

• hal

• libXtst

• nx

• iputils

• openssl

• java-1.7.0-openjdk-devel

Installing Unison

18

Note that these package names are based on RedHat 6.x packages. Other distributions might have differentnames. Additionally Oracle's JDK may be substituted for OpenJDK but the Unlimited JCE policy filesMUST 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 rundirectly 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 Iunison_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.

If the file is not executable, update the permissions with the following command:

$ chmod +x $PATH_TO_INSTALLER/unison_installer.bin(again, 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)

Once started, the installer will guide the installation process. It will:

1. Display a message indicating that the installer has begun

2. Present the EULA one page at a time and ask the user to agree Press Enter or the Space Bar to advancethrough the EULA. Enter "A" at the prompt to agree.

Installing Unison

19

Installing Unison

20

Installing Unison

21

Installing Unison

22

3. Ask for the directory to which Unison should be installed (the default directory is /usr/local/tremolo)To use the default directory, press Enter. To use a different directory, enter the full path to the directory.

If the directory does not exist, the installer will ask if it should be created.

4. Copy the necessary files to complete the installation and display a message on how to start Unison aswell as how to access it via a web browser.

Once installation is complete, it is recommended that you configure iptables to forward all requests from80 to 8080 and 443 to 8443.

Using the ISO to create a Unison ApplianceTremolo Security makes available a CentOS based DVD image file that can be used to create a Unisonappliance. To use the ISO to create a Unison appliance on a physical server, download the ISO file andburn it to a DVD. Boot the server using the DVD and follow the prompts to install CentOS and Unison.To use the ISO with a virtual machine (VM) download the ISO file and point your VM to it. Boot the VMand follow the prompts to install CentOS and Unison.

The following minimum hardware (or virtual hardware) specs are required to use the ISO:

• 8GB of hard disk space

• 1GB RAM

• a network connection

Note: A connection to the internet is not required for Unison to function, but it is required to update/patchthe system.

23

Chapter 4. Tremolo Security UnisonApplianceOverview

Tremolo Security Unison is deployed as an appliance. It can be deployed onto dedicated hardware or intoan existing virtual environment. The appliance is built on CentOS (http://www.centos.org), an enterprise-class Linux distribution.

Configuring the ApplianceAfter the appliance has been deployed, it must be configured for the network environment in which it willrun. To begin the configuration, log in to the appliance as the tremoloadmin user. The password should besupplied with the appliance image. A message is displayed indicating that the appliance must be configuredand that the configuration script will be automatically started.

Press Enter to display the Tremolo Security software license agreement. Enter ‘A’ to agree. The scriptwill generate SSH keys for the various appliance user accounts. Follow the prompts to generate the SSHkeys. Finally, the script will configure the network settings for the environment. To complete the networkconfiguration have the following information available.

• IP address

• Netmask

• Default gateway

• Hostname

• Domain name

• Primary DNS server IP

• Secondary DNS server IP (if applicable)

• NTP server address

• Time zone

Finally, the script will begin the process to change the passwords for the various default appliance useraccounts. Once complete the system will be automatically rebooted. Upon reboot, if Unison is not startedautomatically, start it with the following command:

/etc/init.d/unison start

UsersThe Unison appliance is configured with four user accounts at the operating system level. As part of theconfiguration process the password for each account must be set. SSH keys are automatically generatedas well.

• crluser - Used to maintain certificates and revocation lists

http://www.centos.org

Tremolo Security Unison Appliance

24

• tremoloadmin - Used to conduct administrative tasks on the appliance

• tremolo - Used to conduct non-administrative tasks on the appliance

• tremolosys - File owner for system files. No direct use currently.

File System LayoutUnison is installed on the appliance at the path /usr/local/tremolo/tremolo-unison. All of the files necessaryto the application are contained in this directory.

Important directories include the bin, conf, and logs directories. They are used to store binary/executablefiles, configuration files, and Unison's log files respectively.

• /usr/local/tremolo/tremolo-service/bin - Binary/executable files such as the tremolo.sh script used tocontrol 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 a dedicated Java Runtime Environment (JRE). It is self-contained and is stored at /usr/local/tremolo/jre.

Controlling Unison with the /etc/init.d/unisonScript

The Unison appliance is configured to start and stop Unison automatically when the appliance is bootedand shut down. To start and stop Unison manually, use the control script located at /etc/init.d/unison. Thescript can be used with the following arguments: start, stop, restart, status, getenv. Use the start/stop/restartarguments 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


25

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 UtilitiesNearly all configuration tasks can be performed from inside of the Unison administrative interface. If asituration 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, changedand re-encrypted. The tools described in this section assist in this process. NOTE: These tools are ment asa 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/tremolo-cfg.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 ConfigurationThe printConfig.sh script in /usr/local/tremolo/tremolo-service/bin provides the ability to decrypt one ofthese 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


26

• 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-encryptedusing the saveConfig.sh command.

Save ConfigurationThe saveConfig.sh script in /usr/local/tremolo/tremolo-service/bin provides the ability to encrypt aTremolo and MyVD configration file for use by Unison. It takes no command line parameters, but requestsfour 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 (typicly one of the above paths)

• Key - The license key for Unison

Export Server PackageThe exportPackage.sh script in /usr/local/tremolo/tremolo-service/bin will generate a server package thatcan 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 mostinstallations

• Package path - The full path to the file to save the package to, ie /tmp/unison-package.json

LogsThere are three main logs used by @PRODUCT@ for the following:

• tremolo.log - This file is used by the tremolo.sh script to log standard output and standard error associatedwith the starting and stopping of Prelude and its components on Linux and Mac OS X. This log is notused by Windows systems.

• tremolo-service.log - This is the service log used to log all events other than access events. The followinginformation 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 - StartedSSL 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] - AdminSystem - 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 externalrequests). It records the type of access, timestamp, user, connection operation on the connection andresults.

Location

For each operating system the logs can be found at:


27

/ PRELUDE_HOME /tremolo-prelude/logs

where PRELUDE_HOME is the directory in which Prelude was installed.

Creating ServicesUnison can be run as a service on either Red Hat 6.x or 7.x (and variants). Neither the installer nor the RPMinstalls the scripts by default but they are included in the bin directory. This section provides instructionsfor 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$ cp /usr/local/tremolo/tremolo-service/bin/unison-xvfb.chkconfig \ /etc/rc.d/init.d/unison-xvfb$ chmod 740 /etc/rc.d/init.d/unison-xvfb$ chkconfig unison-xvfb on$ chkconfig unison on$ service unison-xvfb start$ service unison start

Red Hat Linux 7.x / CentOS 7.xNOTE - 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-xvfb.service \ /etc/systemd/system/$ cp /usr/local/tremolo/tremolo-service/bin/unison.service \ /etc/systemd/system/$ systemctl daemon-reload$ systemctl enable unison-xvfb$ systemctl start unison-xvfb$ systemctl enable unison$ systemctl start unison

28

Chapter 5. First Time setupInitial Setup

Tremolo Unison First Time SetupAfter installing Unison it must be configured for your environment before it can be used. This processtakes only a few minutes and is the same for all operating systems.

To begin the initial setup of Unison, open a browser and navigate to:

https://HOST:9090

(where HOST is the host on which Unison was installed and started). This step assumes that Unison wasstarted after it was installed. If it wasn’t started, see the instructions above for how to start Unison on youroperating system.

The Tremolo Security Unison Initial Setup screen is displayed:

Fill in the required fields with your information and click OK.

Unison is now configured.

Additional information about each configuration field is included below.

Upload Tremolo Server Package• Tremolo Server Package - To add this Unison server to an existing cluster use this field to upload an

existing Tremolo server package.

• Admin Service IP - If the admin service will run on a specific IP, specify it here.

Manual ConfigurationSSL Information for Administration Server

• Server Name - Name of the server on which Unison is running.

• Department - Department name.

• Company - Company name.

• City - City name.

• State - Fully spelled out province or state (Ex. Virginia)

• Country Code - Two-letter country code (Ex. US)

• Keystore Password - Password to be used to encrypt the Unison keystore.

Server Information

• IP Address - The IP address on which Unison should listen. Leave this field blank to configure Unisonto listen on all available addresses.

First Time setup

29

• Secure Port - The port on which the Unison administrative user interface should listen.

Administrative User

• Login ID - The login ID for the Unison administrative user.

• Login Password - The password for the Unison administrative user.

License Information

• License Key - The Unison license key.

• Company Name - The company name associated with the license key.

• Year - The year the license key was issued.

• Month - The month the license key was issued. Use a two digit number to indicate the month. E.g. 01for January, 07 for May, 12 for December, etc.

• Day - The day of the month the license key was issued.

30

Chapter 6. Server Setup WizardProxy First Time Setup

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

Option Description Example

Server Name (CN) The Common Name of thecertificate. This is the server namethat users will type into theirbrowser.

apps.mycompany.com

Department (OU) The name of the departmentassigned to this certificate

IT

Company (O) The name of the companyassigned to this certificate

Tremolo Security Inc.

City (L) The name of the city the companyis located in

Arlington

State (ST) The FULL name of the state orprovince the company is in.

Virginia

Country Code (C) The two letter country code thecompany is in.

US

IP Address (blank for all) If Unison will run on a specificinterface, it can be specified here.Usually this is left blank

Open Port (blank for none) Port for non securecommunications. Usually this canbe left blank

External Open Port (blank fornone)

What port is used for externalURLs if different then the actualport being listened on. Forinstance if Prelude is running on8080 but a load balancer willpresent it on port 80 this would be80.

80

Secure Port (blank for none) Port for non securecommunications

8443

External Secure Port (blank fornone)

What port is used for externalURLs if different then the actualport being listened on. Forinstance if Prelude is running on8443 but a load balancer willpresent it on port 443 this wouldbe 443.

443

31

Chapter 7. Identity Provider Wizard

IntroductionThe Identity Provider Wizard is designed to help you connect your enterprise to your SaaS applicationsquickly. This wizard will guide you through the process of connecting Unison to your directory, generatingcertificates and connecting to your SaaS application.

WelcomeThe first screen is an introduction screen with no input. This screen gives you an overview of whatinformation you'll need.

Identity Provider Basic InformationThis screen configures two main pieces of information: The name of the IdP and the host users will useto access your IdP:


Identity Provider Name Descriptive name for the identityprovider. There should be nospaces

EnterpriseIdP

Enterprise Facing The host name (with no port) ofthe Unison URL. For instance ifUnison is being hosted at https://idp.myenterprise.com:8443 thenthis would beidp.myenterprise.com

idp.myenterprise.com

Identity Provider Signing CertificateWhen configuring an identity provider its important to always sign the assertions that are sent to your SaaSapplications. This ensures the SaaS application that your assertions are coming from you. This step willsetup a self-signed certificate that is used for signing. Once this step is complete, you may want to havethe certificate signed by a 3rd party CA. Additionally, you may choose an existing certificate.


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 lowercase

idp-saml2-sig

Name (CN) The Common Name of thecertificate. For web servers this isthe server name but for federationa descriptive name will do.

idp-saml2-sig

Identity Provider Wizard

32



IT




Arlington


Virginia


US

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


No Encryption If checked, no encryptioncertificate is generated orconfigured.

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 lowercase

idp-saml2-sig

Name (CN) The Common Name of thecertificate. For web servers this isthe server name but for federationa descriptive name will do.

idp-saml2-sig


IT




Arlington


Virginia


US

Create New Directory?If the IdP requires the integration of a new directory, check the box on this page. Otherwise directoryconfiguration will be skipped.


33


Create a new directory? If checked, the next screen will bethe creation of a new directory.

Checked

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


Source The type of directory to configure LDAP

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

Identity Provider AttributesUnison will supply a SaaS application with information about the logged in user via an assertion. Thisassertion can contain information such as a username, email address and entitlement information. Use thisscreen to configure these attributes.


Attribute Name The name of the attribute as it willappear in the assertion

userName

Source Type The user attribute the valuewill come from. There are threeoptions:

• user - An attribute that iscurrently a part of the user'sobject

• static - A pre-defined value thatnever changes

• composite - A combination ofstatic text and attributes definedby ${attributeName}

composite

Source The data to be used There are threeoptions:

• user - The name of the attribute,ie uid

• static - A set value, ie someData

${givenName}.${sn}@test.com


34


• composite - The compositeattributes, ie ${givenName}.${sn}@test.com

NameID? Will this attribute be used toidentify the user?

Checked

NameID Format SAML identifies different typesof user names. If this attribute isa NameID, you must specify whattype it is.

urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

Default Name ID Type? If the SaaS application doesnot specify a NameID format,either in its meta data or in theauthenticaiton request, should thisbe the default NameID?

checked

SP Meta Data ImportIn order to more quickly configure identity providers, SaaS providers may supply a meta data file thatcontains 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 fromit 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 manualy

SP Meta Data Import VerificationIf there are any issues with the meta data import, check the logs for any errors.

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


Reload Identity Provider Unison must be reloaded forchanges to take effect

Click the link

Generate IdP Meta Data Most SaaS providers will acceptmetadata files for simplerconfiguration. This section canbe used to quickly generate themeatadata

35

Chapter 8. Application WizardWelcome

This screen is informational and does not contain any configuration information

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


Application Name Descriptive name for theapplication. There should be nospaces

MyApp

Enterprise Facing The host name (with no port)of the Unison URL and theURI (path) the application willbe hosted on. For instance ifUnison is being hosted at https://apps.myenterprise.com:8443/testthen this would beapps.myenterprise.com in the firstbox and /test in the second box


Application Facing The host and port of the serverhosting the application behindUnison. For instance if theserver hosting the application is10.1.2.100 port 8080 then thiswould be 10.1.2.100:8080


Use SSL? If checked, Unison will useHTTPS instead of HTTP

Checked

Create New Directory?If the IdP requires the integration of a new directory, check the box on this page. Otherwise directoryconfiguration will be skipped.


Create a new directory? If checked, the next screen will bethe creation of a new directory.

Checked

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

Application Wizard

36


Source The type of directory to configure LDAP

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

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


Authentication Type Choose an existing authenticationchain or "New Chain" to create anew chain

New Chain

Authentication Mechanism If "New Chain" is selected, choosea mechanism to base the newchain on. Once selected, configurethe chain using the instructionsfrom the information fromthe Authentication Mechanismschapter.

New Chain

Just-In-Time ProvisioningIf the application needs user data to be populated as users login, check the box on this page. OtherwiseJIT provisioning configuration will be skipped.


Use Just-In-Time Provisioning? If checked, the next screen will beprovisioning configuration.

Checked

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


Existing Target Choose an existing provisioningtarget or "New ProvisioningTarget" to create a new target

New Provisioning Target

New Target Type If "New Provisioning Target"is selected, choose a targettype to configure. Once selected,configure the chain using theinstructions from the information

New Target Type

Application Wizard

37


from the Provisioning Targetschapter.

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

Just-In-Time ProvisioningOn this screen tell Unison how to map data from authentication into the application's user store.

Attribute MappingsIn this section tell Unison which attributes from authentication to provision into the application'sprovisioning target


Provisioned To The name of the attribute in thetarget system

login

Source Type One of user, static, custom orcomposite. user loads an attributedirectly from authentication. staticsets the value to a constantvalue. composite allows foran attribute to be built fromseveral attributes easily withsomething like "${givanName}${sn}". Custom is a class name.

uid

From Authentication The value of the attributeaccording to the source type

login

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

If doing a manual mapping:


Attribute Name The name of the user attribute tomap to a group

attribute1

Attribute Value The value of the attribute to mapto a group

value1

Group Name The name of the group to addto the user if the attribute name

group1

Application Wizard

38


and value are present in theauthentication data

Last Mile ConfigurationThe final step is to tell the application who the user is. There are three ways to do this, each with theirown advantages.

NoneThis option is only useful in situations where you plan on configuring a custom last mile integration.

Secure Last MileThis is the recommended option for integrating with applications. See the integration guide for specificinstructions on different application platforms. If "Set Use Groups to Role Attribute?" is checked then theattribute named in the "Role Attribute Name" box will be configured as the role identifier.

HeaderIf a Last Mile integration is not possible, you can use a header to supply the unique identifier.

39

Chapter 9. Administration ReferenceServers

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

Manage ProxyThis screen specifies on what ports Unison listens on:


Open Port The port that will listen on “http”,leaving blank means there will notbe an open port

8080

External Open Port If Unison is behind a firewallrunning a different port, this isthe open port that users see, oftenport 80. This setting is used forcreating redirects.

80

Secure Port The port that will listen using SSL,leaving blank means there will notbe a secure port

8443

External Secure Port If Unison is behind a firewallrunning a different port, this is thesecure port that users see, oftenport 443. This setting is used forcreating redirects.

443

Force to SSL Check this if the host should forceall requests to ssl

true/false

SSL Certificate The name of the certificate fromthe “SSL Certificates” section inCerts

idp-server

Allow SSLv3 Check this if the listener shouldallow SSLv3 connections, defaultto false

true/false

SSL Client Authentication When using SSL, is a trustedclient certificate required?

none – No client certificaterequired optional – If a certificateis available, accept it required –A certificate is REQUIRED toestablish a connection Note, thatto support SSL Authenticationoptional or required are needed.Selecting optional allows for userfriendly 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 toTLS_RSA_WITH_RC4_128_SHA,

Administration Reference

40


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 interfaceUnison will listen on, leave blankfor all interfaces

10.10.10.2

Open Session Cookie Name The name of the session cookie for"open sessions"

tremoloOpenSession

Open Session Cookie Timeout the number of seconds the opensession is idle until it is timed out

1200

Restart Proxy

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

Reload Proxy Configuration

Clicking on this link reloads Unisons configuration without restarting Unison. Click this link after makingchanges 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 separatecertificates for multiple proxys.

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:



8080

External Open Port If Unison is behind a firewallrunning a different port, this is

80


41


the open port that users see, oftenport 80. This setting is used forcreating redirects.


8443


443


true/false


idp-server



Available Ciphers Which ciphers will be used? If none are specified, defaults toTLS_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


10.10.10.2

Enabled If checked, the identity provider isrunning

Checked

Manage Virtual DirectoryThis screen specifies on what ports the virtual directory listens on:


Open Port The port that will listen on “ldap”,leaving blank means there will notbe an open port

10389

External Open Port If Unison is behind a firewallrunning a different port, this is

389


42


the open port that users see, oftenport 80. This setting is used forcreating redirects.


10636


636


true/false


idp-server




10.10.10.2

Enabled If checked then the virtualdirectory is started. Uncheckingthis box and submitting will stopthe virtual directory.

checked

Reload Virtual Directory Configuration

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

Manage Web ServicesThis screen specifies on what ports the user provisioning web services listens on:



External Open Port If Unison is behind a firewallrunning a different port, this isthe open port that users see, often


43


port 80. This setting is used forcreating redirects.


9093


9093


true/false


idp-server


true/false





10.10.10.2

Enabled If checked then the virtualdirectory is started. Uncheckingthis box and submitting will stopthe virtual directory.

checked

Session Key The session key used to encryptthe session for identity webservices.

tremolowssession

Session Cookie Name The name of the cookie foridentity web services

tremolowssession

Issuers Unison identity web servicesare secured using certificate


44


authentication. Specify whichcertificate issuers to trust from thisoption.

Reload Web Services Configuration

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

Generate PaaS PackageUnison can be deployed on top of a J2EE application as a Java Sevlet Filter. In this configuration Unisoncan provide authentication, authorization and just-in-time provisioning services to a J2EE applicationdirectly.

JDBC Data Sources

When working with a J2EE system it is a best practice to use the application server's integrated databasepooling instead of manually configuring a data source in Unison. When configuring any databasecomponents to use an existing database pool, use the com.tremolosecurity.proxy.util.DataSourceDriverand the url "jdbc:datasource://DSN". For instance if the data source name is java://MyDB then the urlshould be "jdbc:datasource://java://MyDB".

Limitations

When configuring Unison in PaaS mode Unison is not able to write response cookies or headers.

Configuration


UserID Attribute Name The name of the attribute onthe user object to pass tothe application. Accessible torequest.getUserPrincipalName().

uid

Role Attribute Name The name of the attribute onthe user object to pass to theapplication as role. Accessible inrequest.isUserInRole()

role

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



8080

External Open Port If Unison is behind a firewallrunning a different port, this isthe open port that users see, often

80


45


port 80. This setting is used forcreating redirects.


8443


443


true/false


admin-server


true/false


10.10.10.2

Enabled If checked, the admin service isrunning

Checked

Hosted on a Shared File System? If checked, Unison looks forchanges to the file system toreload or restart rather then usingthe configuration push system forconfiguration. This is useful insituations where the IP address ofthe server is not static.

Unchecked

Administrative Constraint Type Determines how Unisonauthorizes administrators. dn – Aroot dn, all users below this DNcan administer Unison group –The DN of a group of users thatcan administer Unison filter – anLDAP filter that can be used itidentify administrative users Seethe “Directories” section for howto specify a static group

dn

Administrative Constraint The constraint for identifyingadministrators. A DN, group orfilter See the “Directories” sectionfor how to specify a static group

ou=admin,o=Tremolo

Synchronization Certificate The certificate from the“Trusted Certificate Authorities”of certificate management torequire for cluster syncing

sync-certificate


46


JCE The class name of the JCEprovider to use. By default,org.bouncycastle.jce.provider.BouncyCastleProviderhowever another JCE (ie aFIPS 140-2 certified one) maybe specified. The server mustbe restarted after changing thissetting to take effect.

org.bouncycastle.jce.provider.BouncyCastleProvider

Administrative AuthenticationType

Use this setting to enableSAML2 authentication for theadministration portal. If SAML2is selected, the same screen as theSAML2 Authentication Chain isavailable.

Choose between "Username andPassword" and "SAML2"



Administrative Authentication

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


User ID Attribute Name The name of the user identifierattribute. Defaults to uid

uid

Update License

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


License Key The license key you wereprovided

9bde4b9493afcb89b908c9b9bf824334773f862d1343aa5asdds324

Company Name The EXACT company name asspecified in your license file

My Company


47


Year The 4 digit year your companywas registered

2011

Month The numeric month yourcompany was registered, in thelicense file

07

Day The day your company wasregistered, 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 bootstrapprocess 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 shouldbe listed as “host:port”. For instance if a slave is on Unison1.domain.com with SSL port 9090 the slaveshould 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 updatinga configuration to push the new configuration out to the cluster.

IdP 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 ProxyConfiguration” on the “Proxy” management screen

Reload Admin Equivalent to clicking on the “ReloadAdmin Service Configuration” on the “Admin”management screen

Restart Proxy Equivalent to unchecking “Enabled” on the “Proxy”screen, submitting, re-clicking “Enabled” andsubmitting again

Restart Admin Equivalent to unchecking “Enabled” on the“Admin” screen, submitting, re-clicking “Enabled”and submitting again


48

Upload Server Package

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

Manage CertificatesThe 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 willlisten over SSL, such as theidentity provider, admin serviceand any virtual hosts

Create, Import, Manage

Session Keys Used for encrypting the sessiontoken. These keys are used toseperate different sessions withthe same cookie scope.

Create, Delete

Signature and Encryption Keys Used for signing and encryptingdata outside of an SSL sessionsuch as signing and encryptingSAML2 assertions. These keysare used for outgoing data.

Create, Manage

Signature and EncryptionValidation Certificates

Used to validate and encryptdata outside of SSL forexternal sources such as SAML2assertions. These keys are used forvalidating incomming data.

Import, Delete

Trusted Certificate Authorities Certificates for CAs that aretrusted

Import, Delete

Manage Certificates

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:


Name A descriptive label idp-ssl

Server Name (CN) Either the Fully Qualified DomainName for the server this certificatewill be used for or a descriptivename

apps.mycompany.com

Organizational Unit (OU) What department is this certificatefor?

IT

Organization (O) The legal name of yourorganization

My Company Inc.


49


City (L) The name of the city yourcompany is located in

Arlington

State (ST) The FULLY SPELLED OUTname of your state or province. Donot use a two letter abbreviation

Virginia

Country (C) The two letter country code yourcompany is located in

US

Key Size The size of the key, 1024 is theminimum recommended key size

1024

Signature Algorithm How the certificate should be self-signed

SHA1withRSA

Valid After First date, in MM/DD/YYYY, theself-signed certificate is valid

10/05/2011

Valid Until Final date, in MM/DD/YYYY,the self-signed certificate is valid

10/02/2021

Import Key and Certificate

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

PKCS12 File


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 thePKCS12 file

1 by default

Password Password to unlock the PKCS12file

Verify Password Verify the password

Individual Files


Alias A descriptive label idp-ssl

Key File (PEM or DER) Either a binary or base64 encodedprivate key in PKCS1 or PKCS11format

Path to the file

Certificate File (PEM or DER) Either a binary or base64 encodedcertificate in PKCS1 or PKCS11format

Path to the file

Manage

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


50

• 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 certificateauthority. 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 thekeystore by clicking on this link. If the certificate is a text file, or PEM file, its contents can be copied andpasted into the “Certificate” box. If the file is a binary file, or DER file, it can be uploaded by clickingon 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. Additionaly links to download PEM or DERformatted 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 ofthe 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.

Import Certificate

If a certificate needs to be trusted there are three options for importing it. Option 1 is to copy and pastethe contents of the PEM file into the “Certificate” box. Option 2 is to directly import a certificate from aservice 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 HTTPSservice

• Option 3 - Upload either a DER or PEM encoded certificate

Admin Service DirectoriesThis section allows for the use of external user stores, such as LDAP directories or Active Directory, foraccess to the Unison administration site. Edit and Delete directories by clicking on the links next to thedirectory 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.


51

Access

Find UsersThe users section is a simple way to search for users in the internal virtual directory. There are three waysto 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 usingthe 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.

ApplicationsUnison 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 differenceis that a "User Application" is generally associated with a proxied application. An identity provider is aspecialized 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'sURL is static based on the name of the identity provider. Each identity provider can have only one URLwhere as an application can have any number of URLs

Application/Identity Provider

Every application and identity provider has some common configuration options:


Name A descriptive name for theidentity provider

Saml2

Type Determines if the application isa User Application or an IdentityProvider

User Application

Session Cookie The name of the session cookiefor the application. If you usethe same name across applicationsthere will be SSO between them.

Tremolosession

Session Cookie Secure If checked, the browser will onlysend the sessionc oookie for thisapplication when connected overan SSL or TLS connection.

true


52


Session Inactivity Timeout(Seconds)

The number of seconds that anin-active session can remain openuntil the user must re-authenticate.Specify 0 for no inactive timeout.

900

Session Cache Timeout inMilliseconds

Number of milliseconds thatan authorization decision madeabout a user exists before it isrevalidated

30000

Cookie Domain The domain to be listed in thecookie. Only domains that endin this domain will receive thesession cookie. For sso betweenapplications this cookie should bescoped high enough to be sent toall applications.

Unison.enterprise.domain.com

Logout URI The uri that will trigger an end tothe user’s session

/logout

Session Key Alias The encryption key to use forencrypting 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 onthe application name.


IdP Class Name The idp implementation type. Seethe Identity Providers referenceguide for individual options

SAML2

Authentication Success Result The result group to execute whenauthentication succeeds

My Success Group

Authentication Failure Result The result group to execute whenauthentication fails

My Failure Group

Authorization Success Result The result group to execute whenauthorization succeeds

My Success Group

Authorization Failure Result The result group to execute whenauthorization 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 witha set of authorization policies, filters and an end point to proxy to.


URI The URI to match on /myapp


53


Regular Expression If checked, Unison interprets theURI configuration option as aregular expression

unchecked

Proxy To Application? If checked, allows for a the ProxyTo field to be set.

checked

Proxy To The URL to proxy to with theURI being set based on requestvariables. To use the full URI, use${fullURI}. Any request variablecan be used by placing it inside ofa ${}.

https://10.10.0.14:8443${fullURI}

Override URL Host If set to true, the HOST header andall Referal and Location headersare mapped from the URL in therequest to the URL in the ProxyTo. If false, the host header is notchanged.

true

Authentication Chain The name of the authenticationchain to use with this URI. If theuser is already authenticated to achain of equal or higher value thenthe user is NOT re-authenticated.If the user is already authenticatedto a lower strength chain then theuser IS prompted to authenticate.

Default Form Login

Authentication Success Result The result group to execute whenauthentication succeeds

My Success Group

Authentication Failure Result The result group to execute whenauthentication fails

My Failure Group

Authorization Success Result The result group to execute whenauthorization succeeds

My Success Group

Authorization Failure Result The result group to execute whenauthorization 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 beincluded. For instance if Unison is listening on port 8443 the host should NOT be myhost.com:8443, itshould 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. Forinformation 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 aresatisfied then the user is given access. The below table defines how to specify a rule:


54


group Full dn of a static group. Groupsmay be looked up by clicking onthe "Pick Group" button to the leftof the "Constraint" box.

Cn=My Group,ou=groups,ou=MyDirectory,o=Tremolo

dn A root dn for all users with access.A root may be picked by clickingthe "Pick Root DN" button to theleft 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=MyDirectory,o=Tremolo

Mappings

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

Source Type Source Target Example

user Map an attribute form theuser’s directory object

Name of an attribute givenName

static A static value thatdoesn’t change

The static value Myvalue

custom A class that is used todetermine the mapping

Class name, see the SDKfor details on how toimplement

com.mycompany.mapper.Mapper

composite A composite of attributesand static values.Attributes are definedwith ${attributename}.Only attributes that existbefore the mappings arerun 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, seethe IdP configuration guide.

User Directories

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


55

Inserts

Inserts can be used to manipulate directory operations, including searches and results. Inserts may beconfigured either globally or on individual directories. See the insert configuration guide for options forspecific 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

Configuring an Insert

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


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 MechanismsAuthentication Mechanisms define the ways in which a user can be authenticated. Prior to being added to anauthentication chain, a mechanism must be defined in the section. Unless creating a custom authenticationmethod, it is generally not necessary to add mechanisms here. Every authentication method has its ownconfiguration parameters. See the Authentication Mechanisms section for configuration options on specificmechanisms.

Adding an Authentication Mechanism

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


Name A descriptive name for thisauthentication mechanism. Do notinclude spaces.

MyAuthMech

Class The Java class name for themechanism. If this is a custommechanism the java class namewill appear in the drop down box.

com.tremolosecurity.mech.MyAuthMech

URI The uri that users will beredirected to when authenticating.This uri should allways start with"/auth/".

/auth/myauth


56

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 andlist 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 alevel of “1” but certificate based authentication may have a level of “2”. If a user that logs in with a formbased authentication but attempts to access an area protected with a level 2 chain the user will be forcedto re-authenticate. In the reverse, a user authenticated at a level of 2 will not need to re-authenticate whenaccessing a URL protected by a level “1” chain.

Chaining mechanisms lets you validate a user’s identity in multiple ways. For instance you may haveIntegrated Windows Authentication for internal users, but want to provide a form for users that are usingexternal hardware (such as a tablet) or accessing the system remotely. A chain with an IWA mechanismand a form based mechanism where both are “sufficient” would accomplish this. Another possibility iswanting to use certificate authentication with a password as a second factor for software certificates. Usinga 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:


Name A descriptive label IWA Login

Level A number indicating theauthentication level

Arbitrary, ie 1

Directory Root DN of where to search for users inthe internal directory tree

o=Tremolo

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

Authentication Mechanism

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


Name The mechanism as defined in theAuth Mechs screen

loginForm

Required Determine if the mechanism isrequired or sufficient. If a requiredmechanism fails to authenticatethe user the entire chain fails.If any sufficient mechanismsauthenticate the user the chainsucceeds.

required - If the mechanism fails,the entire chain fails sufficient -If the mechanism succeeds, theentire chain succeeds


57

Result GroupsA Result Group is used to do something as a result of an authentication or authorization event. This couldbe the setting of an HTTP header, creating a cookie or sending a redirect. Result groups can be definedand re-used. For instance a common failed authentication result that will direct the user to a common errorpage 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 groupare 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 isadded to the request.Useful for passingattributes to a backendapplication.

name=value

cookie outbound Cookies are small piecesof information stored inthe browser.

name=value

Redirect outbound Instructs the user’sbrowser to go to anotherpage

value

Each result can have one of three sources:


static A static value, not changed basedon the user

Myheader=somevalue

user Comes from a user attribute Firstnameheader=givenname

custom A custom result generator, see theSDK for how to implement

Customheader=com.mycompany.tremolo.Result

Each result has the following configuration options


Type The type of result, see the abovetable for a detailed description ofthe options

header cookie redirect

Source Where the value for the result willcome from, see the above tablefor a detailed description of theoptions

static user custom


58


Value For header and cookie results, aname=value. For redirects, the urlto be redirected to

See above table for examples

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

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

• 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 bereferenced inside of authorization rules

Authorization Class Implementation ofcom.tremolosecurity.proxy.az.CustomAuthorization

Edit Edit the current authorization

Add New Custom Authorization Create a new custom authorization rule

Adding and Edditing Custom Authorization Rules

Prior to configuring a new authorization rule the class/jar that implements this rule must be uploaded toUnison 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.

Provisioning

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


59

Source Type Description Source Example










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

WorkflowsWorkflows are utilized to manage user data inside of a provisioning target or targets. A workflow can beused to manipulate a user’s attributes, add entitlements in the form of groups or attributes and to updatethe data in a target. Unison workflows follow a tree 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. For instance, inthe below workflow:

[pic]

Figure 1 - Unison Workflow

1. Add the group MyGroup to the user object

2. Does the user have the attribute myattr with the value myval?

3. Yes

4. Perform a mapping

5. Provision to the target named ldap

6. Resync the user object from the internal virtual directory

7. No

8. Resync the user object from the internal virtual directory


60

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 newworkflows. 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 theworkflow 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 willbe overwritten by the imported workflow.

Editing Workflows

When editing a workflow, there are three sections. The first section "Workflow Data" defines somecommon information about a workflow. The "Sub Tasks" section shows the various tasks at the currentlevel of the workflow. Finally the graphic on the right hand side has the graphical representation of theworkflow.

Workflow Data

This section has the following options:


Name An internal name for theworkflow.

AdminAddToGroup

Label A descriptive name for theworkflow. This is what users inScale will see.

Add a user to a group.

Description A description of the workflow forreference purposes in Scale

Requests for administrators

Organization The organization this workflowshould be included in if displayedin Scale.

Root

Include in List If checked, provides thisworkflow to Scale when lookingup available workflows.

Checked

Task Data

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

Sub Tasks

Unison workflows are built using a tree structure. This starts at the root and moves down each task. Whenediting a workflow, sub tasks can be added to the current task if that task allows sub tasks. To add a subtask to the current task, click on "Add Task". The task currently being edited is highlighted in white. Todelete 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 ofthe workflow. This can be useful when editing if you know exactly how to edit the XML tags. NOTE: this


61

should only be done if you are an expert, as editing the tags directly can cause the XML to be corruptedand 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 webservice interface. Clicking "Execute" lets you run a workflow from inside of the administrative console.


User Identifier Attribute Name The name of the attribute thatidentifies the user. The attributenamed here MUST be listed in theAttributes section

uid

Attributes Name/Value pairs of attributes tobe passed into the workflow. ATLEAST the attribute named in the"User Identifier Attribute Name"field must be listed. Multi-valueattributes may be listed multipletimes.

uid/someuser

Groups List of groups to be passed into theworkflow

MyGroup

Parameters Name/Value pairs to be passedinto the workflow's request object.Typically left blank.

Execute Approvals as CurrentUser

If checked, Unison will NOT senda notification on the first approvalseen and will assume that thecurrently logged in user to theadmin interface is an approver.In order for this to work theUnison admin console should beconfigred with the same sourcedirectory data as the user system.

Checked

Request Reson The reason why the workflow isbeing executed, recorded in theaudit logs

For testing

Approval Reason If "Execute Approvals as CurrentUser" is checked, the reason forthe approval. Recorded in theaudit log.

To test the workflow

OrganizationsOrganizations provide a way to organize workflows in a hierarchy. In a small deployment a singleorganization may be all thats needed, but in larger deployment it can be difficult to organize workflows. Bycreating 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 instancean organization called "Administrators" may only allow users that are a member of the administratorsgroup to execute workflows. This makes it easier to cut down on extra approvals.


62

Navigating Organizations

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

Organization DataOption Description Example

Name A descriptive name for theorganization. This is what userswill see in GetAccess.

Administrators

Description A description of the organizationfor reference purposes inGetAccess

Requests for administrators

Authorized Users

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


Constraint Scope How the constraint is enforced:Group is a static LDAP group,Filter is an LDAP filter and Useris 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.


63

Move Up

Moves the currently selected organization up in the ordered list of children for the selected organization'sparent.

Move Down

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

New Parent Organization

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

Message QueueUnison uses a message queue for all asynchronous provisioning operations. The use of a message queueallows Unison to ensure that workflows are completed, even if targets such as directories and databasesare down. Unison encrypts all messages sent to the queue for increased security. There are two modesthat 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 simplerdeployment model, but Unison servers are not able to failover in case of a failed provisioning task orspread the load across multiple servers. This is the default mode that Unison uses and no actions need tobe taken to get this working after installation.

Leveraging an external queue allows for high availability across Unison instances if a workflow fails onone server it can be picked up by another server. External queues can also increase the volume of operationsUnison can handle because tasks do not need to be processed on a single box. Any message queue thatsupports 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.


Use Internal Queue Determines if Unison should usethe internal ActiveMQ systemfor message management or anexternal system.

Checked

Task Queue Name The name of the queue formanaging workflow tasks

TremoloUnisonTaskQueue

Outbound Email Queue Name The name of the queue formanaging emails generated byUnison

TremoloUnisonSMTPQueue

Encryption Key The session key used to encrypt alltask messages.

workflowtasks


64

Empty Dead Letter Queue

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

External Queue Configuration

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


Provider Connection Factory Implementation ofjavax.jms.ConnectionFactory

org.apache.activemq.ActiveMQConnectionFatory

Maximum Message Producers Maximum number of threadsgenerating messages

5

Maximum Message Consumers Maximum number of threadsconsuming messages

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 forActiveMQConnectionFactory's setBrokerURL the property name would be brokerURL.

Message Listeners

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

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

Queue Listener

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


Class Name The name of the class or label com.company.MyQueueListener

Queue Name The name of the queue to listen on MyQueue

SchedulerUnison 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


65

recommended for production deployments to ensure that scheduled tasks are only executed once. Unisonuses the Quartz scheduler (http://quartz-scheduler.org).

Scheduler Configuration


Scheduler Label A descriptive label for thisscheduler

Unison

IP Mask This field is used to determinewhich IP address to use on thesystem to identify the particularinstance

192.168.2

Thread Count The number of threads thescheduler should use. Must be atleast 3

3

Use Database To Store Jobs If checked, use a database tomanage jobs. NOTE: prior tostarting Unison the databasemust be initialed per Quartz'documentation

checked

Job Database

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


Quartz Database Delegate ClassName

The delegate to use to work withthe 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 databasewith

Verify Password Verify your the password

Max Connections Maximum number of connectionsto the database

10

Validation Query A query that can be used to verifythe 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 descriptivename and group name to this job configuration. What you name the job and group are not important toUnison and are only used for organizational purposes. on startup.


Class Name The name of the class or label com.company.MyQueueListener


66


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

Provision to Target

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


Target A target as defined in the Targetsarea of the administration system

LDAP

Set Password If set to true this will create apassword on the user. Note thatnot all targets support password

True/False

Full Synchronization If checked, then the target willupdate the object in the target tomatch exactly the current user’sobject; potentially removingattributes and entitlements on theuser’s object in the target. Ifunchecked, then only the attributevalues on the user’s object willbe pushed to the target, inessence “overlaying” it onto theprovisioning target

True/False

If User Does Not Exist

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


User ID Attribute The attribute to test on uid, userPrincipalName

Add Group to User

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


Name The name of the group to add,must match the name of the groupin a downstream target.

MyGroup


67

Synchronize User Session from Directories

When executing a just-in-time provisioning workflow, for instance when using identity federation, oncethe 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.


Keep External Attributes? If true, will keep attributes fromthe external source (such as anassertion) that were not pushed todownstream targets

True/False

If Attribute has Value

This task will execute sub tasks if-and-only-if the user’s Unison object has an attribute with a matchingvalue.


Name The attribute to check MyAttribute

Value The value that must be present MyValue

If Attribute Exists

This task will execute sub tasks if-and-only-if the user’s Unison object has an attribute with a matchingname.


Name The attribute to check MyAttribute

Add Attribute to User

As the name specifies, adds a static value to the specified attribute of the user


Name The attribute to add MyAttribute

Value The value to add MyValue

Map User Attributes

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


Strict Mapping If checked, the user object used forsub tasks will only have attributesthat are explicitly listed in thismapping.

True/False


68

The below table details the mapping options:











Call Workflow

This task allows for another workflow to be called. This allows for the creation of modular workflows. Forinstance 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 withthe same results without having to duplicate the workflow.


Workflow The name of the workflow to call My Workflow

Approval

The approval task allows for steps to require approval from a pre-set list. The approval can be constrainedby a static group, an LDAP filter or a particular user or base. Approvals are not bound to a resource ortarget, 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 andUnits for each escalation. Escalations are sequential, for instance if the first escalation is marked for runningafter 5 days and the second escalation is marked for running after 5 days then it will take 10 days forthe second escalation will run. In addition to providing a time based escalation, an implementation ofthe 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 happenswhen no approvers are available for an escalation. However if "Assign" is used then the failure policy istreated as an escalation and the approvers as configured in the policy.


Label A descriptive name for thisapproval

Access to the portal

Email Template A template for the email sent toapprovers to notify them that they

You have an open approvalwaiting. Please go to https://


69


have an open approval. Attributesfrom the REQUESTOR’s objectcan be placed in the email byenclosing it in a “${}”. Forinstance, to include the user’sfull name user “${givenName}${sn}”

unison.mycompany.com/approvals/ to complete theapproval. Requesting user:${givenName} ${sn} ${mail}${ou}

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 ofthe request then the approval moves forward.

Scope Constraint Example

Group Full dn of a static group Cn=My Group,ou=groups,ou=MyDirectory,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 ruleconfigured on the "CustomAuthorizations" screen

ManagerLevel1

Notify User

This task provides a way to send an email to the requestor of the workflow. This can be used to notify theuser of a successful execution, request more information, etc. Emails are sent from the server specified inthe “Approval DB” section of the configuration interface.


Subject What should the subject line of theemail be?

Request for access has beenapproved

Mail Attribute Name The name of the user attribute thathas the user’s email address

mail

Message A template for the email sent toapprovers to notify them that theyhave an open approval. Attributesfrom the REQUESTOR’s objectcan be placed in the email by

${givenName} ${sn}, Thank youfor registering for the portal.Your request is waiting approval.Thanks The Team


70


enclosing it in a “${}”. Forinstance, to include the user’sfull name user “${givenName}${sn}”

Custom Task

Unison’s workflow engine provides the ability to create custom tasks written in Java. This task allows forthose tasks to be added to the workflow.


Class Name Implementation of thecom.tremolosecurity.proxy.auth.secret.CustomTaskinterface. Implementations shouldbe uploaded from the “ManageProxy Libraries” screen.

com.tremolosecurity.proxy.auth.secret.CreateSecretQuestionsTask

Initialization Parameters Name/Value pairs that can bepassed to the task when itsinitialized. These parameters canhave multiple instances of thesame parameter

AttributeName = something

Delete User

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

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


Enabled If not checked, and approvaldatabase is not registered. Allprovisioning actions are logged tothe tremolo-service.log

Checked

Approval and Audit Database

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


Driver The class of the JDBC driver com.vendor.jdbc.Driver

URL The JDBC URL for accessing thedatabase

jdbc:driver://host/db

User The user for connecting to thedatabase

Password The password for the database


71


Maximum Connections The maximum number ofconnections to the database

10

Maximum Idle Time The maximum time a connectioncan be idle before its closed inmilliseconds

1000

Validation Query A query that will be used to test ifa connection is active on checkout

SELECT 1

Workflow Encryption Key An encryption key, defined inthe CERTS section to encryptworkflows in process in thedatabase

workflowkey

User Identifier Attribute The name of the attribute on theuser that is used to identify them

mail

Report Approver Attributes The names of attributes that areadded to the approvers table.These attributes are meant to beused for reporting and audits.

sn cn givenName mail

Report User Attributes The names of attributes that areadded to the users table. Theseattributes are meant to be used forreporting and audits.

sn cn givenName mail

Mask Attributes The names of attributes who'svalues will NOT be written to theaudit database

secretKey

SMTP Settings


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 [email protected]

Password Password for accessing the SMTPserver

Validate Validate password

Subject The subject used for approvalnotifications

Approval Waiting

From Email address in the “From” of theemail

[email protected]

Use SSL Check if the server uses SSL True

Portal URLsWhile Unison can provision access to applications, its also can be important to be able to tell users aboutwhat applications they have access to. To provide this, Unison has a portal URL api that can be configuredon this screen. Each URL can be assigned to an organziation for situations where there are hundreds ofapplications a user may have. Each portal URL has the following options:


72


Name Descriptive name of the link MyApplication

Label The value show to the user as alink

My Application

URL The URL to be used for this link https://www.myapp.com/

Organization The organization this link shouldbe displayed for

Icon A PNG file that will be used forthis link. If none is specified then adefault one will be used. All PNGfiles shold be the same size, witha recommendation of 240x210.

Authorized Users Authorization rules that specifywhich users will see this link.

ReportsUnison provides a simple reporting mechanism that can be used to provide reports via the web servicesAPI. 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 aheader section for each data set

Parameters Unison reports can accept any of the fourparameters:

• 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, eachhaving an authorization

Each report has the following configuraiton options:


Name A descriptive name for the report Completed Approvals

Description A desctive blurb about the report All approvals completed betweentwo dates

Organization The organization that this reportwill sit in

Root Organization

SQL The SQL that drives this report.All paraeters must be marked as aquestion mark (?)

SELECT id, name as `WorkflowName` FORM workflows wherebeginTS > ? and endTS < ?

Header Fields Fields that should be displayed ina data set's header. NOTE - fields


73


MUST map to a field that is in theSQL SELECT clause.

Data Fields Fields that should be displayed ina data set. NOTE - fields MUSTmap to a field that is in the SQLSELECT clause.

Parameters List of which of the aboveavailable parameters are used bythis report

Break Report into Groups If checked, then each report willbe a collection of smaller subreports rather then one largereport.

Checked

Group By If Break Report into Groups ischecked, this field will tell Unisonhow to break the data set up. Inorder for the data set to be brokenup properly, the field specified inthis option should be the ORDERBY 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..." andchoose the file you wish to import. Follow the prompts to complete the import process.

Database SchemaUnison's provisioning model uses an open table format for storing relationships and audit data from theprovisioning process. This format allows for custom reporting as well as storage in any SQL database. Thebelow diagram and descriptions provide information on how these tables relate and provide the baselinefor 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 updatedbased on the user attributes to be tracked in reports. The only two fields in this table that are required areid 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 thistable 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


74

approvers

This table lists the approvers and certain attributes that have been processed. This table should be updatedbased on the approver attributes to be tracked in reports. The only two fields in this table that are requiredare 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 thistable called givenName, sn and mail.



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 automaticlypopulated when Unison is started or the configuration is re-loaded. It should only be used for reportingand should not be updated manually.



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.



entry id 1

name varchar(255) Workflow nameas configured inthe administrationsystem

AddUser

startTS datetime Timestamp forwhen the workflowwas started

2012-11-1511:45:23 AM

completeTS datetime Timestamp forwhen the workflowwas completed, nullis not completed

2012-11-1511:45:23 AM

userid int users.id Link field to theuser the workflow isacting on

1

requestReason text The reason why thisworkflow is beingexecuted

Need access to domy work


75

approvals

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



entry id 1

label varchar(255) Approval labelas configured inthe administrationsystem

Owner Approval

workflow int workflows.id 1

workflowObj text Encrypted andBase64'd workflowstate. If theapproval iscomplete, null

createTS datetime Timestamp forwhen the approvalstep was created

2012-11-1511:45:23 AM

approvedTS datetime Timestamp forwhen the approvalwas completed, nullif not completed

2012-11-1511:45:23 AM

approver int approvers.id Link field to theapprover that actedon this approval.null if not yetapproved.

1

approved int 1 if approved, 0 ifdenied

1

reason text Reason for theapproval action(denied orapproved)

More informationneeded

allowedApprovers

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



entry id 1

approval int approval.id ID of open approval 1


76


approver int approvers.id ID of potentialapprover

1

auditLogType

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



entry id 1

name varchar(255) Audit Log EntryType

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.



entry id 1

isEntry int 1 if the action isagainst the entry,0 if its against aparticular attribute

1

actionType int auditLogType.id ID of action type 1

userid int users.id ID of user beingacted upon

1

approval int approvals.id ID of approval, 0if no approval wasneeded

1

attribute varchar(255) The name ofthe attribute beingacted on

uid

val varchar(255) The value being set SomeUser

workflow int workflows.id The id of theworkflow beingexecuted

1

target int targets.id The id of the targeteffected

1

77

Chapter 10. Directory ConfigurationAt the core of Unison is an LDAP virtual directory that is used to provide Unison with identity data fromany directory or database in the enterprise. Each directory supported by Unison has its own configurationoptions defined in this section.

Normalization and DN MappingUnison creates an internal virtual directory of the directories configured. This provides tremendousflexibility. The root dn for a directory is based on the name of the directory. For instance if a directoryis named “My Directory” then the root will be “ou=My Directory,o=Tremolo”. DN attributes are alsomapped. If a user’s DN is cn=My User,cn=Users,dc=domain,dc=com for “My Directory” then the DN inUnison 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 meansthat when integrating an Active Directory into Unison the samAccountName will be mapped to uid, themember attribute will be mapped to uniqueMember.

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

InsertsUnison’s integrated virtual directory, based on the open source MyVirtualDirectory, supports insertsthat are similar to the HttpFilters that Unison supports and HttpServletFilters used when developingJ2EE applications. For a list of standard inserts, see the MyVirtualDirectory website (http://myvd.sourceforge.net/inserts.html). Inserts can either be configured globally from the “Directories” screenor 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 propertieswith the following options:


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 configurationproperty

MyProperty

Value The value of a configurationproperty

MyValue

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

Directory Configuration

78

Directory Types

Active Directory

Configuration of an Active Directory forest with the following options:


Name A descriptive name for thedirectory

MyForest

User Directory Determines if this directory storesuser objects (Default is True)

True / False

Enabled Determines if this directory willbe started (Default is True)

True / False


True / False

Remote Base The DN of the root Unison shouldconnect to

DC=domain,DC=com

Host The host for the forest, may be aload balancer

Ldap.myforest.com

Port The port to connect to, generally389 for open ports, 636 for secureports

389 / 636

Bind DN The full DN, unmapped, of aservice account user

cn=svcact,cn=Users,dc=domain,dc=com

Bind Password The password for the serviceaccount

Use SSL Determines if the connection tothe forest is secure. Either theconnection certificate or it’s rootcertificate must be trusted

Use Kerberos If SSL is not available, Kerberosauthentication can be used forauthenticating Unison users. Inorder for this option to work theforest must be configured on theIWA authentication mechanism.

Max Timeout (milliseconds) The maximum amount ofmilliseconds that an operation cantake before erroring out.

30000

Stale Connection Timeout(milliseconds)

The maximum amount ofmilliseconds that a connectioncan remain locked until itis considered stale. Once aconnection is considered stale theconnection is closed and re-addedto the pool.

60000


79


Minimum Number ofConnections

The minimum number ofconnection to open

10

Maximum Number ofConnections

The maximum number ofconnection to open

100

Heart Beat Interval inMilliseconds

Interval to send a heart beat 30 seconds

Use Paging Active Directory by default willonly support returning 500 objectsin a single search. Enablingthis option allows for the useof pages to return larger resultsets transparently. This setting isuseful when Unison is used as avirtual directory to perform largesearches.

checked

Page Size When used with "Use Paging",determines the size of each "page"when returning results. Should beless then 500.

450

LDAP Directory

Configuration of standard LDAP Directory with the following options:



MyForest

User Directory Determines if this directory storesuser objects

True / False


True / False


DC=domain,DC=com


Ldap.myforest.com


389 / 636

Bind DN The full DN, unmapped, of aservice account user

cn=svcact,cn=Users,dc=domain,dc=com

Bind Password The password for the serviceaccount



80


Stale Connection Timeout(milliseconds)

The maximum amount ofmilliseconds that a connectioncan remain locked until itis considered stale. Once aconnection is considered stale theconnection is closed and re-addedto the pool.

60000

Minimum Number ofConnections

The minimum number ofconnection to open

10

Maximum Number ofConnections

The maximum number ofconnection to open

100

Heart Beat Interval inMilliseconds

Interval to send a heart beat 30 seconds

Use Paging Active Directory by default willonly support returning 500 objectsin a single search. Enablingthis option allows for the useof pages to return larger resultsets transparently. This setting isuseful when Unison is used as avirtual directory to perform largesearches.

checked

Page Size When used with "Use Paging",determines the size of each "page"when returning results. Should beless then 500.

450

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



MyForest


True / False


True / False

Login ID The user’s login name Myuser

Password The user’s password

Amazon SimpleDBUnison can use Amazon SimpleDB to store user and group information. This allows for a cloud basedsolution with no storage or backup footprint. This can provide an extremely effective way to store cloud


81

based identities without having to deploy a cloud based LDAP directory. In order to use this directory typeyou must have an Amazon Web Services account. This directory should be used in conjunction with theAmazon SimpleDB provisioning target.



MySimpleDB


True / False

Access Key The access key generated byAmazon Web Services

Secret Key The secret key provided byAmazon Web Services

User Domain The domain to store userinformation 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 canNOT be used for authentication, only for user attribute data. The database can store users and optionallygroups using a many-to-many relationship. It does not require a specific schema, but the tables specifiedmust follow a particular pattern:

Schema for Users Only


82

Schema for Users and Groups



MySimpleDB


True / False




User The user for connecting to thedatabase



10


1000

Users Table Name The name of the table that storesthe user objects

Users

Users Table Primary Key The name of the column in theuser table that is the primary key

id

Use Groups? Determines if this database storesgroup information about the usersin the db

True/False

Group Table Name The name of the table that storesgroup information

Groups

Group Table Primary Key The name of the primary key ofthe group table

Id


83


Link Table Name The name of the table used to linkusers and groups

LinkTable

Link Table User Column The name of the column in thelink table that maps to the user’sprimary key

User


user


User

Link Table Group Column The name of the column in thelink table that maps to the group’sprimary key

Groups

User Mappings

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

Group Mappings

This area is where ldap attributes are mapped to database columns. The cn and uniqueMember LDAPattributes 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 anapplication, this directory type can be used to proxy the schema of another directory.



MySchema


True / False


cn=SubSchema


Ldap.myforest.com


389 / 636



84

NoOpThe "NoOp" directory is a placeholder for configuring custom directory types. This directory should useinserts for performing searches and authentication.



MySchema


True / False

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



MyJoiner


True / False

Primary Name Space The name space that will drive thedirectory structure of the joinedname spaces. All attributes fromthis name space are available.

ou=addomain,o=Data

Joined Name Space The name space to be joined to theprimary name space. This shouldbe the name space that storesadditional attributes.

ou=db,o=Data

Joined Attributes List of attributes from the joinedname space that will be availableto Unison.

givenName,sn,etc

Joined Object Classes Optional, list of objectClasses tolimit the join to

inetOrgPerson

Join Filter A filter that is used tocombine objects. When includingan attribute from the joiningentry prepend the attributewith "ATTR.". For instance, tocombine a user based on theuid attribute the filter would be"(uid=ATTR.uid)"

(uid=ATTR.uid)

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


85

External Group MembersThe External Group Members insert allows an Active Directory forest to store group members that are nota member of the forest or a trusted forest. This insert requires an attribute to be defined that will store theUnison 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, mustbe allowed on the group objectClass

Corrupt ObjectGUIDThis insert allows a client that tries to search on an ObjectGUID that has been cast to text improperly.

Class Name com.tremolosecurity.proxy.myvd.inserts.ad.ExternalGroupMembers

Create UPNActive Directory “user” objects don’t all have user principal name objects which can interfere withdirectory based systems that expect them. This insert will create a userPrincipalName object based on adirectory attribute and suffix.

Class Name com.tremolosecurity.proxy.myvd.inserts.ad.CreateUPN

prefixAttributeName The name of the attribute that’s used as the sourcefor the UPN; generally uid

suffix The domain name to use as a suffix for the UPN

TOTP AuthenticationThe TOTP Authentication insert provides TOTP authentication for users who have been provisioned witha TOTP token using the CreateOTPKey custom provisioning task by adding the current key to the end ofthe password after a ":". So if the current code is 123456 and your password is "secret" then the correctpassword 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 validfor

UUID To TextThe objectGUID attribute is a binary attribute that is often corrupted by translation to text. This insert willtranslate a binary attribute to text properly.


86

Class Name com.tremolosecurity.proxy.myvd.inserts.ad.UUIDtoText

attributeName The name of the attribute to map

87

Chapter 11. AuthenticationMechanisms

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

• Mechanism – In the Auth Mechs section, global to all authentication chains

• Chain – Configuration for a specific authentication chain

Form LoginAn 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.

MechanismNo configuration Parameters

Chain


Login JSP The URI for the jsp page used tolog the user in

/auth/forms/defaultForm.jsp

User Attribute Name/LDAP Filter Either an attribute name OR anldap filter mapping the formparameters. If this is an ldap filter,form parameters are identified by${parameter}

Attribute name : uidFilter : (&(uid=${username})(l=${locationName}))

Search Using LDAP Filter If true, the user is determinedbased on an LDAP filter ratherthan a simple user lookup

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

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

ChainWhen configuring the authentication chain there are two options:

1. Manually – Provide specific configuration options

Authentication Mechanisms

88

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.


Optional Identity ProviderEntityID

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 POSTendpoint


Identity Provider Redirect URL The URL for the IdP’sREDIRECT endpoint


Optional Identity Provider LogoutURL

The URL for the IdP’s SingleLogout Service HTTP-Redirectendpoint; requires that theSignature Certificate and OptionalFinal Logout URL be set


Optional Final Logout URL URL to redirect users to afterreceiving a response from theidentity provider indicating asuccessful 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) besigned?

Signing Algorithm The algorithm to use whensigning AuthnRequest andSingleLogoutRequest messagesto the identity provider

Signature Certificate The name of the certificate usedto validate the signed response /assertion

Certificate must be trusted in theCerts section

Required Authentication Type How does the user need to beauthenticated

Choose “other” to specify onemanually or leave blank to notrequire an authentication type

Other Authentication Type If “Other” is chosen for theRequired Authentication Type,one can be specified here

A SAML2 recognized contextclass ref

Service Provider Information

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


Force response to SSL For sites that do not work wellwith SSL this feature will allow anapplication to use federation for

If true, the certificate used to signthe metadata must be trusted in theCerts management system


89


https, but switch back to HTTPonce authentication is complete.Note: for this feature to worksesison cookies must NOT bemarked as secure.

Require Signed MetaData When importing metadata, must itbe signed?

If true, the certificate used to signthe metadata must be trusted in theCerts management system

Require Encrypted Assertion Must assertions be encrypted? Iffalse, encrypted assertions willstill be accepted if properlyencrypted

Assertion Decryption Key If an assertion is encrypted, whichkey should be used to decrypt it?

Key must be created in the Certsmanagement area

Sign Authentication Requests Should authentication requests besigned before being sent to theIdentity Provider?

Authentication Request SigningKey

If authentication requests aresigned, what key to use to sign therequest

Key must be created in the Certsmanagement area

Optional Jump Page URI An optional setting to allow for apage to be displayed to the userprior to SP initiated federationbeing triggered. This page is fornotifying the user they will beredirected for authentication.

Empty to be ignored or /auth/forms/jump.jsp for the defaultjump 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 loadedfrom the directory and the attributes from the directory are merged with whatever attributes were in theassertion. If a user can’t be mapped then a user object is created based on the information in this section.


LDAP Name Attribute Name of the attribute that theNameID in the assertion

Uid

DN Org Unit What the ou of the DN foran unlinked user should be. Forinstance if a user named testuseris authenticated but not associatedwith a user in the directoryand the value of this setting isSAML2 the user’s DN will beuid=test,ou=SAML2,o=Tremolo

External users

Default Object Class If a user can not be mapped, theobjectClass that should be usedwhen constructing the user object

inetOrgPerson

Do Not Attempt to Link toDirectory

If checked, Unison will skipattempting to find an object in

false


90


the internal virtual directory toassociate with this user. Thisshould be checked when usingJust-In-Time provisioning andwill reload the context AFTER theworkflow executes.

Generating Meta Data

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

AnonymousAnonymous authentication is used for scenarios when user authentication is not needed. Its not generallyneeded for Unison.

Mechanism


RDN Attribute name of theanaonymous user

uid

Value Attribute value of the anonymoususer

Anonymous

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

Chain

There are no chain specific configuration options.

BasicBasic authentication can be used for simple authentication tasks.

Mechanism

There are no mechanism configuration options.

Chain


Realm Name The name of the realm presentedto the user when authenticating

My Authentication Server


91


User Attribute Name The name of the attribute to usewhen looking for the user

uid

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

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


Enterprise The fully qualified domain nameof the domain

Enterprise.domain.com

KDC Host The host of the AD domaincontroller

Ad.enterprise.domain.com

SPN Service Principal Name – thesamAcountName of a user thathas been setup as a SPN.

To create an SPN: Create a serviceaccount in the domain Use thesetspn tool to create an spn onthe user with the host name of theUnison server

SPN Password The password for the SPN

ChainThere are no authentication chain configuration options.

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

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


Custom Extracts List of classes that implementscom.tremolosecurity.proxy.auth.CertificateExtractSubjectAttributeto get custom subject attributesfrom a certificate


92


Name A descriptive name for the CRL MyCRL

Type The type of CRL

Path The path to the CRL For File based, relativeto the TREMOLO_CRL_PATHenvironment variable For LDAP,an LDAP url for thecRLDistributionPoint object ForOCSP, 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 andlink them to a user in the directory. If a user can’t be linked in the directory then a user object is createdbased 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 anunmatched entry.


UID Attribute Either an attribute name OR anldap filter mapping the certificatedn components. If this is anldap filter, dn components areidentified by ${component}

Attribute name : uid Filter :(&(uid=${CN})(ou=${OU}))

Is Filter If the UID Attribute is a filter orjust an attribute name

RDN Attribute A list of attributes in the certificatesubject, or subject alternative

CN


93


names, that will be the RDN of anunmatched entry.

Default Object Class The object class to use for objectscreated because the user doesn’texist in the directory

DN for Unmatched Users The ou component of theDN to use for users notmatched. For instance if SSL isspecified the user’s dn would beuid=user,ou=SSL,o=Tremolo

SSL

Allowed Issuers List of DN’s of trusted certificatesthat the chain will accept

Username Only LoginAn HTML login form that ONLY collects a username. This mechanism is convinient when using a customauthentication scheme or authentication system that doesn't have a password (like SMS). All login formsmust 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


Username JSP The URI for the jsp page used tolog the user in

/auth/forms/userOnlyLogin.jsp

Username JSP The URI for the jsp page usedwhen a user can't be found

/auth/forms/noUser.jsp

User Attribute Name/LDAP Filter Either an attribute name OR anldap filter mapping the formparameters. If this is an ldap filter,form parameters are identified by${parameter}

Attribute name : uidFilter : (&(uid=${username})(l=${locationName}))

Search Using LDAP Filter If true, the user is determinedbased on an LDAP filter ratherthan a simple user lookup

Banner AcknowledgeThe Banner Acknowledge mechanism provides a way to make a user acknowledge a set of policies priorto 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.


94

MechanismNo configuration Parameters

Chain


Banner JSP The URI for the jsp page tohost the banner and requestacknowledgement

/auth/forms/acknowledge.jsp

Banner The text of the banner, may beHTML

I acknowledge that I am accessinga secured system and will not doanything I know I shouldn't.

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

MechanismThere are no mechanism level configurations

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


Account SID Twilio Account SID

Authentication Token Twilio Account token

SMS Source Phone Number Twilio Source Phone Number 1234567890

User Attribute That Stores User’sPhone Number

The attribute that stores the user’sphone number

mobile

Key Collection Form URI for the form to collect thelogin key

/auth/forms/smsKey.jsp

Message (for the OTP) The message to be sent to the user.“${key}” is used to represent thesingle use password.

Please login with ${key}

Key Size The length of the single usepassword

10

Use Upper Case Letters Checked if the single usepassword will have upper caseletters

checked

Use Lower Case Letters Checked if the single usepassword will have lower caseletters

checked


95


Use Numbers Checked if the single usepassword will have numbers

checked

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

MechanismQuestions users may choose from are configured on the mechanism.

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


Login JSP The URI of the secret questionanswer form

/auth/defaultForms/secretQuestions.jsp

LDAP Attribute The attribute that stores thebase64 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 shouldbe used to create the secret questions on a user’s object. It has the following initialization parameters:


numQuestions How many questions must theuser have?

3

questionNamePrefix What is the prefix for attributesrepresenting questions?

If the attributes arequestionName1, questionName2,etc this should be“questionName”

questionValuePrefix What is the prefix for attributesrepresenting question’s answers?

If the attributes are questionVal1,questionVal2, etc this should be“questionVal”

chainName The name of the authenticationchain that secret questions areconfigured on

Portal Login

Login ServiceThe Login Service mechanism provides a way to give users a choice in how they login. This is useful insituations where the user could have multiple tokens and different levels of authentication. For instance,


96

in a scenario where a user might be able to use 2-factor authentication when they have a token or a singlefactor when they don't.

The way the login service works is it redirects the user to another Application URL for authentication. Oncethe chain for that application URL is completed the user is re-directed back to the original request (withpost 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.CompleteLoginfilter. This will complete the login process.

MechanismThere are no mechanism level options.

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


Login JSP The URI of the login methodselect page

/auth/forms/chooseLogin.jsp

"Remember Decision" CookieName

The name of the cookie to storethe user's decision to keep theuser's decision to save the choice.

LoginChoice

"Remember Decision" CookieDays Valid

The number of days the cookiethat determines if the user wants toremember their login choice willbe 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:


Label Descriptive name for the loginchoice

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


97

MechanismThere are no mechanism level configuration options.

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


Realm Name The name of the realm to respondwith to failed authenticationattempts

MyRealm

Scope An optional attribute that providesadditional context to the RealmName

urn:myscope:myval

Encryption Key A key from the Last Mile key listused to encrypt and decrypt thelast mile token

mykey

Just-In-Time ProvisioningThis mechanism executes a workflow on the currently logged in user.


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


User Name Attribute The name of the attribute usedto identify the user on the user'sobject.

uid

Workflow Name The workflow to execute MyWorkflow

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

To enhance security this mechanism uses three levels of security:


98

Layer Description

AES-256 Encryption The cookie is encrypted using industry standardAES with 256 bit keys

Client IP Address The user's IP address is stored in the cookie, if theIP of the source of a request doesn't match this valuethe cookie is rejected

Optional - SSL Session ID The session id for the current SSL session can bestored as an extra layer of validation

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

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

MechanismThere are no configuration options on the mechanism.

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


Cookie Name The name of the cookie togenerate. Scoping informationis taken from the application'scookie configuration.

loginCookie

Include SSL Session ID? If checked, the user's ssl sessionid is included in the validationprocess.

checked

Time to Live (milliseconds) The number of millisecondsbefore this cookie needs to be re-generated. Defaults to 4 hours.

14400000

Encryption Key Alias The name of the Last Mile Keyfrom the Certificate Managementscreen to use to encrypt the cookie

Time Based One Time PasswordThis mechanism provides a one-time-password using the OATH time based protocol (sometimesreferred to as Google Authenticator). This mechanism needs to be paired with a workflow that containsthe com.tremolosecurity.provisioning.customTasks.CreateOTPKey custom task forsetting the user's encrypted key.



99

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


Form URI The path to the form for enteringthe one-time-password

/auth/forms/otp.jsp

Encryption Key Name The last mile key used to encryptthe user's token

MyWorkflow

Full Encryption Key Name The full name to be used in theencryptionKey property ofthecom.tremolosecurity.provisioning.customTasks.CreateOTPKeyprovisioning task

Based on the Encryption KeyName

Base64 Encoded Encryption Key The base64 value of the key usedfor encrypting the user's token,useful for applications that willdisplay the token or a QR Code forimporting the token into a mobiledevice

Directory Attribute Name The name of the attribute toretreive the user's token from,should be the same as theattributeName property ofthecom.tremolosecurity.provisioning.customTasks.CreateOTPKeycustom task

l

Valid 30 Second Windows Number of valid 30 secondwindows that a token shouldremain usable for cases whereclocks aren't exactly in-sync orto forgive codes entered over awindows switch

3

100

Chapter 12. FiltersUnison provides the capability to make changes to each request. For an identity provider this typicallymeans adding additional attributes to an assertion. For a reverse proxy, this generally means adding headersor executing workflows based on the user's choices. The below filters come standard in Unison.

Create an attribute from a group membershipThis filter allows for an attribute to be added to an assertion if the user is a member of a particular group inyour directory. This could be useful when providing service providers entitlement information. This filtercan be added multiple times and if the user is a member of the specified group AND the attribute alreadyexists the specified value is added to the attribute, it does not replace it.


Group DN The full LDAP DN of the groupbeing checked. This DN must bethe mapped DN from inside ofUnison. The “…” button next tothis option may be used to searchfor the group based on it’s CN.

Cn=mygroup,cn=Users,ou=MyEnterprise,O=Tremolo

Attribute Name The name of the attribute to createif the user is a member of thisgroup

Role

Attribute Value The value to be added or set if theuser is a member of the specifiedgroup

Users

Create an attribute from a base DNThis filter allows for an attribute to be added to an assertion if the user's DN in the virtual directory is achild 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 attributealready exists the specified value is added to the attribute, it does not replace it.


Base DN The full LDAP DN of the basebeing checked. This DN must bethe mapped DN from inside ofUnison. The “…” button next tothis option may be used to find it.

cn=Users,ou=MyEnterprise,O=Tremolo

Attribute Name The name of the attribute to createif the user is a member of thisgroup

Role

Attribute Value The value to be added or set if theuser is a member of the specifiedgroup

Users

Filters

101

Login TestThis filter will echo the attributes of the currently logged in user. It's a convinient way to test the loginprocess without having to have an application to proxy or an identity provider configured. Configure thisfilter on a URL and that URL will use this filter to provide content back to the web browser. No filtersconfigured after this filter are executed.


JSP URI The path of the JSP page thatwill show the logged in user'sinformation

/auth/forms/loginTest.jsp

Logout URI The path of the logout URI /logout

Create XForward HeadersThe X-Forward headers (X-Forwarded-For, X-Forwarded-Host and X-Forwarded-Proto), are a defactostandard for supplying down-stream servers with information as a reverse proxy would see it. This filterwill create these attributes for use as headers.


Create Standard Headers Determine if plean HTTP Headersor Secure Headers should beused. If checked, standard headersare created, if not checked thenattributes are created with thesame names that can be added asSecure Headers to the LastMilefilter.

true

Create AWS Role AttributeThis filter is designed to be added to an identity provider for the AWS console to create an attribute thatis acceptable to AWS out of human readable role names.


Source Attribute Name The name of an attribute on theuser object that contains all ofthe names of roles to be includedin the assertion. NOTE: eachrole should exist in IAM or theauthentication will fail.

roleNames

AWS Account Number The AWS account number thatshould be included in the rolemapping.

1234567

Identity Provider Name The name of the identity providerin your AWS IAM configurationto bind to.

MyIdp

Filters

102

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

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


Workflow The name of the workflow toexecute

Create Shadow Users

Username Attribute The name of the attribute on theuser object used to identify theuser

Uid

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


Proxy Request If set to “true” the request iscontinued to be proxied. If set tofalse, the request completes

True/False

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

Remote Basic AuthenticationThis filter will authenticate users by executing a basic authentication request against a remote server usingthe Authorization header inbound from the browser. The filter will then set the user’s context. Its designedto work with an application’s session disabled.


Realm Name The name of the realm onthe remote web server theauthentication is against

My Realm

URL The url to use to test theauthentication

https://www.mydomain.com/auth

Filters

103

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


Encryption Key The key used to encrypt the lastmile header

Header-encryption-key

Specify New Encryption Key If the key doesn’t exist, specifyingthis field will create a new key

Header-encryption-key

Encryption Key Password The password used to unlock thekey by the last mile system

Time Scew The number of milliseconds thatthe last mile token is valid

1000

Header Name The name of the header tremooHeader

Attribute Mapping Specify mappings from userattributes to headers, also choosewhich attribute is used to identifythe user and which to identifyroles (optional)

Create Headers Specifies if the last mile systemshould create headers in theapplication

True/False

Keystore Path The relative path to the keystore WEB-INF/lastmile.jks

Ignore URI A uri that is ignored by thelast mile system, often used tounprotect web services

/path/to/ws

Filter Type The type of last mile system to beused

Check Shadow AccountWhen integrating with an AD environment that is used for both shadow accounts and real accounts thisfilter is used to transition from real account in an external forest to a shadow account.


Local UPN Suffix The UPN suffix for AD foreststoring shadow accounts

shadows.ad.local

New UPN Source Attribute The attribute that’s used for thesource of the shadow account’sUPN

Mail

Flag Attribute Name Attribute to store a flag value if theaccount is to be a shadow account

Description

Flag Attribute Value Flag value if the user will becomea shadow account

shadow

Filters

104

Basic AuthenticationThis filter is used in conjunction with an application with a disabled session. It will perform a basicauthentication against the internal virtual directory.


Realm Name The name of the realm to bepresented to the browser

My Realm

Username Attribute The name of the attribute to use tolookup the user

Uid

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

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

Decode Form Parameter NameThis filter will decode any form parameters that are already URLEncoded. This is useful for applicationslike Drupal that relies on form parameters that were URL encoded.

Last Mile JSON IdPUsed inconjunction with the OAuth2 Last Mile Bearer Token authentication scheme, this filter will createan HTML page with an OAuth 2 access token inside of a div called "json".


Encryption Alias Last Mile encryption key oauth2-key

Seconds Valid The number of seconds thereturned token is valid

6000

Scew Seconds The number of seconds to adjustfor if clocks are not synced

300

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

Filters

105


Pre-Auth URL The fully qualified domain name(FQDN) and uri of the URLin Unison configured with aLastMile filter configured.

https://mysite.company.com/myapp/login

Post SAML? Determines if a SAML assertionshould be generated and postedto the Pre-Auth URL. Ifchecked an Identity ProviderMUST be created to supplythe configuration information togenerate the assertion.

true

IdP Name The name of the identityprovider that has the configurationinformation for generating theassertion

MyIdP

Issuer Host The host name that should be inthe issuer

idp.mycompany.com

Issuer Port If the issuer is on a non-standardport, it can be specified here. Thisfield is optional

8443

Issuer SSL If the issuer should be https(checked) or http (not checked)

checked

Create attribute from group membershipsThis filter will create an attribute with the names of groups the user is a member of. An optional regularexpression can be used to specify only a certain number of groups.


Base The base in the virtual directory tobegin searching for groups.

o=Tremolo

Attribute Name Name of the attribute to create roles

Optional Pattern A regular expression to filter outgroup memberships

groups-(.*)

Group Number from Pattern If a pattern is specified, the groupfrom that pattern to add to theattribute

1

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


Support Cookie Name RegularExpressions

If checked, the values tofilter are treated as Javaregular expressions. (http://

Unchecked

Filters

106


docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html)

Cookies to Filter List of cookie names (or regularexpressions) to filter

SomeCookieName

107

Chapter 13. Identity ProviderConfiguration

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

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

Access URLsThere are three primary URLs for accessing the identity provider:

URL Type Function Format Example

HTTP-POSTAuthentication Requests

Accepts authenticationrequests as an HTTP Post

https://host:port/auth/idp/IDPNAME/httpPostWhere IDPNAME is thename of the identityprovider under the APPSsystem

https://host:port/auth/idp/saml2/httpPost

HTTP-RedirectAuthentication Requests

Accepts authenticationrequests as an HTTP Get

https://host:port/auth/idp/IDPNAME/httpRedirect WhereIDPNAME is the nameof the identity providerunder the APPS system

https://host:port/auth/idp/saml2/httpRedirect

Identity providerinitiated federation

Start a federation withoutan authentication requestfrom the SP

https://host:port/auth/idp/IDPNAME/idpInit?sp=TRUST whereIDPNAME is the nameof the identity providerunder the APPS systemand TRUST is the nameof the trust

https://host:port/auth/idp/saml2/idpInit?sp=https://saml2.salesforce.com

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


Signature Key The key used for verifyingsigned authentication requests.The key should be listed under the

Idp-cert-key

Identity Provider Configuration

108


“Signature and Encryption Keys”in Certs

Encryption Key The key used for encryptingauthentication requests. The keyshould be listed under the“Signature and Encryption Keys”in Certs

Require Signed AuthenticationRequests

Must the identity providerrequire signed authenticationrequests? If not checked, signedauthentication requests will stillbe accepted and verified.

Require Signed MetaData Must the identity provider requiresigned metadata? If not checked,signed metadata will still beaccepted and validated.

Generating Metadata

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

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


HTTP Post Response URL The URL used to post theresponse to. This is optional ifincluded in the authenticationrequest.

https://www.mysp.com/saml2/sp/post

SP Signature Key The key used to sign the responseor assertion

SP Encryption Key The key used to encrypt assertions

Sign Assertions Determine if the assertionshould be signed. If encryptingassertions, its expected that theassertion will be signed.

Encrypt Assertions Should the assertion beencrypted?

Sign Responses Should the entire response(including the assertion)

Default NameID Format If no nameid format is specified inthe authentication request or in theidp initiated request this setting

urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

Identity Provider Configuration

109


specifies which attribute to use toidentify the user

Default Authentication ContextClass

If no authentication class contextreference is specified in theauthentication request or in the idpinitiated request specifies how toauthenticate 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 ismapped to a an authentication chain. The default context class ref defined above MUST be included inthis 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 thisfield. 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 betrusted in the Certs system.


Import Meta Data Check this box if you planto upload metadata. Otherwisevalidation will fail. NOTE:uploading new metadata willoverwrite the trust configuration.

Checked

Option 1 - Import from URL If your service provider haspublished its SAML2 metadata,the url can be put into this optionand 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 filecontaining the metadata choosethis option

C:\Downloads\www.tremolosecurity.com-saml2-metadata.xml

Option 3 - Copy and Paste MetaData

You may copy and paste thetext of the metadata file into thisoption

meta data contents

110

Chapter 14. Custom AuthorizationRules

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

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

Manager AuthorizationClass Name - com.tremolosecurity.provisioning.az.ManagerAuthorization

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


Number of Levels (Start with 1) Use this to define who "distant"of a manager is authorized.For instance to allow the user'smanager's manager to performthe authorization specify "2".This allows for escalations to beprocessed with multiple tiers ofmanagers.

1

Manager Attribute Name The name of the attribute on theuser's directory object that will tellUnison who their manager is.

manager

Is Manager Attribute a DN? If checked, Unison will assumethat the attribute defined in"Manager Attribute Name" is thedistinguished name of the user'smanager. If not checked, thenUnison will use a filter built fromthe "User Identifier Attribute"from the Approvals screen and thevalue of the "Manager AttributeName"

Checked

Allow Lower Level Managers toApprove?

Used when the number of levelsis greater then one, allowingall the managers between theuser and the current step toapprove. For instance of anapproval is escalated to a user'smanager's manager checking thisoption will allow both theuser's manager AND the user'smanager's manager to approve.

Checked

111

Chapter 15. Provisioning TargetsThis section details the pre-built provisioning targets that are available for Unison. In addition to thesetargets, custom targets may be created. Consult the Unison SDK for instructions on how to create a customtarget.

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











Note that if the source attribute is TREMOLO_USER_ID then the user object’s id is used. WhenTREMOLO_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 theconnection, it will be displayed.

LDAP DirectoryThis target provisions identities to a generic LDAPv3 directory.


Name A descriptive name for the target LDAP

User Object Class The object class for new userobjects

inetOrgPerson

Host Host for the ldap server ldap.enterprise.com

Port The port to connect to 636

Administrator DN A DN for a user withadministrator rights to create andupdate accounts

Cn=Directory Manager

Administrator Password Credential passwords

New User DN Pattern The DN pattern for new users withuser attributes in ${}

uid=${uid},ou=users,dc=domain,dc=com

Provisioning Targets

112


Search Base The base that should be used forsearching for users and groups

Dc=domain,dc=com

Use SSL If set to true SSL is used for theconnection

True/False

UserID Attribute The name of the attribute used toidentify the user

Uid

Maximum Connections Maximum number of connectionsto the directory

10

Maximum Sessions perConnection

Maximum number of individualoperations per connection

10

Manage Groups for ExternalUsers

If checked, this directory is ableto store users that are NOT storedin the directory. For instance iflinked to an Active Directory viathe internal virtual directory. If auser is not found in the target, thevirtual directory is searched fromo=Tremolo using the user's ID.ONLY group memberships willbe provisionined and they'll beprovisioned using the DN fromthe virtual directory.

Checked

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


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 willbe added to each RESTful request.If false, then the URI of the serviceapi MUST be ignored by the lastmile system

True/False

Last Mile Key Alias If “Use Last Mile Security?” istrue, the key to use to generate theheader


113

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


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 withadministrator rights to create andupdate accounts

Cn=Directory Manager

Administrator Password Credential passwords

New User DN Pattern The DN pattern for new users withuser attributes in ${}

uid=${uid},ou=users,dc=domain,dc=com

Search Base The base that should be used forsearching for users and groups

Dc=domain,dc=com

Create Shadow Accounts If set to true a shadow account iscreated. A shadow account is justlike a regular account except thepassword is randomly generated.

True/False

Use SSL If set to true SSL is used for theconnection

True/False

UserID Attribute The name of the attribute used toidentify the user

Uid

Maximum Connections Maximum number of connectionsto the directory

10

Maximum Sessions perConnection

Maximum number of individualoperations per connection

10

Relational DatabaseThis target can be used to create users and update their attributes in a relational database. The target caneither use a generic model or a custom model can be updated by implementing a specific interface. Forinstructions on how to manage a custom database, see the Unison SDK. Note that this target does NOTset password.


114

Figure 1 – Group Management Mode: None

Figure 2 – Group Management Mode: Many to Many


115

Figure 3 - Group Management Mode: One to Many


Name A descriptive name for the target MyDB




Begin Escape Character(Optional)

An optional character used toescape field names in SQL

`

End Escape Character (Optional) An optional character used toescape field names in SQL

`

User Name The user for connecting to thedatabase



10


1000

Validation Query A query that will be used to test ifa connection is active on checkout

SELECT 1

Users Table The name of the table that storesthe user objects

Users


116


User SQL If a custom group management isused this option is used to specifyhow users are looked up. Use %Sto specify the fields being lookedup, %I for the user’s numeric IDand %L for the user’s login

SELECT %S FROM usersWHERE login=%L

User Table Primary Key Field The name of the column in theuser table that is the primary key

Id

Group Management Mode Determines how to manage therelationship between users andgroups:

None – No group information isstored ManyToMany – Assumesthere is a table of users, table ofgroups and a table that links themOneToMany – Assumes there’s atable of users with a one-to-manyrelationship with a groups tableCustom – Use a custom class toupdate user attributes and groupmemberships. See the SDK forimplementation details

Group Table Name The name of the table that storesgroup information

Groups

Group SQL If a custom group managementis used this option is used tospecify how groups are lookedup. Use %S to specify the fieldsbeing looked up, %I for the user’snumeric ID and %L for the user’slogin

SELECT %S FROMwp_usermeta INNER JOIN usersONusers.id=wp_usermeta.user_idANDwp_usermeta.meta_key='wp_capabilities'where users.id=%I

Group Table Primary Key The name of the primary key ofthe group table

Id

Group Table Name Field The field start stores the name ofthe group

name

Group Link Table Name The name of the table used to linkusers and groups

LinkTable

Group Link User Field The name of the column in thelink table that maps to the user’sprimary key

User

Group Link Group Field The name of the column in thelink table that maps to the group’sprimary key

Groups

Custom Provider The class name for a customprovider. See the SDK for how toimplement a custom provider

Amazon SimpleDBIf utilized as the basis for user data in the cloud this target can be used in a workflow to populate thedatabase.


117


Name A descriptive name for the target MyAmazonDB

User Domain Domain for storing userinformation

Users

Group Domain Domain for storing groupinformation

Groups

Access Key Access Key

Secret Key Secret Key

User Identifier Attribute Name The attribute that stores the userid uid

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


Name A descriptive name for the target MyUnison

UID Attribute Name The attribute name for the useridentifier

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 tocreate new users

Delete User Workflow Name The name of the workflow todelete users

Set User Password WorkflowName

The name of the workflow to set auser’s password

Synchronize User WorkflowName

The name of the workflow tosynchronize a user

SugarCRMThe SugarCRM target can be used to update contacts inside of SugarCRM. It does not, at present supportthe creating of users.


Name A descriptive name for the target SugarCRM

URL The SugarCRM web servicesURL

http://sugarcrm.domain.com/sugarcrm/service/v2/rest.php

Admin User Administrative username

Admin Password The user’s password


118

SharePoint GroupsThis target allows for a user's groups in SharePoint to be managed by Unison. For Just-In-Timeprovisioning 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 intoSharePoint

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

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


Name A descriptive name for the target SharePoint

Authentication to SharePointMode

Mechanism for authentication toSharePoint. For JIT provisioningyou must use Unison Last Mile.

Unison Last Mile or NTLM

SharePoint Users and GroupsService URL

The URL, from Unison'sperspective, of the web servicesurl

http://sharepoint-internal.domain.com/_vti_bin/usergroup.asmx

Administrator UPN Full user principal name of anadministrative user

[email protected](when using NTLM this shouldbe in the form domain\user, ieDOMAIN\Administrator)

Administrator Password Password for NTLM access

Multi Site Tell Unison if all subsites are amember of the root site or aredistinct sites with their own webservices endpoints

Unchecked

Sites List of paths for each site. Forinstance "/", "/MySite" withoutquotes

Reliable Provisioning ProviderThis provider wraps another target to ensure that the operations performed are "reliable" by pushing allrequests to the provider through an embedded message queue. The queue is connected to a relationaldatabase that provides fault tollerence and high availability. When using this provider, note that theworkflow will continue to process so the next task will execute.


119


Name A descriptive name for the target Queue

Driver The JDBC Driver for the database com.driver.Driver

URL The JDBC URL for the database jdbc:sql://server

User Name The name of the user to connect tothe database

activemq

Password Password for user


10

Queue Name The name of the queue to storemessages from this provider in

MyQueue

Provisioning Target The target to call when messagesare received

SomeTarget

Message Encryption Key The name of the Last Mike keyto use to encrypt messages beforethey are placed on the queue

SomeKey

120

Chapter 16. Provisioning CustomTasks

This section details the pre-built provisioning custom tasks. These tasks can be used in your deploymentswithout 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 numberof name/value pairs. A single configuration option can have multiple values by listing the name/value pairfor each value.

Filter GroupsClass 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 havethe groups "Admin","Developer" and "User" but the target only has the groups "Admin" and "User" thistask can be used to filter out "Developer". This way no "rogue" groups are presented to a target. This taskshould be used inside of a mapping task to make sure that other tasks are not effected.


name A group name that should passthrough this filter, case sensitiveand can be listed multiple times

User

Load User AttributesClass 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 isonly being called with a user identifier or a subset of attributes and additional attributes are needed forreporting or decision making.


name An attribute name to load,case sensitive and can be listedmultiple times

sn

nameAttr The name of the attribute thatidentifies the user in the virtualdirectory

mail

Map User GroupsClass Name - com.tremolosecurity.provisioning.customTasks.MapGroups

The Map User Groups task will map group names from a "global" name to a target specific name. Forinstance if there is a generic group called "Administrator" but the target stores administrators in the group

Provisioning Custom Tasks

121

"SYS_ADMINS" this task can be used to create that mapping. It should be deployed inside of a mappingto make sure that global groups are not effected.


map A mapping of target fromsource. To map Admins -->SYS_ADMIN the value shouldbe SYS_ADMIN=Admins. Thisattribute can be mapped multipletimes.

SYS_ADMIN=Admins

Complete Registration / Set User's PasswordClass 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 addressneeds to be verified. It triggers a password reset through the password reset authenticaiton mechanism. Inorder for this task to work, it MUST have a password reset authentication mechanism configured wherethe workflow is configured.


mechName The name of the password resetmechanism as defined in the AuthMechs section.

PasswordReset

Set Groups from AttributeClass 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 buildinggeneric workflows.


attributeName The name of the attribute to getthe group values from. Once thevalues are added, the attribute isremoved from the user.

roles

Ignore GroupsClass 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 amember of the named group in named target the user's provisioning object is also given the group. Thisway when the synchronization occurs the group is ignored.


groupName The name of the group to ignore Administrators

targetName The name of the provisioningtarget to search

adUsers


122

Load GroupsClass 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 canalso 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.


nameAttr The attribute name to search foron the user's account

mail

inverse If set to true, only loads the groupsfrom the virtual directory that theuser's object is NOT already amember of

false

Just-In-Time Create GroupsClass 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 isuseful when using a database to store group information in a cloud situation where the list of groups isunknown at deployment time. It is used in conjunction with a database provisioning target that has a grouptable defined.


targetName The name of a databaseprovisioning taget

jitdb

Print User InfoClass Name - com.tremolosecurity.provisioning.customTasks.PrintUserInfo

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


message An optional label to add to the logmessage

"After approval"

Create OTP KeyClass Name - com.tremolosecurity.provisioning.customTasks.CreateOTPKey

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


attributeName The name of the attribute to storethe token in

l


123


hostName The host name of the service,used for identification in theauthenticator

www.someplace.com

encryptionKey The name of the key used toencrypt and decrypt the user'stoken. Can be obtained from theTOTP Authentication Mechanismon your Authentication Chain.

lastmile-enc-totp

124

Chapter 17. Message ListenersThis section details the pre-built message listeners. These tasks can be used in your deployments withoutchange. 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 numberof name/value pairs. A single configuration option can have multiple values by listing the name/value pairfor each value.

Update Approvals AuthorizationsClass Name - com.tremolosecurity.provisioning.listeners.UpdateApprovalAZListener

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

Automatically Fail Open ApprovalsClass Name - com.tremolosecurity.provisioning.listeners.AutoFailApprovalListener

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

125

Chapter 18. JobsThis 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 ofname/value pairs. A single configuration option can have multiple values by listing the name/value pairfor each value.

Update AuthorizationsClass Name - com.tremolosecurity.provisioning.scheduler.jobs.UpdateApprovalAz

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


Queue Name The name of the queue theUpdate Approvals Authorizationsmessage listener is configured on

MyQueue

Open Approvals ReminderClass Name - com.tremolosecurity.provisioning.scheduler.jobs.RemindApprovers

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


SQL The SQL used on the auditdatabase to determine whichapprovers to send reminders to.This SQL must:

1. Have a single parameter thatrepresents the number of daysa request for approval is open

2. Returns:

a. daysOpen - number of daysthe request has been open

b. label - the label of theworkflow being processed

c. mail - The email address ofthe user to be reminded

For SQL Server: select * from(SELECTdatediff(DAY,approvals.createTS,GETDATE())as daysOpen ,approvals.label,mailFROM approvals INNERJOIN allowedApprovers onapprovals.id=allowedApprovers.approvalINNER JOIN approvers onapprovers.id=allowedApprovers.approverWHERE approvals.approvedTSIS NULL ) X where daysOpen>= ?

Jobs

126


Message to send The template for the messageto send to the approvers. Use%L to represent the label of theworkflow that is open and %D torepresent the number of days open

The request %L has been open for%D days, please login to act onthis request

Number of days open beforesending a reminder

The number of days an approvalrequest should be open beforesending a reminder

7

Automatically Fail Open ApprovalsClass 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 jobtakes these approval requests and puts them on a queue to be picked up by the Automatically Fail OpenApprovals listener.


Queue Name The name of the queue to addapproval requests to

autoFailures

Failure Reason A message to be provided to usersas to why the request failed

Your request was not approvedwithin one week

Auto Fail User The name of the user whom allfailures are assigned, must bethe value of the user identifierattribute configured on the auditdatabase

failUser

127

Chapter 19. High Availability

OverviewUnison can provide services in a HA, or High Availability, environment. This ensures that if there isnetwork 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 HAenvironment, 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 UnisonUnison can be clustered such that a single configuration change is propagated out to all the members ofthe cluster. Unison has two potential models for clustering: A master/slave model, where a single serveris the configuration "master" while multiple "slaves" consume configuration data or a file system modelwhere Unison listens for changes to certain files to trigger a reload. When a configuration change is madeto 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 forsecuring 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 andsetting 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

High Availability

128

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

Peer Mode

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

High Availability

129

Client / Server Mode

High Availability

130

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

Load Balancing In-bound ConnectionsUnison handles two types of in-bound connections: LDAP(S) and HTTP(S). Since LDAP is a statefulprotocol, once a connection is established with a Unison instance the client will continue to work with thatconnection. For this reason LDAP connections can be loadbalanced either via a DNS server, reverse proxyor when running "beside" Unison. HTTP(S) connections are stateless, each individual request requires anew network connection which may be routed to any of the Unison servers in the cluster. Since Unisonhas an internal session, HTTP requests MUST be loadbalanced in "sticky" mode. This means that allconnections from a client MUST always go to the same server.

Load Balancing Out-bound ConnectionsUnison relies on external load balancers for lod balancing outbound connections. For LDAP serverseither DNS, reverse proxy or running "beside" the LDAP servers is supported. The same is true of HTTPconnections, however that is dependent on individual applications.

Unison 1.0 - Tremolo Security · Alfresco ECM ... High Availability ... Clustering Unison ...

Documents

Transcript of Unison 1.0 - Tremolo Security · Alfresco ECM ... High Availability ... Clustering Unison ...