Tomcat Authentication

The administrative portion of Numishare should be closed off to non-authenticated users. We will want to create an new administrative group and user(s) that can access the /numishare/admin portion of the application. The instructions follow Tomcat authentication.

Create a Tomcat User for Numishare Admin

Edit /var/lib/tomcat10/conf/tomcat-users.xml and follow the commented out example in the file. Within the tomcat-users element, we want to create a new role <role rolename="numishare-admin"/> and at least one new user with a matching role, e.g., <user username="admin" password="" roles="numishare-admin"/>. By default, the passwords are stored in plain text within this file, but Tomcat authentication can be calibrated to use SHA-2 encoded passwords.

There may be multiple users belonging to the numishare-admin group. This group has the authorization to create new projects in Numishare, associating other Tomcat groups with collection names in the eXist XML database. Typically, the group name should match the eXist-db collection name.

Create additional project-based Tomcat users

Follow the directions above for creating new users and groups for each additional project in Numishare. For example, users with access to editing and publication of the OCRE project belong to the ocre Tomcat group: <role rolename="ocre"/> and <user username="ocre-user" password="" roles="ocre"/>.

After creating the user and role, save and exit the file and restart Tomcat for the changes to take effect: sudo service tomcat7 restart

Restrict Access to /numishare/admin in Orbeon

Now that we have created a new 'numishare-admin' role in Tomcat, we can now restrict access to the administrative backend of Numishare through Orbeon's web.xml following the standard Tomcat protocol.

Edit /var/lib/tomcat10/webapps/orbeon/WEB-INF/web.xml and scroll to the bottom of the file. We will place authentication instructions above the session-config element. After saving web.xml, restart Tomcat.

<security-constraint>
    <web-resource-collection>
        <web-resource-name>Numishare</web-resource-name>
        <url-pattern>/numishare/admin/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
        <role-name>numishare-admin</role-name>
        <role-name>other-project-roles</role-name>
    </auth-constraint>
</security-constraint>
<login-config>
    <auth-method>BASIC</auth-method>
</login-config>
<session-config>
    <session-timeout>720</session-timeout>
</session-config>

In essence, this restricts anything in the /numishare/admin/* namespace to an authenticated user from the numishare-admin and other project Tomcat roles. The authentication method is BASIC (in contrast with FORM), so the login is performed through a browser popup window rather than a web page.

Note The XForms web form pages (admin and admin/import) do not function via Apache Proxypass, so you will have to access the administrative section through Orbeon directly at port 8080.

Set Roles in Orbeon properties

Following #4 in the Orbeon Form Runner authentication documentation, edit $TOMCAT_HOME/webapps/orbeon/WEB-INF/resources/config/properties-local.xml and insert the following property:

<property as="xs:string" name="oxf.fr.authentication.method" value="container"/> <property as="xs:string" name="oxf.fr.authentication.container.roles" value="other-project-roles numishare-admin"/>

Substituting 'other-project-roles' for any other project necessary.

BASIC Authentication

BASIC authentication requires additional configuration, as of Orbeon 2016. See https://doc.orbeon.com/installation/tomcat.html#basic-authentication.

FORM Authentication

By default, the BASIC authentication method is enabled in Orbeon, which means a simple, browser-based popup window will appear when attempting to access the Admin panel. This may be replaced with a login form page. The login and login-error pages are contained within the Numishare installation. The default login-config may be replaced with the following:

<login-config>
        <auth-method>FORM</auth-method>
        <form-login-config>
                <form-login-page>/numishare/login</form-login-page>
                <form-error-page>/numishare/login-failed</form-error-page>
        </form-login-config>
</login-config>

The /numishare/login and /numishare/login-failed paths above are defined in the Numishare Page Flow Controller (page-flow.xml) in the root installation directory.

Encrypted authentication

Note that enabling encrypted SHA-256 or SHA-512 passwords has changed in Tomcat 8.5: https://stackoverflow.com/questions/39967289/how-to-use-digest-authentication-in-tomcat-8-5.