Summary

Most Semarchy xDM customers use a central Single Sign On authentication technology. Often this is not practical or not desired during initial development work.

This article explains how to configure a Tomcat DataSourceRealm for easy management of users.

After completing these steps you will be able to provision, edit, and remove users from a simple web-based GUI. There's no longer a need to have access to tomcat-users.xml to add users or roles. (But tomcat-users.xml can remain enabled if desired.)

Model the Entities in xDM

We will create Basic entities in xDM to manage users and roles. You may choose to include these entities in the same model as another domain. Or you may create a separate model and separate data location to manage these. The steps and functionality are identical in either case.

Data model:

Create Application Components for each entity. It's fine to accept all default settings.

Validate the model. Then deploy the model to your data location.

You should now be able to add users and roles in the Semarchy xDM user interface.

Add Users and Roles

You should now be able to log in to the Semarchy xDM front end to create users and roles.

Start by creating semarchyConnect and semarchyAdmin. Every user needs semarchyConnect, and in your DEV environment many users may have semarchyAdmin.

Then create any additional roles you need. (In a new environment you may not need any additional roles yet.)

If you plan to create many users or many roles right now, then be sure to modify the "Create" action to support creating multiple records at once.

Likewise, if you use this environment to manage users permanently then you'll want to update the Business Views to show transitions from User to UserRoles and make other usability improvements. Configuring the stepper to use a many-to-many relation makes it quicker to add roles to a user. Adding a transition from Roles lets you see all users with a given role, etc.

But the default generated components are good enough for a quick start.

Add the users that you want.

Add the roles to each user as appropriate.

Now you have a table with the desired user and role information. If you followed the data model shown above you will have physical table names similar to these:

GD_SEM_USER and GD_USER_ROLE

Next you need to configure Tomcat to use this information for authentication.

Configure Tomcat

First, we need a view on top of the table GD_USER_ROLE. This is to overcome a limitation of the default functionality in Tomcat's DataSourceRealm. This realm assumes that the foreign key to the user table will have exactly the same column name as in the username in the user table. But in Semarchy the foreign key is named F_USER_NAME rather than USER_NAME.

Create V_USER_ROLE

/* sanity check: does this table have the role information I expect? */
select * from GD_USER_ROLE ;

/* create a view to rename F_SEM_USER */
create or replace view V_USER_ROLE as
select F_SEM_USER as USER_NAME, F_SEM_ROLE as F_SEM_ROLE
from GD_USER_ROLE ;

/* sanity check: does the new view return users and roles as expected? */
select * from V_USER_ROLE ;

Next, we need to edit semarchy.xml use the user information. In this example we'll use a combined realm so that you have the option to log in using users defined in tomcat-users.xml as well as users defined in Semarchy xDM.

semarchy.xml snippet

<!-- You should already have this Valve in semarchy.xml -->
  <Valve className="org.apache.catalina.authenticator.FormAuthenticator" landingPage="/"/>

<!-- Use this realm to replace your existing realm. -->
  <Realm className="org.apache.catalina.realm.CombinedRealm">
    <!-- This UserDatabaseRealm is tomcat-users.xml -->
    <Realm className="org.apache.catalina.realm.UserDatabaseRealm" resourceName="UserDatabase"/>
    <!-- This JDBCRealm points to your data location containing the user and role tables. -->
    <Realm
      className="org.apache.catalina.realm.JDBCRealm" driverName="oracle.jdbc.OracleDriver"
      connectionURL="jdbc:oracle:thin:@xxx.xxxxxxxxx.eu-west-1.rds.amazonaws.com:1521:ORCL"
      connectionName="MY_USER" connectionPassword="MY_PASSWORD"
      userTable="GD_SEM_USER" userNameCol="USER_NAME" userCredCol="PASSWD"
      userRoleTable="V_USER_ROLE" roleNameCol="F_SEM_ROLE"/>
  </Realm>

Restart tomcat, then log in with your newly defined users and roles.

Now you can provision, edit, and remove users from a simple web-based GUI. There's no longer a need to have access to tomcat-users.xml to add users or roles. (But tomcat-users.xml can remain enabled if desired.)

Troubleshooting

If things don't work perfectly, then turning on logging can help.

Add these logging parameters. In a default tomcat configuration you can add these to the end of /etc/tomcat8/logging.properties

org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/semarchy].level = ALL
org.apache.catalina.realm.level = ALL
org.apache.catalina.realm.useParentHandlers = true
org.apache.catalina.authenticator.level = ALL
org.apache.catalina.authenticator.useParentHandlers = true

Sample of failed login attempt

