How to Implement a New Realm in Tomcat

Tomcat by default ships with a couple of Realm implementations likeJDBCRealm, DataSourceRealm, and JNDIRealm, etc. But sometimes, it is not sufficient for your organization’s requirements and you are required to apply your own implementations.

How to Implement a Custom Realm in Tomcat

You can create your own realm by extending RealmBase class; here, I am going to show an example of implementing a new Realm in Tomcat.

Here is a sample code snip for implementing a new Realm by extending RealmBase class:

package com.sid.realm;
import java.security.Principal;
import java.util.ArrayList;
import java.util.List;
import org.apache.catalina.realm.RealmBase;
import org.apache.catalina.realm.GenericPrincipal;
import org.jboss.logging.Logger;
 /*
 * @author siddhartha
 */
public class NewRealm extends RealmBase {
 
 private String username;
 private String password;
 protected static Logger log = Logger.getLogger(NewRealm.class);

 @Override
 public Principal authenticate(String username, String credentials) {

 this.username = username;
 this.password = credentials;
 log.info("Authentication is taking place with userid: "+username);
 /* authentication just check the username and password is same*/
 if (this.username.equals(this.password)) {
   return getPrincipal(username);
  }else{
   return null;
  }
 }
 @Override
 protected String getName() {
  return username;
 }

 @Override
 protected String getPassword(String username) {
  return password;
 }

 @Override
 protected Principal getPrincipal(String string) {
  List<String> roles = new ArrayList<String>();
  roles.add("TomcatAdmin");  // Adding role "TomcatAdmin" role to the user
  log.info("Realm: "+this);
  Principal principal = new GenericPrincipal(username, password,roles);
  log.info("Principal: "+principal);
  return principal;
 }
}

This code can be compiled using Maven by executing following instructions:

1. Create a project using Maven by executing the below command.

   mvn archetype:generate -DgroupId=com.sid.realm -DartifactId=realm -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

2. Place NewRealm.java at src/main/java/com/sid/realm.
3. Edit pom.xml and add the following dependencies.

   <dependencies>
    <dependency>
     <groupId>org.apache.tomcat</groupId>
     <artifactId>tomcat-catalina</artifactId>
     <version>7.0.27</version>
     <type>jar</type>
    </dependency>
   </dependencies>

4. Execute the command below to build the package.

   mvn clean package

5. If the build is successful, it will generate realm-1.0-SNAPSHOT.jar at target directory. Place this jar at $CATALINA_HOME/lib.
6. Now make the following changes in $CATALINA_HOME/conf/server.xml, if you want to enable this realm for all the application deployed in Tomcat. If you want to enable this realm for a specific application, make the following changes in context.xml placed at application’s META-INF folder.

   <Realm className ="com.sid.realm.NewRealm"/>

7. Start Tomcat and test your application now.

Note: In the code, role is set as TomcatAdmin, make sure the same role is implemented in web.xml in your application, or you may get a 403 error.

POC is available at GitHub!