Red Hat Training

A Red Hat training course is available for JBoss Enterprise Application Platform Common Criteria Certification

Chapter 7. Authentication

The following examples describe ways you can use application policies in a security domain.
For clarity, only the authentication policy is declared in the examples, however you can include <authorization>, and <mapping> elements in the same <application-policy>. Refer to Section 6.1, “<authentication>” for detailed information about the <authentication> element.

Example 7.1. Single login stack authentication policy

This example describes a simple security domain configuration named jmx-console that uses a single login module, UsersRolesLoginModule (refer to Section 12.1.5, “UsersRolesLoginModule”).
The login module is supplied user and role properties from files in the jboss-as/server/$PROFILE/conf/props directory.
In this instance, the <login-module> must succeed or authentication fails. 
<application-policy xmlns="urn:jboss:security-beans:1.0 name="jmx-console">
   <authentication>
       <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" flag="required">
          <module-option name="usersProperties">props/jmx-console-users.properties</module-option>
          <module-option name="rolesProperties">props/jmx-console-roles.properties</module-option>
       </login-module>
   </authentication>
</application-policy>

Example 7.2. Multiple login stack authentication policy

This example describes a security domain configuration named web-console that uses two login modules in the authentication login module stack.
One <login-module> obtains login credentials using the LdapLoginModule (refer to Section 12.1.1, “LdapLoginModule”), whereas the other <login-module> obtains authentication credentials using BaseCertLoginModule (refer to Section 12.1.7, “BaseCertLoginModule”).
In this instance, both modules are marked as sufficient, therefore only one of them must succeed for authentication to be successful. 
<application-policy xmlns="urn:jboss:security-beans:1.0 name="web-console">
    <authentication>
    <!-- LDAP configuration -->
    <login-module code="org.jboss.security.auth.spi.LdapLoginModule" 
         flag="sufficient" />
    <!-- database configuration -->
    <login-module code="org.jboss.security.auth.spi.BaseCertLoginModule" 
                      flag="sufficient" />
            
    </authentication>
</application-policy>

7.1. Custom Callback Handlers

Implementing callback handlers into authentication procedures allows a login module to authenticate a user independent of the client application authentication method.
You can implement callback handlers using the following methods:
  • Specify the CallbackHandlerClassName attribute in the conf/jboss-service.xml JaasSecurityManagerService MBean definition.
  • Inject a callback handler instance into the deploy/security/security-jboss-beans.xml JNDISecurityManagement bean.

Procedure 7.1. Set callback handler using attributes

This procedure describes how to specify a callback handler in the jboss-service.xml configuration file.

  1. Open the configuration file

    Navigate to $JBOSS_HOME/server/$PROFILE/conf/
    Open the jboss-service.xml file.
    By default, the jboss-service.xml file contains the configuration in Example 7.3, “jboss-service default configuration”

    Example 7.3. jboss-service default configuration

    <?xml version="1.0" encoding="UTF-8"?>
...

<!-- ==================================================================== -->
<!-- Security                                                             -->
<!-- ==================================================================== -->

<!-- JAAS security manager and realm mapping -->
  <mbean code="org.jboss.security.plugins.JaasSecurityManagerService" name="jboss.security:service=JaasSecurityManager">
  <!-- A flag which indicates whether the SecurityAssociation server mode
  is set on service creation. This is true by default since the
  SecurityAssociation should be thread local for multi-threaded server
  operation.-->
  <attribute name="ServerMode">true</attribute>

  <attribute name="SecurityManagerClassName">org.jboss.security.plugins.JaasSecurityManager</attribute>

  <attribute name="DefaultUnauthenticatedPrincipal">anonymous</attribute>

  <!-- DefaultCacheTimeout: Specifies the default timed cache policy timeout
  in seconds.
  If you want to disable caching of security credentials, set this to 0 to
  force authentication to occur every time. This has no affect if the
  AuthenticationCacheJndiName has been changed from the default value.-->

  <attribute name="DefaultCacheTimeout">1800</attribute>

  <!-- DefaultCacheResolution: Specifies the default timed cache policy
  resolution in seconds. This controls the interval at which the cache
  current timestamp is updated and should be less than the DefaultCacheTimeout
  in order for the timeout to be meaningful. This has no affect if the
  AuthenticationCacheJndiName has been changed from the default value.-->

  <attribute name="DefaultCacheResolution">60</attribute>

  <!-- DeepCopySubjectMode: This set the copy mode of subjects done by the
  security managers to be deep copies that makes copies of the subject
  principals and credentials if they are cloneable. It should be set to
  true if subject include mutable content that can be corrupted when
  multiple threads have the same identity and cache flushes/logout clearing
  the subject in one thread results in subject references affecting other
  threads.-->

  <attribute name="DeepCopySubjectMode">false</attribute>

  </mbean>