11-May-2018 22:08:26.134 FINE [http-nio-8080-exec-3] org.apache.catalina.authenticator.AuthenticatorBase.invoke Security checking request POST /semarchy/mdm-app/ConsentManagement/ConsentManagement/j_security_check
11-May-2018 22:08:26.134 FINE [http-nio-8080-exec-3] org.apache.catalina.authenticator.FormAuthenticator.authenticate Authenticating username 'matt.dahlman'
11-May-2018 22:08:26.135 FINE [http-nio-8080-exec-3] org.apache.catalina.realm.CombinedRealm.authenticate Attempting to authenticate user "matt.dahlman" with realm "org.apache.catalina.realm.UserDatabaseRealm"
11-May-2018 22:08:26.135 FINE [http-nio-8080-exec-3] org.apache.catalina.realm.CombinedRealm.authenticate Failed to authenticate user "matt.dahlman" with realm "org.apache.catalina.realm.UserDatabaseRealm"
11-May-2018 22:08:26.135 FINE [http-nio-8080-exec-3] org.apache.catalina.realm.CombinedRealm.authenticate Attempting to authenticate user "matt.dahlman" with realm "org.apache.catalina.realm.JDBCRealm"
11-May-2018 22:08:26.200 FINE [http-nio-8080-exec-3] org.apache.catalina.realm.CombinedRealm.authenticate Authenticated user "matt.dahlman" with realm "org.apache.catalina.realm.JDBCRealm"
11-May-2018 22:08:26.201 FINE [http-nio-8080-exec-3] org.apache.catalina.authenticator.FormAuthenticator.authenticate Authentication of 'matt.dahlman' was successful
11-May-2018 22:08:26.202 FINE [http-nio-8080-exec-3] org.apache.catalina.authenticator.FormAuthenticator.authenticate Redirecting to original '/semarchy/mdm-app/ConsentManagement/ConsentManagement/search'
11-May-2018 22:08:26.202 FINE [http-nio-8080-exec-3] org.apache.catalina.authenticator.AuthenticatorBase.invoke  Failed authenticate() test ??/semarchy/mdm-app/ConsentManagement/ConsentManagement/j_security_check
11-May-2018 22:08:26.497 FINE [http-nio-8080-exec-4] org.apache.catalina.authenticator.AuthenticatorBase.invoke Security checking request GET /semarchy/mdm-app/ConsentManagement/ConsentManagement/search
11-May-2018 22:08:26.497 FINE [http-nio-8080-exec-4] org.apache.catalina.authenticator.FormAuthenticator.authenticate Restore request from session '64C4C864567E3581E28B1C2772C5C942'
11-May-2018 22:08:26.497 FINE [http-nio-8080-exec-4] org.apache.catalina.authenticator.AuthenticatorBase.register Authenticated 'matt.dahlman' with type 'FORM'
11-May-2018 22:08:26.498 FINE [http-nio-8080-exec-4] org.apache.catalina.authenticator.AuthenticatorBase.register Session ID changed on authentication from [64C4C864567E3581E28B1C2772C5C942] to [9F5424EB3C01F66833
3745FE0A981393]
11-May-2018 22:08:26.499 FINE [http-nio-8080-exec-4] org.apache.catalina.authenticator.FormAuthenticator.authenticate Proceed to restored request
11-May-2018 22:08:26.499 FINE [http-nio-8080-exec-4] org.apache.catalina.realm.RealmBase.findSecurityConstraints   Checking constraint 'SecurityConstraint[Protect Convergence for MDM Designer, Protect Convergence 
for MDM Landing, Protect Convergence for MDM Data UI]' against GET /mdm-app/ConsentManagement/ConsentManagement/search --> true
11-May-2018 22:08:26.499 FINE [http-nio-8080-exec-4] org.apache.catalina.realm.RealmBase.findSecurityConstraints   Checking constraint 'SecurityConstraint[Protect Convergence for MDM Designer, Protect Convergence 
for MDM Landing, Protect Convergence for MDM Data UI]' against GET /mdm-app/ConsentManagement/ConsentManagement/search --> true
11-May-2018 22:08:26.499 FINE [http-nio-8080-exec-4] org.apache.catalina.authenticator.AuthenticatorBase.invoke  Calling hasUserDataPermission()
11-May-2018 22:08:26.499 FINE [http-nio-8080-exec-4] org.apache.catalina.realm.RealmBase.hasUserDataPermission   User data constraint has no restrictions
11-May-2018 22:08:26.500 FINE [http-nio-8080-exec-4] org.apache.catalina.authenticator.AuthenticatorBase.invoke  Calling authenticate()
11-May-2018 22:08:26.500 FINE [http-nio-8080-exec-4] org.apache.catalina.authenticator.AuthenticatorBase.checkForCachedAuthentication Already authenticated [matt.dahlman]
11-May-2018 22:08:26.500 FINE [http-nio-8080-exec-4] org.apache.catalina.authenticator.AuthenticatorBase.invoke  Calling accessControl()
11-May-2018 22:08:26.500 FINE [http-nio-8080-exec-4] org.apache.catalina.realm.RealmBase.hasResourcePermission   Checking roles GenericPrincipal[matt.dahlman()]
11-May-2018 22:08:26.500 FINE [http-nio-8080-exec-4] org.apache.catalina.realm.RealmBase.hasRole Username matt.dahlman does NOT have role semarchyConnect
11-May-2018 22:08:26.501 FINE [http-nio-8080-exec-4] org.apache.catalina.realm.RealmBase.hasResourcePermission No role found:  semarchyConnect
11-May-2018 22:08:26.501 FINE [http-nio-8080-exec-4] org.apache.catalina.authenticator.AuthenticatorBase.invoke  Failed accessControl() test

# This attempt failed due to a typo in a column name in the roles table. 
# The enhanced logging reveals that authentication was successful, but the user does NOT have role semarchyConnect.