Configuring JBoss : Configuring Java applications to use Active Directory
 
Configuring Java applications to use Active Directory
The sample applications are preconfigured to use the Active Directory for authentication. In this section, you modify your web application’s context to authenticate users against their Active Directory account.
Centrify for Java applications provides a customized JAAS realm for JBoss applications. Java EE applications that are configured to use the standard BASIC or FORM authentication methods use the Centrify for Java applications JAAS login module to authenticate users in Active Directory.
In addition to these standard Java EE authentication methods, you can configure applications to use Kerberos or NTLM authentication by using the Centrify for Java applications SPNEGO authenticator. The SPNEGO authenticator allows transparent authentication using Kerberos tickets when users access an application using a Web browser, such as Internet Explorer or Firefox, that supports the Negotiate protocol and SPNEGO tokens.
When the Web browser requests service from the Web server, the Web server responds with a denial of service and a request that the browser negotiate authentication through HTTP. The browser then contacts the Kerberos Ticket Granting Service to get a service ticket and returns the ticket in a SPNEGO token to the Web server for authentication.
Because this authentication occurs between the browser, acting on the user’s behalf, and the Web server, users can access services without being prompted to provide their login credentials. If the user’s browser doesn’t support the Negotiate protocol and SPNEGO token, the Web server will attempt to authenticate the user using the next most secure authentication scheme supported.
To use Centrify for Java applications and Active Directory, you need to manually configure several application-specific files to use the Centrify for Java applications login module and JAAS realm.
Configuring individual JBoss applications to use Centrify for Java applications and Active Directory involves the following steps:
Configuring the application context
Configuring the security domain in jboss-web.xml
Configuring the authentication method in web.xml
Configuring the reprompt servlet in web.xml
Defining a servlet filter in web.xml
Configuring the security constraints in web.xml
Modifying settings in centrifydc.xml
Configuring the application context
For any type of authentication using Active Directory, applications must be configured to use the Centrify for Java applications JAAS realm. The procedure is different depending upon your JBoss version.
For JBoss before version 7.0
    1 Create the file context.xml.
    Navigate to the application’s Web application archive (WAR) WEB-INF directory. If the file context.xml does not already exist create it. If it’s already there, go to the next step.
    2 Open context.xml to specify Centrify for Java applications as the context for the application
    After you open the file add the following lines:
    <Context>
    <Valve className="com.centrify.dc.tomcat.ContextValve"/>
    </Context>
    3 Save your changes and close the file.
For JBoss version 7.0 and later
    1 Create the file jboss-web.xml.
    Navigate to the application’s Web application archive (WAR) WEB-INF directory. If the file jboss-web.xml does not already exist create it. If it’s already there, go to the next step.
    2 Open jboss-web.xml to specify Centrify for Java applications as the context for the application
    After you open the file add the following lines:
    <valve>
    <className>com.centrify.dc.tomcat.ContextValve</classname>
    </valve>
    3 Save your changes and close the file.
Configuring the security domain in jboss-web.xml
For each application, you need to modify the jboss-web.xml file to use the Centrify for Java applications JAAS realm as the security-domain.
To modify the security domain for an application:
    1 Create the file jboss-web.xml.
    Navigate to the application’s Web application archive (WAR) WEB-INF directory. If the file jboss-web.xml does not already exist create it. If it’s already there, go to the next step.
    2 Open jboss-web.xml and set JAAS realm as security domain
    Locate the <jboss-web> section. If you do not have a <jboss-web> add the following lines to set the Centrify for Java applications JAAS realm as the security-domain:
    <jboss-web>
    <security-domain>java:/jaas/CentrifyDC</security-domain>
    </jboss-web>
    If you already have a <jboss-web> section, just add the <security-domain> line.
    3 Save your changes and close the file.
Configuring the authentication method in web.xml
For each application, you need to define an authentication method in the application’s web.xml file.
To set the authentication method in the application’s web.xml:
    1 Open the application’s web.xml file.
    2 Set the <auth-method> setting in the <login-config> section to BASIC, FORM or SPNEGO.
Configuring applications to use BASIC authentication
The BASIC authentication method is a standard Java EE authentication method that prompts for a user name and password.
To configure the <login-config> section to use BASIC authentication:
    ...
    <login-config>
    <auth-method>BASIC</auth-method>
    <realm-name>Realm</realm-name>
    </login-config>
    ...
