Retrieve First Name, Last Name, AD Groups, Email using Authorization Service

This example will show how your web application or standalone application can automatically obtain user information that is included as part of the authentication and authorization process.

Summary:

In addition to authenticating a user or perhaps after checking a user's authorization credentials, applications need to display the user's first name, last name, or email somewhere on the application. Perhaps, the application also needs to know or needs to display the active directory groups or email list the user belong to.

The SPNEGO Library's getUserInfo method is how an application can obtain user information from the authentication and authorization service.

User information that should be available to the application is specified in the web.xml file or the spnego.policy file. For example, to make available the user's email address or department as specified in Active Directory, the application sets a property value with the list of user attributes that the application is interested in knowing. e.g.

spnego.authz.user.info=mail,department,memberOf,displayName

Before Getting Started

In the authZ for standalone apps example, a spnego.policy file was modified with parameter values that are specific to your environment. This guide will use that modified spnego.policy file from that example.

Be sure to complete that example before proceeding with this guide.

We will only make two changes to that spnego.policy file. The change is to specify which user attributes we are interested in and to specify the LDAP query/search filter that the authorization framework should use.

To specify attributes in the spnego.policy file, add the following:


# case-sensitive
spnego.authz.user.info=mail,department,memberOf,displayName
spnego.authz.ldap.user.filter=(&(sAMAccountType=805306368)(sAMAccountName=%1$s))

Web-based applications may specify the attributes in the spnego.policy file or the web.xml file:


<init-param>
  <param-name>spnego.authz.user.info</param-name>
  <param-value>mail,department,memberOf,displayName</param-value>
</init-param>
<init-param>
  <param-name>spnego.authz.ldap.user.filter</param-name>
  <param-value><![CDATA[(&(sAMAccountType=805306368)(sAMAccountName=%1$s))]]></param-value>
</init-param>

Notice that for web-based configuration, the CDATA directive is needed since the filter contains special xml tokens.

Compile and Run LdapUserInfoExample.java

To determine what user info attributes are available to the application, we'll query the user store (in this example the user store is Active Directory) to get a list of user attributes.

Download the LdapUserInfoExample.java file and place it under your C:\spnego-examples\ folder.

This folder should already contain the the spnego-r9.jar file, the spnego.policy file and the LdapQueryExample.java file that we created from the authZ for standalone apps example.

Open the LdapUserInfoExample.java file in your favorite source code editor.

Modify the following lines with values specific to your environment.


env.put(Context.SECURITY_PRINCIPAL, "Zeus");
env.put(Context.SECURITY_CREDENTIALS, "Z3usP@55");
env.put(Context.PROVIDER_URL, "ldap://athena.local:389");
String deecee = "DC=athena,DC=local";

String username = "dfelix";

Change only the lines above and with the values you used in your LdapQueryExample.java file.

Compile LdapUserInfoExample.java from a command prompt by executing the following command:


C:\spnego-examples>javac -cp .;spnego-r9.jar LdapUserInfoExample.java

Run LdapUserInfoExample by executing the following command:


C:\spnego-examples>java -cp .;spnego-r9.jar LdapUserInfoExample

The returned list of attributes is what is available to us when specifying a list of user info/attributes to the spnego.authz.user.info property.

Note that the list above are attributes for a specific user. It may be the case that a particular attribute does not exist for all users and instead only exists for some users.

Most of the common attributes are usually available to all users.

Modifying the spnego.policy file

Edit the spnego.policy file by adding the following properties:


# case-sensitive
spnego.authz.user.info=mail,department,memberOf,displayName
spnego.authz.ldap.user.filter=(&(sAMAccountType=805306368)(sAMAccountName=%1$s))

Save and close the file.

Note that the user attribute names are case-sensitive and hence we must use the same mixed-case in our HelloUserInfo.java file.

Compile and Run HelloUserInfo.java

Download the HelloUserInfo.java file and place it under your C:\spnego-examples\ folder.

Open the HelloUserInfo.java file in your favorite source code editor and modify the contents with values specific to your environment.

Just as with the other .java files, compile and run HelloUserInfo.java from a command prompt.

Be sure to include the spnego library in the command line when compiling and running HelloUserInfo.java

Take a look at the contents of HelloUserInfo.java file again and notice that the getInfo method always returns a list.

Un-comment the lines that contain the memberOf attribute, re-compile, and run again to see the Active Directory Groups that has been directly assigned to the user.

Active Directory stores AD Groups and Email Distribution List info in the memberOf attribute.

Notice that this attribute is mixed-case. Be sure to use the same mixed-case in the spnego.policy file and in the .java files and the .jsp files.

Web-based Applications

If your application is a web-based application running in a servlet container, take a look at the enable authZ with LDAP guide. The guide will illustrate changes needed to the web.xml file as well as provide an overview of the SpnegoAccessControl interface.

Once you've completed that guide, add the following to your web.xml file:


<init-param>
  <param-name>spnego.authz.user.info</param-name>
  <param-value>mail,department,memberOf,displayName</param-value>
</init-param>
<init-param>
  <param-name>spnego.authz.ldap.user.filter</param-name>
  <param-value><![CDATA[(&(sAMAccountType=805306368)(sAMAccountName=%1$s))]]></param-value>
</init-param>

Download or create a hello_user_info.jsp file and modify the contents with values specific to your environment


<%@ page import="net.sourceforge.spnego.*" %>

<%
    SpnegoAccessControl accessControl = null;
    UserInfo userInfo = null;
    if (request instanceof SpnegoAccessControl) {
        accessControl = (SpnegoAccessControl) request;
        userInfo = accessControl.getUserInfo();
    }
%>

<br >true = <%= userInfo.hasInfo("department") %>
<br >IT = <%= userInfo.getInfo("department") %>

<br />Felix, Darwin = <%= accessControl.getUserInfo().getInfo("displayName").get(0) %>

Testing hello_user_info.jsp

Place the hello_user_info.jsp file on your app server, open a web browser and go to that page.

If everything works as expected, the output should look similar to the screenshot below.

This guide used the LdapAccessControl class included with the SPNEGO Library. The LdapAccessControl class is a reference implementation of the UserAccessControl interface.

If you would like to query your own RDBMS, xml file, REST Service, etc. to get user information, instead of LDAP, and you would like the SPNEGO Library to use your own custom access control class, simply implement the methods defined in the UserAccessControl interface.

Take a look at the javadocs of the UserAccessControl interface for additional details as well as the source code for the LdapAccessControl class to get some inspiration on how to implement your own class.

Next, use the spnego.authz.class property to tell the SPNEGO Library to use your class instead of the LdapAccessControl class.

Links:
pre-flight checklist
install guide - tomcat
install guide - jboss
install guide - glassfish
enable authZ with LDAP
get user group info from LDAP
reference docs
api docs
download

Troubleshooting:
HelloKDC.java
hello_spnego.jsp
HelloKeytab.java
hello_delegate.jsp
SpnegoHelloClient.java
ExampleSpnegoAuthenticatorValve.java

Examples:
create keytab for client
create keytab for app server
credential delegation
protected SOAP Web Service
tomcat authenticator valve
jboss authenticator valve
authZ for standalone apps
protecting edit button on page

Licensing:
GNU LGPL


© 2009 Darwin V. Felix. All rights reserved.