Unison 1.0.5
Administration and Configuration
Unison 1.0.5: Administration and ConfigurationCopyright © 2012 - 2014 Tremolo Security Inc.
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 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 ............................................................................................ 26
Logs ........................................................................................................................ 265. First Time setup ........................................................................................................... 27
Initial Setup .............................................................................................................. 27Tremolo Unison First Time Setup ........................................................................ 27Upload Tremolo Server Package .......................................................................... 27Manual Configuration ....................................................................................... 27
6. Server Setup Wizard .................................................................................................... 29Proxy First Time Setup .............................................................................................. 29
7. Identity Provider Wizard .............................................................................................. 30Introduction .............................................................................................................. 30Welcome .................................................................................................................. 30Identity Provider Basic Information .............................................................................. 30Identity Provider Signing Certificate ............................................................................. 30Identity Provider Encryption Certificate ......................................................................... 31Create New Directory? ............................................................................................... 31Directory Information ................................................................................................. 32Directory Configuration Validation ............................................................................... 32Identity Provider Attributes ......................................................................................... 32SP Meta Data Import ................................................................................................. 33SP Meta Data Import Verification ................................................................................ 33Next Steps ................................................................................................................ 33
8. Application Wizard ...................................................................................................... 34Welcome .................................................................................................................. 34Application Basic Information ..................................................................................... 34Create New Directory? ............................................................................................... 34Directory Information ................................................................................................. 34
Unison 1.0.5
iv
Directory Configuration Validation ............................................................................... 35Authentication Type ................................................................................................... 35Just-In-Time Provisioning ........................................................................................... 35Provisioning Target .................................................................................................... 35Target Configuration Validation ................................................................................... 36Just-In-Time Provisioning ........................................................................................... 36
Attribute Mappings ............................................................................................ 36Group Mappings ............................................................................................... 36
Last Mile Configuration ............................................................................................. 37None ............................................................................................................... 37Secure Last Mile ............................................................................................... 37Header ............................................................................................................. 37
9. Administration Reference .............................................................................................. 38Servers ..................................................................................................................... 38
Manage Proxy ................................................................................................... 38Manage Virtual Directory ................................................................................... 40Manage Web Services ........................................................................................ 41Generate PaaS Package ...................................................................................... 43Manage Admin Service ...................................................................................... 43Manage Certificates ........................................................................................... 46Admin Service Directories .................................................................................. 49
Access ..................................................................................................................... 49Find Users ........................................................................................................ 49Applications ..................................................................................................... 49User Directories ................................................................................................ 53Authentication Mechanisms ................................................................................. 54Authentication Chains ........................................................................................ 54Result Groups ................................................................................................... 55
Provisioning ............................................................................................................. 56Provisioning Targets .......................................................................................... 56Workflows ........................................................................................................ 57Organizations .................................................................................................... 57Workflow Tasks ................................................................................................ 59Approvals ....................................................................................................... 63Database Schema ............................................................................................. 64
10. Directory Configuration ................................................................................................. 69Normalization and DN Mapping .................................................................................. 69Testing Configurations ............................................................................................... 69Inserts ...................................................................................................................... 69
Insert ............................................................................................................... 69Directory Types ........................................................................................................ 70
Active Directory ................................................................................................ 70LDAP Directory ................................................................................................ 71Admin ............................................................................................................. 72Amazon SimpleDB ............................................................................................ 72BasicDB .......................................................................................................... 73Remote Schema ................................................................................................ 75NoOp .............................................................................................................. 75
Insert Reference Guide ............................................................................................... 75External Group Members .................................................................................... 76Corrupt ObjectGUID .......................................................................................... 76Create UPN ...................................................................................................... 76UUID To Text .................................................................................................. 76
11. Authentication Mechanisms ........................................................................................... 77
Unison 1.0.5
v
Form Login .............................................................................................................. 77Mechanism ....................................................................................................... 77Chain ............................................................................................................... 77
SAML2 .................................................................................................................... 77Mechanism ....................................................................................................... 77Chain ............................................................................................................... 77
Anonymous .............................................................................................................. 80Mechanism ....................................................................................................... 80Chain ............................................................................................................... 80
Basic ....................................................................................................................... 80Mechanism ....................................................................................................... 80Chain ............................................................................................................... 80
IWA ........................................................................................................................ 81Mechanism ....................................................................................................... 81Chain ............................................................................................................... 81
SSL Certificate Authentication ..................................................................................... 81Mechanism ....................................................................................................... 81Chain ............................................................................................................... 82
Username Only Login ................................................................................................ 83Mechanism ....................................................................................................... 83Chain ............................................................................................................... 83
Banner Acknowledge ................................................................................................. 83Mechanism ....................................................................................................... 83Chain ............................................................................................................... 83
SMS Token Authentication ...................................................................................... 84Mechanism ....................................................................................................... 84Chain ............................................................................................................. 84
Secret Question Authentication ................................................................................ 84Mechanism ....................................................................................................... 84Chain ............................................................................................................. 85
Login Service ......................................................................................................... 85Mechanism ....................................................................................................... 85Chain ............................................................................................................. 86
OAuth2 Bearer - Last Mile ...................................................................................... 86Mechanism ....................................................................................................... 86Chain ............................................................................................................. 86
Just-In-Time Provisioning ........................................................................................ 87Mechanism ....................................................................................................... 87Chain ............................................................................................................. 87
Persistent Cookie .................................................................................................... 87Mechanism ....................................................................................................... 88Chain ............................................................................................................. 88
12. Filters ......................................................................................................................... 89Create an attribute from a group membership ................................................................. 89Create an attribute from a base DN .............................................................................. 89Login Test ................................................................................................................ 90Create XForward Headers ........................................................................................... 90Stop Processing ...................................................................................................... 90Execute Workflow ..................................................................................................... 90User to JSON ......................................................................................................... 90Check Authorizations .............................................................................................. 91Remote Basic Authentication ....................................................................................... 91Last Mile Security .................................................................................................. 91Check Shadow Account ........................................................................................... 92
Unison 1.0.5
vi
Basic Authentication ............................................................................................... 92Anonymous Authentication ...................................................................................... 92Hide Cookies from Client ........................................................................................... 92Decode Form Parameter Name .................................................................................... 93Last Mile JSON IdP ............................................................................................... 93Pre-Authentication .................................................................................................. 93Create attribute from group memberships ................................................................ 94Cookie Filter ............................................................................................................ 94
13. Identity Provider Configuration ...................................................................................... 95SAML2 .................................................................................................................... 95
Access URLs .................................................................................................... 95Global Configuration .......................................................................................... 95Trust ............................................................................................................... 96
14. Provisioning Targets ..................................................................................................... 98LDAP Directory ........................................................................................................ 98Alfresco ECM ......................................................................................................... 99Active Directory ...................................................................................................... 99Relational Database ................................................................................................. 100Amazon SimpleDB ................................................................................................. 103Tremolo Unison ..................................................................................................... 103SugarCRM ............................................................................................................ 104SharePoint Groups .................................................................................................. 104
Multi Site Integration ....................................................................................... 104Reliable Provisioning Provider .................................................................................. 105
15. Provisioning Custom Tasks .......................................................................................... 106Filter Groups ........................................................................................................... 106Load User Attributes ................................................................................................ 106Map User Groups .................................................................................................... 106Complete Registration / Set User's Password ................................................................ 107Set Groups from Attribute ......................................................................................... 107Ignore Groups ......................................................................................................... 107Load Groups ........................................................................................................... 108Just-In-Time Create Groups ....................................................................................... 108Print User Info ........................................................................................................ 108
16. High Availability ....................................................................................................... 109Overview ................................................................................................................ 109Clustering Unison .................................................................................................... 109Peer Mode .............................................................................................................. 110Client / Server Mode ................................................................................................ 111Load Balancing In-bound Connections ........................................................................ 112Load Balancing Out-bound Connections ...................................................................... 112
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 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
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
Installing Unison
18
$ ./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.
Tremolo Security Unison Appliance
24
• crluser - Used to maintain certificates and revocation lists
• 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.
Tremolo Security Unison Appliance
25
# /etc/init.d/unison getenv TREMOLO_ROOT = /usr/local/tremolo TREMOLO_HOME = /usr/local/tremolo/tremolo-unison TREMOLO_PROXY_HOME = /usr/local/tremolo/tremolo-unison/apps/proxy TREMOLO_ADMIN_HOME = /usr/local/tremolo/tremolo-unison/apps/tremolo-admin TREMOLO_WS_HOME = /usr/local/tremolo/tremolo-unison/apps/webservices TREMOLO_SSH_KEYS = /usr/local/tremolo/.ssh TREMOLO_ETC = /usr/local/tremolo/etc TREMOLO_CONF = /usr/local/tremolo/conf TREMOLO_SDKS = /usr/local/tremolo/sdks TREMOLO_LOGINS = /usr/local/tremolo/logins TREMOLO_SSL = /usr/local/tremolo/ssl TREMOLO_CERTS = /usr/local/tremolo/ssl/certs TREMOLO_CRLS = /usr/local/tremolo/ssl/crls
* 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
Tremolo Security Unison Appliance
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
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:
/ PRELUDE_HOME /tremolo-prelude/logs
where PRELUDE_HOME is the directory in which Prelude was installed.
27
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
28
• 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.
29
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
30
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:
Option Description Example
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.
Option Description Example
Existing Certificate If using an existing certificate,choose it from this list
Existing Certificate or blank
Name of new Certificate The name of the new certificate.No spaces, will be forced to 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
31
Option Description Example
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
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.
Option Description Example
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
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
Create New Directory?If the IdP requires the integration of a new directory, check the box on this page. Otherwise directoryconfiguration will be skipped.
Identity Provider Wizard
32
Option Description Example
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.
Option Description Example
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.
Option Description Example
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
Identity Provider Wizard
33
Option Description Example
• 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.
Option Description Example
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
34
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.
Option Description Example
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
idp.myenterprise.com
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
idp.myenterprise.com
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.
Option Description Example
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
35
Option Description Example
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.
Option Description Example
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.
Option Description Example
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.
Option Description Example
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
36
Option Description Example
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
Option Description Example
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:
Option Description Example
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
37
Option Description Example
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.
38
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:
Option Description Example
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
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,TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_3DES_EDE_CBC_SHA,
Administration Reference
39
Option Description Example
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:
Option Description Example
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
Administration Reference
40
Option Description Example
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
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.
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
IP Address The ip address of the interfaceUnison will listen on, leave blankfor all interfaces
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:
Option Description Example
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 isthe open port that users see, oftenport 80. This setting is used forcreating redirects.
389
Administration Reference
41
Option Description Example
Secure Port The port that will listen using SSL,leaving blank means there will notbe a secure port
10636
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.
636
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
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.
IP Address The ip address of the interfaceUnison will listen on, leave blankfor all interfaces
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:
Option Description Example
Open Port The port that will listen on “http”,leaving blank means there will notbe an open port
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.
Administration Reference
42
Option Description Example
Secure Port The port that will listen using SSL,leaving blank means there will notbe a secure port
9093
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.
9093
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
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.
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
IP Address The ip address of the interfaceUnison will listen on, leave blankfor all interfaces
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 certificateauthentication. Specify whichcertificate issuers to trust from thisoption.
Administration Reference
43
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
Option Description Example
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:
Option Description Example
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
Administration Reference
44
Option Description Example
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
admin-server
IP Address The ip address of the interfaceUnison will listen on, leave blankfor all interfaces
10.10.10.2
Enabled If checked, the identity provider isrunning
Checked
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
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"
Administration Reference
45
Option Description Example
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
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
Update License
When new licenses are needed this screen is used to update the license. The below fields are available:
Option Description Example
License Key The license key you wereprovided
9bde4b9493afcb89b908c9b9bf824334773f862d1343aa5asdds324
Company Name The EXACT company name asspecified in your license file
My Company
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.
Administration Reference
46
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
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
Administration Reference
47
Use Description Operations
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:
Option Description Example
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.
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).
Administration Reference
48
PKCS12 File
Option Description Example
Alias A descriptive label idp-ssl
PKCS12 File The PKCS12 file to import Path to the PKCS12 file
PKCS12 Alias The name of the key inside of thePKCS12 file
1 by default
Password Password to unlock the PKCS12file
Verify Password Verify the password
Individual Files
Option Description Example
Alias A descriptive label idp-ssl
Key File (PEM or DER) Either a binary or base64 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:
• 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.
Administration Reference
49
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 Directories
This 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.
Access
Find Users
The 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.
Applications
Unison organizes user facing URLs into "Applications". An application can be either a "User Application"or an "Identity Provider". Both are configured in the same way with the same screens. The 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
Administration Reference
50
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:
Option Description Example
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
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.
Administration Reference
51
Option Description Example
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.
Option Description Example
URI The URI to match on /myapp
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
Administration Reference
52
Option Description Example
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:
Option Description Example
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
Administration Reference
53
Source Type Source Target Example
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 DirectoriesThis 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.
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.
Option Description Example
Name A descriptive name for this insert myinsert
Class Name The Java class name for the insert com.tremolosecurity.insert.MyInser
• Add Property - Adds a new property to the insert
• Rmove - Removes the specific property
Administration Reference
54
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:
Option Description Example
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
When adding a custom mechanism, properties can be specified by clicking on "Add Property"
Authentication ChainsAn 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:
Option Description Example
Name A descriptive label IWA Login
Administration Reference
55
Option Description Example
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:
Option Description Example
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
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
Administration Reference
56
Type Direction Description Value
Redirect outbound Instructs the user’sbrowser to go to anotherpage
value
Each result can have one of three sources:
Option Description Example
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
Option Description Example
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
Value For header and cookie results, aname=value. For redirects, the urlto be redirected to
See above table for examples
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:
Source Type Description Source 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
Administration Reference
57
Source Type Description Source Example
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
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
When working with the current level in a workflow, the associated task will be highlighted in white.
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. By
Administration Reference
58
creating organizations users can navigate through a tree to find the workflow that they need. In addition,organizations provide a mechanism to authorize users to be able to request certain workflows. For 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.
Navigating Organizations
The Organizations screen shows all organizations, with children organizations indented beneath theirparent. To navigate to an organization, click on its name.
Organization Data
Option 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.
Option Description Example
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.
Administration Reference
59
Delete Organization and Children
Deletes the currently selected organization and all children organizations.
Move into Parent Organization
Moves the currently selected organization and all children organizations into its grand parent organization.
Move Up
Moves the currently selected organization up in the ordered list of children for the selected organization'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.
Workflow Tasks
Provision to Target
This task is used to push user data to a provisioning target. This task type has the following options:
Option Description Example
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.
Administration Reference
60
Option Description Example
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.
Option Description Example
Name The name of the group to add,must match the name of the groupin a downstream target.
MyGroup
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.
Option Description Example
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.
Option Description Example
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.
Option Description Example
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
Option Description Example
Name The attribute to add MyAttribute
Administration Reference
61
Option Description Example
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.
Option Description Example
Strict Mapping If checked, the user object used forsub tasks will only have attributesthat are explicitly listed in thismapping.
True/False
The below table details the mapping options:
Source Type Description Source 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
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.
Option Description Example
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.
Administration Reference
62
Option Description Example
Label A descriptive name for thisapproval
Access to the portal
Email Template 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 byenclosing it in a “${}”. Forinstance, to include the user’sfull name user “${givenName}${sn}”
You have an open approvalwaiting. Please go to https://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
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)
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.
Option Description Example
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
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 byenclosing it in a “${}”. Forinstance, to include the user’s
${givenName} ${sn}, Thank youfor registering for the portal.Your request is waiting approval.Thanks The Team
Administration Reference
63
Option Description Example
full 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.
Option Description Example
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.
Option Description Example
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.
Option Description Example
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
Maximum Connections The maximum number ofconnections to the database
10
Administration Reference
64
Option Description Example
Maximum Idle Time The maximum time a connectioncan be idle before its closed inmilliseconds
1000
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
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
SMTP Settings
Option Description Example
Host The host of the SMTP server Smtp.google.com
Port The port of the SMTP server 25 or 587 (google)
User The user used for authenticating [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
Use SSL Check if the server uses SSL True
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.
Administration Reference
65
Field Type Foreign Key Description Example
id int (Primary Key,Auto Increment)
entry id 1
userKey varchar(255) User identifier User ID
approvers
This table lists the approvers and certain attributes that have been processed. This table should be 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.
Field Type Foreign Key Description Example
id int (Primary Key,Auto Increment)
entry id 1
userKey varchar(255) User identifier User ID
targets
This table lists the name of all workflow targets as configured in the administration system. It is automaticlypopulated when Unison is started or the configuration is re-loaded. It should only be used for reportingand should not be updated manually.
Field Type Foreign Key Description Example
id int (Primary Key,Auto Increment)
entry id 1
name varchar(255) Target Name AD-MyEnterprise.com
workflows
The main driving table, each row tracks a workflow and is the main table for tracking all workflows.
Field Type Foreign Key Description Example
id int (Primary Key,Auto Increment)
entry id 1
name varchar(255) Workflow 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
Administration Reference
66
Field Type Foreign Key Description Example
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
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.
Field Type Foreign Key Description Example
id int (Primary Key,Auto Increment)
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 on
Administration Reference
67
the rules configured in the administration system. When the approval is executed, it still checks againstthe rules configured in the administration system.
Field Type Foreign Key Description Example
id int (Primary Key,Auto Increment)
entry id 1
approval int approval.id ID of open approval 1
approver int approvers.id ID of potentialapprover
1
auditLogType
This table is a lookup table for various audit log types. Its populated with the values below.
Field Type Foreign Key Description Example
id int (Primary Key,Auto Increment)
entry id 1
name varchar(255) Audit Log 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.
Field Type Foreign Key Description Example
id int (Primary Key,Auto Increment)
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
Administration Reference
68
Field Type Foreign Key Description Example
workflow int workflows.id The id of theworkflow beingexecuted
1
target int targets.id The id of the targeteffected
1
69
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:
Option Description Example
Name A descriptive name for the insert MyInsert
Class Name The class name of the insert com.tremolosecurity.proxy.myvd.util.CorruptObjectGUID
Property The name of the configurationproperty
MyProperty
Value The value of a configurationproperty
MyValue
Properties may be edited in place, added or removed using the appropriate buttons.
Directory Configuration
70
Directory Types
Active Directory
Configuration of an Active Directory forest with the following options:
Option Description Example
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
Enabled Determines if this directory willbe started (Default is True)
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
Directory Configuration
71
Option Description Example
Minimum Number ofConnections
The minimum number ofconnection to open
10
Maximum Number ofConnections
The maximum number ofconnection to open
100
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 DirectoryConfiguration of standard LDAP Directory with the following options:
Option Description Example
Name A descriptive name for thedirectory
MyForest
User Directory Determines if this directory storesuser objects
True / False
Enabled Determines if this directory willbe started (Default is True)
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
Stale Connection Timeout(milliseconds)
The maximum amount ofmilliseconds that a connectioncan remain locked until it
60000
Directory Configuration
72
Option Description Example
is considered stale. Once aconnection is considered stale theconnection is closed and re-addedto the pool.
Minimum Number ofConnections
The minimum number ofconnection to open
10
Maximum Number ofConnections
The maximum number ofconnection to open
100
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
Admin
An 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:
Option Description Example
Name A descriptive name for thedirectory
MyForest
User Directory Determines if this directory storesuser objects
True / False
Enabled Determines if this directory willbe started (Default is True)
True / False
Login ID The user’s login name Myuser
Password The user’s password
Amazon SimpleDB
Unison can use Amazon SimpleDB to store user and group information. This allows for a cloud basedsolution with no storage or backup footprint. This can provide an extremely effective way to store cloudbased 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.
Directory Configuration
73
Option Description Example
Name A descriptive name for thedirectory
MySimpleDB
User Directory Determines if this directory storesuser objects
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
BasicDBThe 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
Directory Configuration
74
Schema for Users and Groups
Option Description Example
Name A descriptive name for thedirectory
MySimpleDB
User Directory Determines if this directory storesuser objects
True / False
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
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
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
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
Link Table User Column The name of the column in thelink table that maps to the user’sprimary key
user
Link Table User Column The name of the column in thelink table that maps to the user’sprimary key
User
Link Table Group Column The name of the column in thelink table that maps to the group’sprimary key
Groups
Directory Configuration
75
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.
Option Description Example
Name A descriptive name for thedirectory
MySchema
User Directory Determines if this directory storesuser objects
True / False
Remote Base The DN of the root Unison shouldconnect to
cn=SubSchema
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
Use SSL Determines if the connection tothe forest is secure. Either theconnection certificate or it’s rootcertificate must be trusted
NoOp
The "NoOp" directory is a placeholder for configuring custom directory types. This directory should useinserts for performing searches and authentication.
Option Description Example
Name A descriptive name for thedirectory
MySchema
User Directory Determines if this directory storesuser objects
True / False
Insert Reference GuideThese inserts are specific to Tremolo’s Unison and are not included with the MyVirtualDirectory project.
Directory Configuration
76
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
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.
Class Name com.tremolosecurity.proxy.myvd.inserts.ad.UUIDtoText
attributeName The name of the attribute to map
77
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
Option Description Example
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
78
2. Using MetaData – User the metadata from an identity provider to automatically configure most options
Identity Provider Information
This section are specific to the identity provider this chain is associated with.
Option Description Example
Optional Identity 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
https://www.myidp.com/fed/aunth20Response
Identity Provider Redirect URL The URL for the IdP’sREDIRECT endpoint
https://www.myidp.com/fed/aunth20Response
Optional Identity Provider LogoutURL
The URL for the IdP’s SingleLogout Service HTTP-Redirectendpoint; requires that theSignature Certificate and OptionalFinal Logout URL be set
https://www.myidp.com/fed/aunth20Response
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.
Option Description Example
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
Authentication Mechanisms
79
Option Description Example
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.
Option Description Example
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
Authentication Mechanisms
80
Option Description Example
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
Option Description Example
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".
ChainThere are no chain specific configuration options.
BasicBasic authentication can be used for simple authentication tasks.
MechanismThere are no mechanism configuration options.
Chain
Option Description Example
Realm Name The name of the realm presentedto the user when authenticating
My Authentication Server
User Attribute Name The name of the attribute to usewhen looking for the user
uid
Authentication Mechanisms
81
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:
Option Description Example
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.
Option Description Example
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
Authentication Mechanisms
82
ChainWhen 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.
Option Description Example
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 alternativenames, that will be the RDN of anunmatched entry.
CN
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
Authentication Mechanisms
83
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.
MechanismNo configuration Parameters
Chain
Option Description Example
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.
MechanismNo configuration Parameters
Chain
Option Description Example
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.
Authentication Mechanisms
84
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.
Mechanism
There are no mechanism level configurations
Chain
When using this mechanism in a chain, it MUST come after a mechanism that collects the user’s loginsuch as the username only or login form.
Option Description Example
Account SID Twilio Account SID
Authentication Token Twilio Account token
SMS Source Phone Number Twilio Source Phone Number 1234567890
User Attribute That Stores User’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
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.
Mechanism
Questions users may choose from are configured on the mechanism.
Authentication Mechanisms
85
Chain
When 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.
Option Description Example
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:
Option Description Example
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,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.
Mechanism
There are no mechanism level options.
Authentication Mechanisms
86
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.
Option Description Example
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:
Option Description Example
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.
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.
Authentication Mechanisms
87
Option Description Example
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.
MechanismThere are no mechanism level configuration options.
ChainThis mechanism should only be configured AFTER the chain has established a user
Option Description Example
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:
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
Authentication Mechanisms
88
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".
Option Description Example
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
89
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.
Option Description Example
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.
Option Description Example
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
90
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.
Option Description Example
Logut 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.
Option Description Example
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
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.
Option Description Example
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.
Filters
91
Option Description Example
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.
Option Description Example
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
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.
Option Description Example
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)
Filters
92
Option Description Example
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.
Option Description Example
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
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
Basic AuthenticationThis filter is used in conjunction with an application with a disabled session. It will perform a basicauthentication against the internal virtual directory.
Option Description Example
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.
Filters
93
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".
Option Description Example
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.
Option Description Example
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
Filters
94
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.
Option Description Example
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.
Option Description Example
Support Cookie Name RegularExpressions
If checked, the values tofilter are treated as Javaregular expressions. (http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html)
Unchecked
Cookies to Filter List of cookie names (or regularexpressions) to filter
SomeCookieName
95
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.
Option Description Example
Signature Key The key used for verifyingsigned authentication requests.The key should be listed under the
Idp-cert-key
Identity Provider Configuration
96
Option Description Example
“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.
Option Description Example
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
97
Option Description Example
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.
Option Description Example
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
98
Chapter 14. 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.
Source Type Description Source 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
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.
Option Description Example
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
99
Option Description Example
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
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.
Option Description Example
Name A descriptive name for the target Alfresco
Admin Service URL The full URL of the admin service https://alfresco.enterprise.com /alfresco/service/api
Admin User User with admin privileges Admin
Admin Password Password for admin user
Username Attribute Name The user id attribute username
Use Last Mile Security? If set to true, a last mile header 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
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.
Option Description Example
Name A descriptive name for the target MyDomain
Host Host for the ldap server ldap.enterprise.com
Port The port to connect to 636
Administrator DN A DN for a user withadministrator rights to create andupdate accounts
Cn=Directory Manager
Provisioning Targets
100
Option Description Example
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.
Figure 1 – Group Management Mode: None
Provisioning Targets
101
Figure 2 – Group Management Mode: Many to Many
Figure 3 - Group Management Mode: One to Many
Option Description Example
Name A descriptive name for the target MyDB
Driver The class of the JDBC driver com.vendor.jdbc.Driver
Provisioning Targets
102
Option Description Example
URL The JDBC URL for accessing thedatabase
jdbc:driver://host/db
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
Password The password for the database
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
Users Table The name of the table that storesthe user objects
Users
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
Provisioning Targets
103
Option Description Example
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.
Option Description Example
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.
Option Description Example
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
Provisioning Targets
104
Option Description Example
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.
Option Description Example
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
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.
Option Description Example
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
Provisioning Targets
105
Option Description Example
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.
Option Description Example
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
Maximum Connections The maximum number ofconnections to the database
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
106
Chapter 15. 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.
Option Description Example
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.
Option Description Example
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
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
107
"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.
Option Description Example
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.
Option Description Example
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.
Option Description Example
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.
Option Description Example
groupName The name of the group to ignore Administrators
targetName The name of the provisioningtarget to search
adUsers
Provisioning Custom Tasks
108
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.
Option Description Example
nameAttr The attribute name to search foron the user's account
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.
Option Description Example
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.
Option Description Example
message An optional label to add to the logmessage
"After approval"
109
Chapter 16. 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 uses a master/slave model, where a single server is the configuration "master" whilemultiple "slaves" consume configuration data. When a configuration change is made to Unison, the changeis 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
The configuration is pushed over port 9090 (the administration port) using certificate authentication.For details on how to add slaves and change the certificate used for securing the admin system, see theadministration guide.
There are two methods for configuring Unison clusters:
• Peer Mode - All Unison servers in the cluster accept user requests
• Client/Server Mode - The configuration master does not serve user requests
Each method has its advantages and disadvantages. Its recommended that port 9090 run on its own networkinterface with limited access. Each of the two methods are detailed below.
High Availability
110
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
111
Client / Server Mode
High Availability
112
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.