...

  2. Append the attribute

    To set the custom callback handler, append an <attribute> element as a child of the <mbean> element, and specify the fully qualified name of your callback handler. Refer to Example 7.4, “jboss-service appended callback handler” for an example <attribute> element, with the callback handler specified.

    Example 7.4. jboss-service appended callback handler

    <?xml version="1.0" encoding="UTF-8"?>
...

<!-- ==================================================================== -->
<!-- Security                                                             -->
<!-- ==================================================================== -->

<!-- JAAS security manager and realm mapping -->
  <mbean code="org.jboss.security.plugins.JaasSecurityManagerService" name="jboss.security:service=JaasSecurityManager">
  <!-- A flag which indicates whether the SecurityAssociation server mode
  is set on service creation. This is true by default since the
  SecurityAssociation should be thread local for multi-threaded server
  operation.-->
  <attribute name="ServerMode">true</attribute>

  <attribute name="SecurityManagerClassName">org.jboss.security.plugins.JaasSecurityManager</attribute>

  <attribute name="DefaultUnauthenticatedPrincipal">anonymous</attribute>

  <!-- DefaultCacheTimeout: Specifies the default timed cache policy timeout
  in seconds.
  If you want to disable caching of security credentials, set this to 0 to
  force authentication to occur every time. This has no affect if the
  AuthenticationCacheJndiName has been changed from the default value.-->

  <attribute name="DefaultCacheTimeout">1800</attribute>

  <!-- DefaultCacheResolution: Specifies the default timed cache policy
  resolution in seconds. This controls the interval at which the cache
  current timestamp is updated and should be less than the DefaultCacheTimeout
  in order for the timeout to be meaningful. This has no affect if the
  AuthenticationCacheJndiName has been changed from the default value.-->

  <attribute name="DefaultCacheResolution">60</attribute>

  <!-- DeepCopySubjectMode: This set the copy mode of subjects done by the
  security managers to be deep copies that makes copies of the subject
  principals and credentials if they are cloneable. It should be set to
  true if subject include mutable content that can be corrupted when
  multiple threads have the same identity and cache flushes/logout clearing
  the subject in one thread results in subject references affecting other
  threads.-->

  <attribute name="DeepCopySubjectMode">false</attribute>

  <attribute name="CallbackHandlerClassName">org.jboss.security.plugins.[Custom_Callback_Handler_Name]</attribute>

  </mbean>

...

  3. Restart server

    You have now configured the jboss-service.xml file to use a custom callback handler.
    Restart the server to ensure the new security policy takes effect.

Procedure 7.2. Set security callback handler using injection

This procedure describes how to inject a security callback handler instance into the JNDISecurityManagement bean.

  1. Create custom callback instance

    You must create an instance of the custom callback handler, and register it.

  2. Open the configuration file

    Navigate to $JBOSS_HOME/server/$PROFILE/deploy/security/
    Open the security-jboss-beans.xml file.
    By default, the security-jboss-beans.xml file contains the JNDIBasedSecurityManagement bean configuration in Example 7.5, “security-jboss-beans default configuration”

    Example 7.5. security-jboss-beans default configuration

    <!-- JNDI Based Security Management -->
<bean name="JBossSecuritySubjectFactory" class="org.jboss.security.integration.JBossSecuritySubjectFactory" />

  3. Append the injection property

    To inject the callback handler, append a <property> element as a child of the JNDIBasedSecurityManagement <mbean> element. Specify the callback handler using the the <property> and <inject> elements described in Example 7.4, “jboss-service appended callback handler”.

    Example 7.6. security-jboss-beans callback handler

    <bean name="JBossSecuritySubjectFactory" class="org.jboss.security.integration.JBossSecuritySubjectFactory">
   <property name="securityManagement">
      <inject bean="JNDIBasedSecurityManagement" />
   </property>
</bean>

  4. Restart server

    You have now configured the security-jboss-beans.xml file to inject your custom callback handler.
    Restart the server to ensure the new security policy takes effect.