Best Practice - configuring user access for a DEV instance
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.
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.
<!-- 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