Reference Documentation

Configuring web.xml for AutheNtication (authN)

Servlet Filter init params for (authN). See example web.xml in Tomcat Install Guide.

Property Req/Opt Description
spnego.krb5.conf Required
  • Valid value: Path to krb5.conf file (relative or absolute path)
  • Take a look at the pre-flight documentation for guidance on how to create this file.
  • See the Tomcat Install Guide for an example configuration.
    		•
    spnego.login.conf Required
  • Valid value: Path to login.conf file (relative or absolute path)
  • Take a look at the pre-flight documentation for guidance on how to create this file.
  • See the Tomcat Instal Guide for an example configuration.
    		•
    spnego.login.server.module Required
  • Valid value: value specified in login.conf file for server
  • Take a look at the pre-flight documentation for guidance on how to create this file.
  • See the Tomcat Instal Guide for an example configuration.
    		•
    spnego.login.client.module Required
  • Valid value: value specified in login.conf file for client
  • Take a look at the pre-flight documentation for guidance on how to create this file.
  • See the Tomcat Instal Guide for an example configuration.
    		•
    spnego.preauth.username Required
  • Valid value: Windows NT Domain Account.
  • Take a look at the pre-flight documentation for guidance on how to create this account.
    		•
    spnego.preauth.password Required
  • Valid value: Pre-auth Domain Account Password.
  • Should set password to never expire.
    		•
    spnego.allow.basic Required
  • Valid values are true or false.
  • Offer HTTP Basic Authentication in addition to Kerberos Authentication.
  • Consider this option if an HTTP client cannot negotiate SPNEGO token(s).
  • Set this value to false if you only allow Kerberos Authentication.
    		•
    spnego.allow.unsecure.basic Required
  • Valid values are true or false.
  • With respect to Basic Authentication, specify if HTTPS is required. If Basic Authentication is not allowed, this operation is a no-op.
  • Set this value to false if you do not want to offer Basic Authentication for non-SSL connections.
    		•
    spnego.allow.localhost Optional
  • Valid values are true or false.
  • Default is false.
  • Skip authentication if requests are coming from localhost.
  • Requests that originate from localhost will not require authentication.
  • Set this value to true if you run a local instance of the server and you want to avoid having to register an SPN for your workstation.
  • Set this value to false if requests from localhost should be rejected.
    		•
    spnego.prompt.ntlm Required
  • Valid values are true or false.
  • The SPNEGO Filter does not support NTLM.
  • Set this value to true if clients who wish to authenticate via NTLM should be offered Basic Authentication (assuming spnego.allow.basic=true).
  • Set this vaue to false if NTLM Authentication should be rejected.
    		•
    spnego.allow.delegation Optional
  • Valid values are true or false.
  • Default is false
  • IE and AD allow delegation by default
  • See DelegateServletRequest docs for more info
  • Set this value to true to enable the filter for delegation
    		•
    spnego.exclude.dirs Optional
  • Valid Values are a list of URL paths starting at the context root that should NOT undergo authentication (authN).
  • e.g. /images,/css
  • e.g. /public/news,/js,/assets/global/release
  • Default is to authN every request.
  • Introduced in spnego-r9.jar
    		•
    spnego.logger.level Optional
  • Valid values are 1 thru 7.
  • Default specified by container
  • 1 = FINEST; 7 = SEVERE
  • Set value to 1 for debugging/verbose logging.
    		•

    A Servlet Filter resource mapping can either be defined at the Container level or at the web application level. The example in the Tomcat Install Guide has the mapping defined at the Container level.

    Here's an example mapping for .jsp files:

    <filter-mapping>
    <filter-name>SpnegoHttpFilter</filter-name>
    <url-pattern>*.jsp</url-pattern>
</filter-mapping>

    And here's an example mapping for .cfm files:

    <filter-mapping>
    <filter-name>SpnegoHttpFilter</filter-name>
    <url-pattern>*.cfm</url-pattern>
