User Authentication with Active Directory Single-Sign-On
iteraplan can be set up to authenticate users via Single-Sign-On (SSO), provided that they are logged in to a Windows Active Directory. This sub chapter describes how to configure iteraplan and how a possible sample solution for the rest of the required environment might look like. The installer includes the option to install with Single-Sign-On configuration, as described in Username & Password.
When trying to set-up the sample solution described below your mileage may vary. Please understand that even with support contracts iteratec can not offer support for systems and set-ups other than iteraplan itself as the number of combinations of systems and versions of software is simply too big.
Other set-ups than the one described below might also work. Should you have another solution up and running and are willing to share it with other iteraplan users, simply send it to us. We would be glad to publish it here.
iteraplan's view of SSO scenarios
In SSO scenarios, the iteraplan web application doesn't handle user authentication itself, but expects the information about a pre-authenticated principal from an external system (in this case the IIS). This is realized by a request header "logon-user", which contains the pre-authenticated principal information as plain username without domain or as username in the format "DOMAIN\user" (without quotes). iteraplan trusts the provided information, which is why the Tomcat's configuration should deny such requests from untrusted sources, for example by restricting the IP range or the hostname(s) for the AJP connector.
The header name "logon-user" can be configured during the installation process. It is also possible to manually set the parameter "principalRequestHeader" in the bean "preauthAuthenticationFilter" of iteraplan's Spring configuration file "WEB-INF/applicationContext-spring-security.xml".
After iteraplan got the principal information, it looks up the groups (= iteraplan roles) in the ActiveDirectory's LDAP for this principal to perform authorization.
For the sample solution the following should be available:
- An Active Directory where all relevant Client Computers are members
- Windows Server 2008 or 2012
- Must be Member in the same Active Directory as iteraplan user are
- With Web Server Role (IIS)
- .NET Framework 3.5 or newer
- Boncode AJP Connector (see below for details)
- iteraplan 3.3 or later with working LDAP configuration parameters
- May be installed on the same Windows Server, but can also run on a different server (even on an non-Windows Operating System)
- Deployed in a Tomcat Server with active AJP Connector
- Optional: SSL certificate for configuring HTTPS connectivity
We know of two possible deployment variants where iteraplan and IIS are installed, as shown in following diagrams. Note that the database is not shown in these diagrams, as it does not matter for authentication. You are free to install iteraplan on the same server where the database runs or on a separate server.
Deployment Variant "All in one Server"
Deployment Variant "Separate Servers"
If you want to run more than one iteraplan installation, this is possible with still just one IIS server. You need to configure different IIS Sites and have each forward to a different iteraplan installation. This case is not considered in further detail in this documentation. Please refer to the Boncode connector documentation for help.
Step-by-Step: Installing the SSO-enabled iteraplan version
Since iteraplan version 3.4 the LDAP with SSO option is available within the premium Installer.
- Use the iteraplan installer with LDAP + SSO option to perform the basic configuration, initialize the database (if necessary) and generate a WAR file.
- Copy your working LDAP configuration file to $TOMCAT_HOME/webapps/iteraplan-sso/WEB-INF. This assumes that you named the WAR file iteraplan-sso.war during installation.
- Edit the Tomcat configuration file $TOMCAT_HOME/conf/server.xml. and make sure it contains the following Connector entry: <!-- Define an AJP 1.3 Connector on port 8009 --><Connector port="8009" protocol="AJP/1.3" URIEncoding="UTF-8"executor="iteraplanThreadPool" tomcatAuthentication="false" redirectPort="443" /> If IIS and Tomcat run on the same server, you may also add the attribute address="localhost" to make sure that Tomcat accepts only local connections, not from other servers.
- Edit the same file so that any other <Connector> entry is removed or commented out. This is required to avoid that unauthenticated requests can reach Tomcat. (iteraplan would block such unauthenticated requests, but it would be confusing for any user.)
Step-by-Step: Installing IIS8 on the Windows Server
- Windows 2008/ 2012 is installed (optional/ recommended: 64 Bit version)
- This documentation focusses on Windows Server 2012 with IIS 8
- Start Server Manager
- Pick Add Roles and Features
- Select Role-based or Feature-based Installation and pick the current server:
- Then select the role Webserver (IIS) and confirm that IIS Management Tools are installed as well:
- In the next step, no additional features are needed. Just click Next.
- The next step shows explanations what the Webserver role comprises. Click Next to proceed to the step Role Services.
- Here, make sure that the option Windows authentication in the Security section is enabled. Also, be sure to enable .NET extensibility 3.5 in section Application development. This is needed for the Boncode connection to integrate with IIS. Confirm that required other features will be enabled as well.
- The next page lists all selected Features. Confirm that they are correct and click Install.
- After the installation process completed, confirm and close the wizard. Return the Server Manager Window.
- There you will see a new left-hand side entry for IIS which offers some diagnostic information. Click the top-right Tools button and select IIS Manager.
- Click your way through the left-hand side configuration tree down to the Default Web Site. After you clicked on that, the right-hand side task panel offers a command to Browse the Website.
- A Web Browser will open and show the IIS welcome page. You have now verified that IIS has been installed and is able to service HTTP requests.
- Optional steps (not documented here): Configure IIS with an SSL certificate to provide HTTPS connectivity
Step-by-Step: Install the Boncode IIS-to-Tomcat connector
- Download the connector installation package from http://www.boncode.net/boncode-connector and extract the ZIP file to the server
- Launch the Boncode installer
- Proceed through the installation wizard and enter the connection information for your Tomcat.
- Leave the default settings as proposed by the wizard:
- Depending on your IIS setup, you may have to choose a specific site into which the connector should be installed. Otherwise, we recommend to install it into All IIS Sites:
- Modify the default handler mappings in the next step if needed for other purposes. For iteraplan, they are fine.
- Be sure to leave IIS Sub Configuration enabled:
- After installation has finished, go back to the IIS Manager.
Step-by-Step: Configuring IIS to forward to iteraplan
- Within the desired IIS site, add an application by right-clicking the site icon.
- As Alias enter the name of the iteraplan application in your Tomcat as entered by you during iteraplan's installation, and select a suitable physical path on the server, where IIS can store its settings. After that, open the Handler Mappings configuration dialog for that application alias.
- Add a Managed Handler to that application alias as follows. The wildcard in the request path field indicates that all requests should be forwarded to the Boncode connector, and hence to Tomcat and iteraplan. You can find the complete string to be entered into the Type field in the file BonCodeFullHandlerName.txt within the Boncode ZIP download.
- In that same dialog, click the Request Restrictions button. Uncheck the option Invoke handler only if request is mapped to on the Mapping tab (first dialog tab), and check that all verbs are handled (second dialog tab) and access permissions are set to Script level.
- Confirm all dialogs for the handler mapping and return to the application alias configuration. Open the Authentication dialog.
- Choose Windows Authentication and enable it. Choose Anonymous Authentication and disable it. You can perform advanced configuration of the Windows authentication feature if needed.
Optional: Step-by-Step: Enable HTTP Basic authentication for iteraplan's REST API
- Add a sub-application API as a child of the iteraplan application you just created. For the field Physical Path it is recommended to create an empty subdirectory within the iteraplan application folder on your hard drive. Leave all other settings with their default values.
- Open the Authentication dialog for that sub-application and enable Anonymous Authentication. All other authentication mechanism must be disabled. Note that choosing anonymous authentication here does not mean everyone could access the REST API, but that authentication is not performed by IIS, but instead by iteraplan itself. Iteraplan will authenticate credentials provided via HTTP Basic against the Active Directory via LDAP.
- Enable SSO for Firefox
The NTLM Authentification required for SSO is enabled in IE by default, but disabled in Firefox. To enable it in Firefox, enter "about:config" (without quotes) into the address bar and search for "network.automatic-ntlm-auth." (without quotes). Double-click on the entry "network.automatic-ntlm-auth.trusted-uris" and enter the URL(s ) that are allowed to automatically authenticate via NTLM, like "example.com". For details please refer to the Mozilla documentation.
- Increase the packet size
In most cases the default packet size for the SSO token might not be big enough. You have to increase the value to an equal byte size in the Boncode AJP connector configuration and in the Tomcat AJP connector configuration. A value of 16384 bytes should be sufficient.
- Boncode AJP connector: make sure, that the "BonCodeAJP13.settings" file has an option like "<PacketSize>16384</PacketSize>". For details please refer to the Boncode documentation.
- Tomcat AJP connector: In the "conf/server.xml" file, look for the AJP <Connector>-tag and make sure that it contains an attribute like
packetSize="16384". For details please refer to the Tomcat documentation.
- Tomcat security
When the token is sent from a different machine as the Tomcat server, then you can restrict the remote machines by adding a RemoteAddressaFilter-Valve or a RemoteHostFilter to the Tomcat configuration. For details please refer to the Tomcat documentation for Valves.
There should be a file BonCodeAJP13.settings in the windows directory of your server.
You can add two lines to that settings file to enable additional logging, see the entries LogDir and LogLevel in the following example:
This will create logfiles containing information about the requests forwarded by the Boncode connector. The files will be saved in the given directory with a name prefix BonCodeAJP13Connection_.