AuthZ for Standalone Programs, Thick Apps or Simple Clients

This example will show how to create a policy file and use the LdapAccessControl class in a standalone program/client. The LdapAccessControl class is a reference implementation of the UserAccessControl interface. An implementation of this interface is how the SPNEGO Library can achieve user authorization (authZ).

Summary:

The SPNEGO Library is used by a Servlet Container to autheNticate (authN) user requests.

As an option, the SPNEGO Library can be configured to perform user authorization (authZ) AFTER authN has occurred.

The authZ feature (interfaces, classes, reference implementations, etc.) is not limited to Servlet Containers and instead may be used in a custom standalone program/client.

Before Getting Started

  • Read the javadoc for the UserAccessControl interface
  • Read the javadoc for the LdapAccessControl class
  • Read the authZ section of the reference docs
  • Although SPNEGO's authZ library is not limited to Microsoft's Active Directory LDAP Server, this example assumes you have some familiarity with LDAP queries.

    It's not required but it might be helpful to briefly review the syntax/features of LDAP filters:

    https://social.technet.microsoft.com/wiki/contents/articles/5392.active-directory-ldap-syntax-filters.aspx

    The following will also have to be performed:

  • obtain domain account and password for querying the LDAP server
  • determine address and port of the LDAP server (default port is 389)
  • use JDK to compile the HelloAuthZ.java example program
  • download the latest version of the spnego library (spnego-r9.jar)
  • Finally, before we get started and once we have met the prerequisites above, we'll compile and run the LdapQueryExample.java program to confirm that we can connect to our LDAP server.

    Compile and Run LdapQueryExample.java

    Before getting started, we must first confirm that we have all we need to connect to the LDAP server. We can do this by using a simple java program that we will modify, compile, and then run. Download the LdapQueryExample.java file and open the file in your favorite source code editor.

    Also, for the filter expression, only change the OU= and DC= parts of the expression. Change it to values specific to your environment.

    Save the file.

    Compile and run LdapQueryExample.java from a command prompt.

    If things worked as expected, you should see your department and/or AD groups in the output.

    Next, modify the file so that it will query for a specific AD group that we do NOT belong to; choose an AD Group that is NOT assigned to you or perhaps choose a non-existent AD Group.

    Just as before, save, compile and run the LdapQueryExample from a command prompt.

    In the above example, notice that no results were returned since dfelix does NOT belong to the AD Group named HR.

    Creating the spnego.policy file

    Create a spnego.policy file with the following contents and place it under the C:\spnego-examples directory.

    Be sure to modify the spnego.policy file and provide values specific to your environment.

    Also, just as before, be sure to change the OU= and the DC= section of the filter.

    For the filter expression, be sure to only change the OU= and DC= parts of the expression; change it to values specific to your environment.

    A note regarding when to specify a new filter versus appending to an existing one: In the above example, filter.1 will search AD Groups in the OU=Los Angeles. If a policy also needed to include additional AD Groups e.g. OU=London, it might be more efficient from an LDAP query perspective to append to filter.1 instead of defining a filter.2 etc.

    Example where AD Groups are only differentiated by location:

    # multiple locations but only one filter
    # this method a little more query efficient
    spnego.authz.ldap.filter.1=\
    (&(sAMAccountName=%1$s)(memberOf:1.2.840.113556.1.4.1941:=CN=%2$s,OU=Groups,OU=Los Angeles,DC=athena,DC=local))\
    (&(sAMAccountName=%1$s)(memberOf:1.2.840.113556.1.4.1941:=CN=%2$s,OU=Groups,OU=London,DC=athena,DC=local))\
    (&(sAMAccountName=%1$s)(memberOf:1.2.840.113556.1.4.1941:=CN=%2$s,OU=Groups,OU=NY,DC=athena,DC=local))\
    

    instead of

    # one location for each filter
    spnego.authz.ldap.filter.1=\
    (&(sAMAccountName=%1$s)(memberOf:1.2.840.113556.1.4.1941:=CN=%2$s,OU=Groups,OU=Los Angeles,DC=athena,DC=local))\
    
    spnego.authz.ldap.filter.2=\
    (&(sAMAccountName=%1$s)(memberOf:1.2.840.113556.1.4.1941:=CN=%2$s,OU=Groups,OU=London,DC=athena,DC=local))\
    
    spnego.authz.ldap.filter.3=\
    (&(sAMAccountName=%1$s)(memberOf:1.2.840.113556.1.4.1941:=CN=%2$s,OU=Groups,OU=NY,DC=athena,DC=local))\
    

    In Java property files, the # character signifies a comment line and the \ character is an escape character.

    The \ character allows property names and property values to be treated as being on one line.

    Creating the HelloAuthZ.java file

    Download and open the HelloAuthZ.java file in your favorite source code editor.

    Replace the values in the file with the values for your environment.

    Save the file, and then compile and run from a command prompt.

    Be sure to include the spnego-r9.jar when compiling and running the HelloAuthZ.java file.

    If things worked as expected, you should see the following output:

    Notice from the output which attributes returned true/false and which resources returned true/false.

    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.

    The SPNEGO Library can be configured via the web.xml file, and optionally along with the spnego.policy file, to use the LdapAccessControl class as the means by which web browser requests undergo user authorization (authZ) checks.

    Getting Information About the User

    Lastly, the SPNEGO Library can obtain user information such as first name, last name, email, active directory groups, department, etc. and make that user information available to your web application or your standalone application via the getUserInfo method.

    Take a look at the get user group info from LDAP guide for more information.

    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.