Configuring applications to use FORM authentication
The FORM authentication method is a standard Java EE authentication method that displays a form for users to provide a user name and password.
To configure the <login-config> section to use FORM authentication:
    ...
    <login-config>
    <auth-method>FORM</auth-method>
    <realm-name>Realm</realm-name>
    <form-login-config >
    <form-login-page>/login.jsp</form-login-page>
    <form-error-page>/accessdenied.jsp</form-error-page>
    </form-login-config>
    </login-config>
    ...
Configuring applications to use SPNEGO authentication
The SPNEGO authenticator is a custom authenticator that supports Kerberos and NTLM authentication to provide silent authentication for users with valid credentials.
To configure the <login-config> section to use the SPNEGO authenticator:
    ...
    <login-config>
    <auth-method>SPNEGO</auth-method>
    <realm-name>CENTRIFYDC</realm-name>
    </login-config>
    ...
Configuring the reprompt servlet in web.xml
With SPNEGO authentication you can also modify web.xml to let the user authenticate using a different authentication scheme if an authentication scheme results in an authorization failure for the application. For example, if a user has successfully authenticated using via Kerberos but failed to get authorization for an application, the application can allow the user to re-try authentication using NTLM or BASIC as a different user. This is done by adding a reprompt servlet in web.xml as in the example below.
NoteIf there are other servlets in your web application be sure to follow the Java EE specification for web.xml when adding this servlet.
    <servlet>
    <servlet-name>reprompt</servlet-name>
    <servlet-class>com.centrify.dc.wbase.Reprompt</servlet-class>
    </servlet>
    <servlet-mapping>
    <servlet-name>reprompt</servlet-name>
    <url-pattern>/reprompt</url-pattern>
    </servlet-mapping>
To allow a user to reprompt, you also need to map the default HTTP 403 response for authorization failure to the reprompt servlet using the <error-page> element as in the example below. This mapping is usually placed after the <welcome-file> element. Check the Java EE specification for web.xml for more information.
    <error-page>
    <error-code>403</error-code>
    <location>/reprompt</location>
    </error-page>
