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.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.6, “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.8, “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.xmlJaasSecurityManagerService MBean definition. - Inject a callback handler instance into the
deploy/security/security-jboss-beans.xmlJNDISecurityManagement 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.
Open the configuration file
Navigate to$JBOSS_HOME/server/$PROFILE/conf/Open thejboss-service.xmlfile.By default, thejboss-service.xmlfile 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> ...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> ...Restart server
You have now configured thejboss-service.xmlfile 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.
Create custom callback instance
You must create an instance of the custom callback handler, and register it.Open the configuration file
Navigate to$JBOSS_HOME/server/$PROFILE/deploy/security/Open thesecurity-jboss-beans.xmlfile.By default, thesecurity-jboss-beans.xmlfile 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" />
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 <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>Restart server
You have now configured thesecurity-jboss-beans.xmlfile to inject your custom callback handler.Restart the server to ensure the new security policy takes effect.
