;

Securing the Viewer

EAS Essential Software, General

The Essential Viewer can be configured to require that any user first authenticate themselves before accessing the requested View.

In the open-source release, the access control is relatively coarse-grain – can the user access the Viewer or not? – but this helps to keep things simple to configure and manage. We can connect Viewer to an LDAP directory such as Active Directory so that users can use their normal login and password to access the Viewer.

Define the Connection from Tomcat to Active Directory / LDAP Directory

The first step is to edit the Tomcat ‘server.xml’ file to define the LDAP connection to your Active Directory. Open this from <TOMCAT>/conf/server.xml. By editing the <Realm> tag, we specify the connection to the LDAP service, your Active Directory.

With your Active Directory connection details to hand, complete the definition of the <Realm> tag as follows:

<Realm className="org.apache.catalina.realm.JNDIRealm" debug="99"
        connectionURL="ldap://DOMAIN_CONTROLLER_HOSTNAME:389"
        alternateURL="ldap://DOMAIN_CONTROLLER_HOSTNAME:389"
        connectionName="[email protected]"
        connectionPassword="DIRECTORY_USER_PASSWORD"
        referrals="follow"
        userBase="OU=USER_GROUP,DC=DOMAIN,DC=com"
        userSearch="(sAMAccountName={0})"
        userSubtree="true"
        roleBase="OU=GROUPS_GROUP,DC=DOMAIN,DC=com"
        roleName=“cn”
        roleSubtree="true"
        roleSearch="(member={0})"
        />

In the connectionName parameter, you can define a more specific query for which part of the directory to connect to and search, e.g.

connectionName=”cn=tomcat LDAP,ou=user,ou=Essential Viewer,ou=Essential Project,dc=viewer,dc=essentialproject,dc=com”

Which performs a query along the lines of:

From the ‘com’ Domain Component (dc), find the ‘essentialproject’ Domain Component and inside there, find the ‘viewer’ Domain Component.

In the ‘viewer’ Domain Component, find the Organisation Unit (ou) called ‘Essential Project’ and then in there find the Organisation Unit called ‘Essential Viewer’ and from there, find the Organisation Unit called ‘user’. From ‘user’, find the object that has the Common Name ‘tomcat LDAP’.

 

 

Configure the Essential Viewer Application

Having instructed Tomcat to connect to the LDAP source, the next step is to configure the application details in the <TOMCAT>/webapps/essential_viewer/WEB-INF/web.xml file.

In here, you will find a set of SECURITY-CONSTRAINT and SECURITY-ROLE tags that are commented out. Un-comment these to switch on the access control. We now need to update these settings to make sure that the configuration is looking at the LDAP directory.

Make sure that the following sections are un-commented:

  • SECURITY-CONSTRAINT which specifies the scope of the application that is to have access control enabled. The newly un-commented setting covers the entire application. In the AUTH-CONSTRAINT tag, you specify the role that users must have in order to access URLs within the Viewer. Out of the box, the security service will look for a role ‘report_viewer’ in your Active Directory. Change this value if you want to use an alternative role name in your directory.
  • LOGIN-CONFIG defines how the user should log in. There are two options here, BASIC which pops up a login / password dialog before you can enter the Viewer, and FORM, which redirects the user to a form on a web page in order to login. We’ll start by continuing with ‘BASIC’. As we will not be using Tomcat’s default user database, we may wish to change the value of the <realm-name> tag.
  • SECURITY-ROLE which defines the roles that are used by this application. Users must have this role in the source directory if they are to gain access. In the <role-name> tag, specify the role in your Active Directory that is assigned to authorised users. The default for this is ‘report_viewer’ but change this to match the value that you wish to use in your directory.

Restart Tomcat to have these changes take effect.

 

Finer-grained Access Control 

It is possible to set the configuration up so that only parts of the Viewer application are constrained by the security specification. For example, we may wish to ensure that everyone has to login in order access the Viewer website but as only a small, authorised set of users have access to the repository in Protege, we don’t need to login in order to publish. In this case, we can define two separate SECURITY-CONSTRAINT tag sets. e.g.

<security-constraint>
    <display-name>Essential Security Constraint</display-name>
    <web-resource-collection>
        <web-resource-name>Protected Area</web-resource-name>
    <!-- Define the context-relative URL(s) to be protected -->
        <url-pattern>/report</url-pattern>
    </web-resource-collection>
    <auth-constraint>
    <!-- Anyone with listed roles may access this area -->
        <role-name>ViewerRole</role-name>
    </auth-constraint>
</security-constraint>
 
<security-constraint>
    <display-name>Essential Public</display-name>
    <web-resource-collection>
        <web-resource-name>Non-Protected Area</web-resource-name>
        <!-- Define the context-relative URL(s) to be protected -->
        <url-pattern>/reportService</url-pattern>
    </web-resource-collection>
    <!-- No constraint which means everybody has access! -->
</security-constraint>
 
<!-- Security roles referenced by this web application -->
<security-role>
    <description>A role for all authenticated ("logged in") users</description>
    <role-name>ViewerRole</role-name>
</security-role>

 

Login Page Instead of a Login Dialogue

For a smoother-looking login experience, you can instruct the application to use FORM-based login in instead of BASIC. With this approach, we can tell Tomcat which JSP pages to use in order to present the login form, gather the details and report any errors.

The first thing we need to do is to define the JSPs that we need for the login, any errors and for logout. Tomcat comes prepared with some examples that we can draw upon, in:

<TOMCAT>/webapps/examples/jsp/security/protected

We can edit these as follows:

  • login.jsp defines the web page that will present the login form. You can edit this as required but the <form> tag must have the following components: (Note that the names “j_security_check, j_username and j_password are significant and are required).
    • <form id=“login” method=“post” action=“j_security_check”>
    • <input id=“user” type=“text” name=“j_username”/>
    • <input id=“password” type=“password” name=“j_password”/>
  • 403.jsp defines a page to be presented when the user is not authorised to access the viewer.
  • error.jsp defines the page to be presented when there is a login error, e.g. you have entered an invalid password.
  • logout.jsp defines the page presented when the user logs out.

Edit these JSP pages as required, e.g. to include any styling that you wish. Then, save these in your Viewer home folder in a subfolder called ‘protected’, e.g. <TOMCAT>/webapps/essential_viewer/protected

With our login, logout and error pages defined, we can now complete the configuration of essential_viewer/WEB-INF/web.xml to switch this on.

In the <login-conf> section of web.xml, we can now change the <auth-method> to FORM. Next, we add a <form-login-config> section to specify the login page and the error page that we defined a few moments ago. e.g.

<!-- Default login configuration uses form-based authentication -->
<login-config>
   <auth-method>FORM</auth-method>
   <realm-name>Essential Viewer</realm-name>
   <form-login-config>
      <form-login-page>/protected/login.jsp</form-login-page>
      <form-error-page>/protected/error.jsp</form-error-page>
   </form-login-config>
</login-config>

Restart Tomcat for these changes to take effect. Note that the Essential Viewer tab in Protege, will automatically attempt FORM-based login as required.

Contact Us