Without the reprompt servlet, users receive a 403 Forbidden HTTP response if they are authenticated but not authorized to access the application. If you want users to receive this response, do not add the reprompt servlet as described in this section.
Defining a servlet filter in web.xml
Servlet filters enable you to define the steps that incoming requests must go through before reaching a servlet, JSP, or static resource. To intercept authentication requests, you should define a servlet filter for Centrify for Java applications and identify the URLs to which the filter applies.
The identity broker service servlet filter sets the authenticated user's attributes such as UPN and groups, in HTTP headers as configured in centrifydc.xml. If you do not use or need the authenticated user's attributes in your application, you do not have to add the identity broker service servlet filter.
For each application, define a servlet filter similar to the following in the application’s web.xml file:
    ...
    <filter>
    <filter-name>dcfilter</filter-name>
    <filter-class>com.centrify.dc.wbase.DCFilter</filter-class>
    </filter>
    <filter-mapping>
    <filter-name>dcfilter</filter-name>
    <url-pattern>/*</url-pattern>
    </filter-mapping>
    ...
Configuring the security constraints in web.xml
For each application, you need to modify the web.xml file to define the security constraints for the application. Edit the <security-constraint> and <auth-constraint> sections as appropriate to your application. For example:
    ...
    <security-constraint>
    <web-resource-collection>
    <web-resource-name>ProtectedResource</web-resource-name>
    <url-pattern>/*</url-pattern>
    <http-method>GET</http-method>
    <http-method>POST</http-method>
    </web-resource-collection>
    <auth-constraint>
    <role-name>user</role-name>
    </auth-constraint>
    </security-constraint>
    ...
Modifying settings in centrifydc.xml
After you have configured an application to use Centrify for Java applications for authentication and authorization services through Active Directory, you can customize settings in the centrifydc.xml file to suit the individual JBoss application. By placing this file in an application’s WEB-INF directory, you can control these custom settings on an application-by-application basis.
NoteTo customize the content of centrifydc.xml file for all Web applications running on a JBoss server, make the content changes and then copy the file to the director $JBOSS_HOME/server/server_instance/conf
To customize the centrifydc.xml file for an application:
    1 Copy the /usr/share/centrifydc/java/templates/centrifydc.xml template file to the application’s WEB-INF directory. For example:
    cd $JBOSS_HOME/server/myserver/deploy/mysample.war/WEB-INF
    cp /usr/share/centrifydc/java/templates/centrifydc.xml .
    Note To customize the centrifydc.xml file for all web applications, copy it to the following directory:
$JBOSS_HOME/server/server_instance/conf
For example:
    $JBOSS_HOME/server/myserter/conf
    2 Open the application’s centrifydc.xml file with a text editing tool. For example:
    vi centrifydc.xml
    3 Modify the default settings in the file to suit the application. For example, modify the <RoleMapping> element of the file to define how JBoss roles and users map to Active Directory groups and users.
    For applications that use the SPNEGO authenticator, you can also modify the centrifydc.xml file to specify the authentication schemes supported.
Modifying the role mapping for JBoss and Active Directory
To define how JBoss roles map to Active Directory groups:
    1 Open the application’s centrifydc.xml file with a text editing tool and locate the <RoleMapping> element.
    2 Set the <Role name=”Role1”> attribute to the name of the appropriate JBoss application role.
    For example, if you have an application that requires a user to be in the admin role, you can map an Active Directory group to this role. To map an Active Directory group to the admin role, you would set the Role name attribute to:
    <Role name="admin"
    You can include as many role names as you need. Each role name can be mapped to one or more groups and one or more specific users.
    3 Set the group="domain/path/groupname" attribute to one or more Active Directory group names.
    If specifying multiple group names, use a semi-colon to separate the groups. In specifying the Active Directory group name, you must use the full name for the group. For example, if the domain is arcade.com and you have an Organizational Unit called Contractors that contains the WebAdmins group:
    arcade.com/Contractors/WebAdmins
    4 Set the user="username" attribute to one or more Active Directory user names you want to grant access to, if needed.
    If specifying multiple user names, use a semi-colon to separate the users. If all users in an Active Directory group are allowed access, you set this attribute to all, for example, user=”*”, or you can remove this attribute from the Role definition.
    For example, to map the JBoss role of “admin” to the Active Directory group “WebAdmins” in the arcade.com domain, you would edit the following section in the application’s centrifydc.xml file:
    <centrifydc>
    ...
    <RoleMapping separator=”;”>
    <Role name="admin" group=”arcade.com/Users/WebAdmins”/>
    </RoleMapping>
    ...
    </centrifydc>
    5 Save your changes and close the file.
NoteIf you don’t specify a <RoleMapping> section in the centrifydc.xml file, the role name in the JBoss application must be the same as the full Active Directory group name for authentication to succeed.
In addition to the <RoleMapping> section, you can also use the centrifydc.xml file to define other aspects of your environment. For more information about the other elements in the centrifydc.xml file, see Understanding the centrifydc.xml file.
For further examples of how to edit the web.xml and centrifydc.xml files, see the Centrify for Java applications sample applications for JBoss installed in the $JBOSS_HOME/server/myserver/deploy/centrifydc-samples.ear file.
Modifying the authentication schemes accepted for SPNEGO
When you configure a JBoss application to use the SPNEGO authenticator, you can specify the authentication schemes you want to support. If the client browser that requests service doesn’t support Kerberos authentication or SPNEGO tokens, the Web server will try to authenticate using the other supported authentication schemes until it finds an authentication scheme that the browser supports.
The authentication schemes supported when using SPNEGO are Negotiate, NTLM, and Basic. With the Negotiate authentication scheme the browser will try to authenticate the user using Kerberos by getting a Kerberos service ticket for the user. If it fails to get a Kerberos ticket it will use NTLM to authenticate the user.
You can customize the authentication schemes supported for any Web application by modifying the <enableAuthSchemes> element in the application’s centrifydc.xml file. For example, if you want to remove support for BASIC authentication for an application, you can modify the <enableAuthSchemes> element in that application’s WEB-INF/centrifydc.xml file to look like this:
<enableAuthSchemes>Negotiate,NTLM</enableAuthSchemes>
For information about other settings you can make in the centrifydc.xml file, see Understanding the centrifydc.xml file.
Once you complete these steps, you can configure the application to use FORM, BASIC, or SPNEGO authentication and have the user's identity authenticated through Active Directory.
For further examples of how to edit the web.xml and centrifydc.xml files, see the Centrify for Java applications sample application centrifydc-samples.ear for JBoss in the /user/share/centrifydc/java/web/sampleapps/jboss directory on Linux- or UNIX-based systems or the
C:\Program Files\Centrify\DirectControl\\web\sampleapps\jboss
directory on Windows-based systems.