Maven

Choosing and Using Realms

After the authenticator has established a user's identity, it's time to search for it. Usually, the ActiveDirectoryRealm will do, but for testing purposes you will find the default UserDatabaseRealm very handy.

Tip
I strongly recommend to try the UserDatabaseRealm first, you'll see whether the authenticator works at all. If it does, go on to the ActiveDirectoryRealm.

The Active Directory Realm

The ActiveDirectoryRealm will query your Active Directory for a user by his/her implicit UPN and retrieve all the necessary information, e.g., his/her security groups.

It requires two steps of setup: First, you will need to configure a DirContextSourceFactory with the parameters of your Active Direcory. Second, the realm itself pointing to that Active Directory.

Configuring a Directory Context Source Factory

Please read the documentation of the DirContextSourceFactory on how to configure it in detail. Here is a minimal working configuration:

[…]
  <!-- Add this -->
  <Resource name="my-active-directory" type="net.sf.michaelo.dirctxsrc.DirContextSource"
    factory="net.sf.michaelo.dirctxsrc.DirContextSourceFactory"
    urls="ldap://ad.example.com" auth="gssapi" loginEntryName="my-client" />
[…]

Referral Handling

In general, you should pick LDAP URLs which avoid any referral incursion because it amplifies execution in space and time. You are highly recommended using the Global Catalog (port 3268) only. More details on how this realm deals with referrals can be found in the Javadoc.

Configuring the Realm

Now we need to wire that to the realm. Open or create your app's context.xml and add:

<Context>
[…]
  <!-- Add this -->
  <Realm className="net.sf.michaelo.tomcat.realm.ActiveDirectoryRealm"
    dirContextSourceName="my-active-directory" localDirContextSource="true|false" />
[…]
</Context>

Provide the dirContextSourceName you have configured for the DirContextSource above and hint whether this directory context source has been configured locally or globally. Default value is false.

You have successfully configured the ActiveDirectoryRealm in your webapp. It is now ready to use.

Authenticated Principal

After successful authentication and retrieval, this realm will create an ActiveDirectoryPrincipal with several attributes. Refer to the Javadoc for details.

Using Security Groups from Active Directory

By default the ActiveDirectoryRealm will populate all roles as SID strings for the given principal. While it might not look convenient in the first place, it adds benefit when security groups are moved from/to other domains, the SID history is completely retained. I.e., your application will continue to work even with the old SID. If you would like to map SIDs to developer-friendly role names, checkout the PropertiesRoleMappingListener.

Using a Realm for Testing Purposes

Usually, you are not able to modify Active Directory entries easily (usually admins can), e.g., adding and removing groups. Therefore, you can use default UserDatabaseRealm, fiddle quickly with users and roles to test your application.

Follow the Tomcat documentation and configure a tomcat-users.xml file with the according resource declaration. Type in the user and group principals, but leave the passwords out.

Open or create your app's context.xml and add:

<Context>
[…]
  <!-- Add this -->
  <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
    resourceName="UserDatabase" stripRealmForGss="false" />
[…]
</Context>

You have successfully configured the UserDatabaseRealm in your webapp. It is now ready to use.

Alternative Realm Implementations

If you are not using the Active Directory as a user repository (e.g. database or another directory server) and can still make use of this library. Extend the Tomcat's default RealmBase class and override the protected method getPrincipal(GSSName, GSSCredential).

The Next Step

You have freed your users from typing usernames and passwords over and over again. Go on and try your new SSO setup.