Choosing and Using Realms

After the authenticator has established a user's identity, it's time to retrieve it. Usually, the ActiveDirectoryRealm and PacDataActiveDirectoryRealm will do, but for testing purposes you will find the 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 with the productive realms.

Active Directory Realm

The ActiveDirectoryRealm will query your Active Directory via LDAP 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. 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:

Tip: Never rely on hard-coded hostnames, use my ActiveDirectoryLdapDnsProvider to auto-locate servers for Active Directory 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 0 (otherName) with the type OID 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.

PAC Data Active Directory Realm

The PacDataActiveDirectoryRealm will process MS-PAC data from your Active Directory for a user and retrieve all the necessary information, e.g., his/her security groups.

It requires a single-step setup.

Note: Unsure about this realm? Use the Krb5AuthzDataDumpingActiveDirectoryRealm to collect authorization data and analyze it with the Krb5AuthzDataDumpPrinter.

Configuring the Realm

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

<Context>
[…]
  <!-- Add this -->
  <Realm className="net.sf.michaelo.tomcat.realm.PacDataActiveDirectoryRealm"
    loginEntryName="a-login-entry" />
[…]
</Context>

Provide the loginEntryName you have configured for the SpnegoAuthenticator before.

You have successfully configured the PacDataActiveDirectoryRealm 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

The PacDataActiveDirectoryRealm 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.

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.