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.

Active Directory Realm

The ActiveDirectoryRealm will query your Active Directory domain for a user by the string name type of the supplied username and retrieve all the necessary information, e.g., his/her security groups.

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

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:

Tip: Never rely on hard-coded hostnames, use my ActiveDirectoryLdapDnsProvider to auto-locate servers for Active Directory domains via DNS.

[…]
  <!-- 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 chasing 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.

Important: If you intend to authenticate with the SSLAuthenticator your client certificates must contain a subject alternative name type of 0 (otherName) with the type OID of 1.3.6.1.4.1.311.20.2.3 (msUPN).

Using Security Groups from Active Directory

The ActiveDirectoryRealm will populate all roles as SID strings for the given principal by default. 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 or use other role formats, but the SID see extended capabilities of this realm in the Javadoc.

Using a Realm for Testing Purposes

In most cases you are not able to modify Active Directory entries easily (usually admins can), e.g., adding and removing groups or their members. Therefore, you can use the 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 Active Directory as a user repository (e.g. database or another directory server) and can still make use of this library. Extend Tomcat's RealmBase class and override any of these methods:

Next Step

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