</filter-mapping>

    The location of the filter-mapping in the web.xml is important. The SPNEGO Filter mapping must be defined before any other mapping. It must be defined first/executed first.

    Optional: Addtional Configuration in web.xml to enable AuthoriZation (authZ)

    Append the authZ init params to the existing authN params in the Servlet Filter definition.
    spnego-r9.jar required for authZ. See example web.xml in the enable authZ with LDAP guide.

    Property Req/Opt Description
    spnego.authz.class *Optional
  • *To enable the AuthZ option, MUST specify java class
  • Valid Value is a class that implements the UserAccessControl interface.
  • e.g. LdapAccessControl
  • The LdapAccessControl class is a reference implementation that is bundled with the SPNEGO Library.
  • Introduced in spnego-r9.jar
    		•
    spnego.authz.ldap.url *Optional
  • *To enable the AuthZ option, MUST specify LDAP URL
  • Valid Value is a URL to the LDAP server.
  • e.g. ldap://athena.local:389
  • e.g. ldaps://athena.local:636
  • Introduced in spnego-r9.jar
    		•
    spnego.authz.ldap.filter.i *Optional
  • *To enable the AuthZ option, MUST specify expression
  • Valid Value is an LDAP Query/Filter expression.
  • Index i starts at one (1) and the maximum number of filter expressions is 200.
  • Take a look at the enable authZ with LDAP guide for guidance. Additional information can be found in the javadoc for the LdapAccessControl class, the UserAccessControl interface, and the SpnegoAccessControl interface.
  • Introduced in spnego-r9.jar
    		•
    spnego.authz.policy.file Optional
  • Valid Value: Path to a spnego.policy file (relative or absolute path).
  • If no path provided, you must specify policies in the web.xml file.
  • Take a look at the enable authZ with LDAP guide for guidance as well as the authZ for standalone apps example.
  • Additional information can be found in the javadoc for the LdapAccessControl class.
  • Introduced in spnego-r9.jar
    		•
    spnego.authz.sitewide Optional
  • Valid Value is one of the user-defined resource labels.
  • Resource labels are specified via the spnego.authz.resource.name.i parameter.
  • e.g. site-wide-authZ
  • Default is that authZ will NOT be automatically applied accross the entire site.
  • The value MUST be a user-defined resource label and NOT an attribute name.
  • Introduced in spnego-r9.jar
    		•
    spnego.authz.403 Optional
  • Valid Value is a path starting at the context root to a custom page that should be displayed if a user is denied authZ access.
  • e.g. /403.html
  • e.g. /my-403-handler.jsp
  • Default is to let the user's Web Browser define how an HTTP Status code of 403 Forbidden should be handled.
  • Introduced in spnego-r9.jar
    		•
    spnego.authz.ttl Optional
  • Valid Value is a number specifying in minutes how long an LDAP query result should stay in the cache.
  • Default is 20 minutes.
  • Parameter is used to minimize trips/queries to the LDAP Server.
  • Introduced in spnego-r9.jar
    		•
    spnego.authz.resource.name.i Optional
  • Valid Value is a user-defined label/name.
  • e.g. edit-button
  • e.g. site-wide
  • Index i starts at one (1) and the maximum number of resource labels is 200.
  • Take a look at the enable authZ with LDAP guide for guidance as well as the authZ for standalone apps example.
  • Introduced in spnego-r9.jar
    		•
    spnego.authz.resource.type.i Optional
  • Required if spnego.authz.resource.name.i is specified.
  • Valid Values are has or any.
  • Index i must match each corresponding index in each spnego.authz.resource.name.i parameter.
  • Introduced in spnego-r9.jar
    		•
    spnego.authz.resource.access.i Optional
  • Required if spnego.authz.resource.name.i is specified.
  • Valid Value is a list of attributes that back the resource.
  • e.g. IT,Marketing,Los Angeles,NY Users,Biz Dev
  • e.g. File Share Access,London Users,Accounting
  • Index i must match each corresponding index in each spnego.authz.resource.name.i parameter.
  • Introduced in spnego-r9.jar
    		•
    spnego.authz.unique Optional
  • Valid Values are true or false.
  • Default is true.
  • Take a look at the enable authZ with LDAP guide for guidance. Additional information can be found in the javadoc for the LdapAccessControl class, the UserAccessControl interface, and the SpnegoAccessControl interface.
  • A value of true will throw an exception if the uniqueness property is violated.
  • A value of false will allow attribute names to exist in two or more attribute sets.
  • Introduced in spnego-r9.jar
    		•
    spnego.authz.ldap.username Optional
  • Required if the SPNEGO Library is being used in a standalone java program/thick client.
  • Valid Value is a domain user/service account.
  • Default is to use the spnego.preauth.username IF the filter is NOT configured to use a Keytab file.
  • Take a look at the authZ for standalone apps example.
  • Introduced in spnego-r9.jar
    		•
    spnego.authz.ldap.password Optional
  • Required if the SPNEGO Library is being used in a standalone java program/thick client.
  • Valid Value is password for the domain user/service account.
  • Default is to use the spnego.preauth.password IF the filter is NOT configured to use a Keytab file.
  • Take a look at the authZ for standalone apps example.
  • Introduced in spnego-r9.jar
    		•
    spnego.authz.ldap.deecee Optional
  • Required if the SPNEGO Library is being used in a standalone java program/thick client.
  • Valid Values is the base syntax of an LDAP Query/Filter when specifying the DC portion.
  • e.g. DC=ATHENA,DC=LOCAL
  • In this example, take a look at the corresponding krb5.conf file to figure out the naming pattern.
  • Default is computed automatically when using the SpnegoHttpFilter.
  • Introduced in spnego-r9.jar
    		•
    spnego.authz.ldap.factory Optional
  • Valid Values are defined by Java's java.naming.factory.initial property.
  • Default is Java's com.sun.jndi.ldap.LdapCtxFactory.
  • Introduced in spnego-r9.jar
    		•
    spnego.authz.ldap.authn Optional
  • Valid Values are defined by Java's java.naming.security.authentication property.
  • Default is Java's Simple.
  • Introduced in spnego-r9.jar
    		•
    spnego.authz.ldap.pool Optional
  • Valid Values are defined by Java's com.sun.jndi.ldap.connect.pool property.
  • Default is true.
  • Introduced in spnego-r9.jar
    		•

    Most of the above authZ init params are specific to the reference implementation, LdapAccessControl class, bundled with the SPNEGO Library (spnego-r9.jar)

    A custom implementation is free to use any user information store (e.g. RDBMS, xml file, REST service, etc.) however the custom implementation MUST implement the UserAccessControl interface

    Optional: Getting User Information

    spnego.authz.user.info Optional
  • Valid Value is one ore more user attributes.
  • e.g. mail,memberOf,department,displayName
  • The available user attributes depends on your user store
  • Take a look at the get user group info from LDAP guide.
  • Introduced in spnego-r9.jar
    		•
    spnego.authz.ldap.user.filter Optional
  • Required if the spnego.authz.user.info is specified.
  • Valid Value is an LDAP Query/Filter expression.
  • The filter expression depends on your user store.
  • Take a look at the get user group info from LDAP guide.
  • Introduced in spnego-r9.jar
    		•

    Take a look at the get user group info from LDAP guide for additional information on how to obtain and use the user information in your web-application or your standalone application.

    Links:
    pre-flight checklist
    install guide - tomcat
    install guide - jboss
    install guide - glassfish
    install guide - spring boot 2.x
    install guide - spring boot 3.x
    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.