Tomcat Authentication

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

Create a Tomcat User for Nomisma 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="nomisma-admin"/> and at least one new user with a matching role, e.g., <user username="admin" password="" roles="nomisma-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 nomisma-admin group.

Restrict Access to /nomisma/admin in Orbeon

Now that we have created a new 'nomisma-admin' role in Tomcat, we can now restrict access to the administrative backend of Nomisma 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>Nomisma</web-resource-name>
        <url-pattern>/nomisma/admin/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
        <role-name>nomisma-admin</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 /nomisma/admin/* namespace to an authenticated user from the nomisma-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 nomisma-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 Nomisma installation. The default login-config may be replaced with the following:

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

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

Encrypted authentication

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

It is highly encouraged to use encrypted rather than clear-text passwords in the tomcat-users.xml file.