-
Language:
English
-
Language:
English
Red Hat Training
A Red Hat training course is available for JBoss Enterprise Application Platform Common Criteria Certification
Chapter 12. Login Modules
12.1. Using Modules
JBoss Enterprise Application Platform includes several bundled login modules suitable for most user management needs. JBoss Enterprise Application Platform can read user information from a relational database, an Lightweight Directory Access Protocol (LDAP) server or flat files. In addition to these core login modules, JBoss provides other login modules that provide user information for very customized needs in JBoss.
12.1.1. LdapLoginModule
LdapLoginModule
is a LoginModule
implementation that authenticates against a Lightweight Directory Access Protocol (LDAP) server. Use the LdapLoginModule
if your user name and credentials are stored in an LDAP server that is accessible using a Java Naming and Directory Interface (JNDI) LDAP provider.
Note
This login module also supports unauthenticated identity and password stacking.
The LDAP connectivity information is provided as configuration options that are passed through to the environment object used to create JNDI initial context. The standard LDAP JNDI properties used include the following:
- java.naming.factory.initial
InitialContextFactory
implementation class name. This defaults to the Sun LDAP provider implementationcom.sun.jndi.ldap.LdapCtxFactory
.- java.naming.provider.url
- LDAP URL for the LDAP server.
- java.naming.security.authentication
- Security protocol level to use. The available values include
none
,simple
, andstrong
. If the property is undefined, the behavior is determined by the service provider. - java.naming.security.protocol
- Transport protocol to use for secure access. Set this configuration option to the type of service provider (for example, SSL). If the property is undefined, the behavior is determined by the service provider.
- java.naming.security.principal
- Specifies the identity of the Principal for authenticating the caller to the service. This is built from other properties as described below.
- java.naming.security.credentials
- Specifies the credentials of the Principal for authenticating the caller to the service. Credentials can take the form of a hashed password, a clear-text password, a key, or a certificate. If the property is undefined, the behavior is determined by the service provider.
The supported login module configuration options include the following:
- principalDNPrefix
- Prefix added to the user name to form the user distinguished name. See
principalDNSuffix
for more info. - principalDNSuffix
- Suffix added to the user name when forming the user distinguished name. This is useful if you prompt a user for a user name and you don't want the user to have to enter the fully distinguished name. Using this property and
principalDNSuffix
theuserDN
will be formed asprincipalDNPrefix + username + principalDNSuffix
- useObjectCredential
- Value that indicates the credential should be obtained as an opaque
Object
using theorg.jboss.security.auth.callback.ObjectCallback
type ofCallback
rather than as achar[]
password using a JAASPasswordCallback
. This allows for passing non-char[]
credential information to the LDAP server. The available values aretrue
andfalse
. - rolesCtxDN
- Fixed, distinguished name to the context for searching user roles.
- userRolesCtxDNAttributeName
- Name of an attribute in the user object that contains the distinguished name to the context to search for user roles. This differs from
rolesCtxDN
in that the context to search for a user's roles can be unique for each user. - roleAttributeID
- Name of the attribute containing the user roles. If not specified, this defaults to
roles
. - roleAttributeIsDN
- Flag indicating whether the roleAttributeID contains the fully distinguished name of a role object, or the role name. The role name is taken from the value of the roleNameAttributeId attribute of the context name by the distinguished name.If true, the role attribute represents the distinguished name of a role object. If false, the role name is taken from the value of
roleAttributeID
. The default isfalse
.Note
In certain directory schemas (e.g., MS ActiveDirectory), role attributes in the user object are stored as Distinguished Names (DNs) to role objects instead of simple names. For implementations that use this schema type, roleAttributeIsDN must be set totrue
. - roleNameAttributeID
- Name of the attribute of the context pointed to by the roleCtxDN distinguished name value which contains the role name. If the roleAttributeIsDN property is set to
true
, this property is used to find the role object'sname
attribute. The default isgroup
. - uidAttributeID
- Name of the attribute in the object containing the user roles that corresponds to the user ID. This is used to locate the user roles. If not specified this defaults to
uid
. - matchOnUserDN
- Flag that specifies whether the search for user roles should match on the user's fully distinguished name. If
true
, the fulluserDN
is used as the match value. Iffalse
, only the user name is used as the match value against the uidAttributeName attribute. The default value isfalse
. - unauthenticatedIdentity
- Principal name to assign to requests containing no authentication information. This behavior is inherited from the
UsernamePasswordLoginModule
superclass. - allowEmptyPasswords
- A flag indicating if empty (length 0) passwords should be passed to the LDAP server. An empty password is treated as an anonymous login by some LDAP servers, and this may not be a desirable feature. To reject empty passwords, set this to
false
. If set totrue
, the LDAP server will validate the empty password. The default istrue
.
User authentication is performed by connecting to the LDAP server, based on the login module configuration options. Connecting to the LDAP server is done by creating an
InitialLdapContext
with an environment composed of the LDAP JNDI properties described previously in this section.
The Context.SECURITY_PRINCIPAL is set to the distinguished name of the user obtained by the callback handler in combination with the principalDNPrefix and principalDNSuffix option values, and the Context.SECURITY_CREDENTIALS property is either set to the
String
password or the Object
credential depending on the useObjectCredential option.
Once authentication has succeeded (
InitialLdapContext
instance is created), the user's roles are queried by performing a search on the rolesCtxDN
location with search attributes set to the roleAttributeName and uidAttributeName option values. The roles names are obtaining by invoking the toString
method on the role attributes in the search result set.
Example 12.1. LDAP Login Module Authentication Policy
This authentication policy describes how you use the parameters in a security domain authentication policy
<application-policy name="testLDAP"> <authentication> <login-module code="org.jboss.security.auth.spi.LdapLoginModule" flag="required"> <module-option name="java.naming.factory.initial"> com.sun.jndi.ldap.LdapCtxFactory </module-option> <module-option name="java.naming.provider.url"> ldap://ldaphost.jboss.org:1389/ </module-option> <module-option name="java.naming.security.authentication"> simple </module-option> <module-option name="principalDNPrefix">uid=</module-option> <module-option name="principalDNSuffix"> ,ou=People,dc=jboss,dc=org </module-option> <module-option name="rolesCtxDN"> ou=Roles,dc=jboss,dc=org </module-option> <module-option name="uidAttributeID">member</module-option> <module-option name="matchOnUserDN">true</module-option> <module-option name="roleAttributeID">cn</module-option> <module-option name="roleAttributeIsDN">false </module-option> </login-module> </authentication> </application-policy>
The
java.naming.factory.initial
, java.naming.factory.url
and java.naming.security
options in the testLDAP <login-module> configuration indicate the following conditions:
- The Sun LDAP JNDI provider implementation will be used
- The LDAP server is located on host
ldaphost.jboss.org
on port 1389 - The LDAP simple authentication method will be use to connect to the LDAP server.
The login module attempts to connect to the LDAP server using a Distinguished Name (DN) representing the user it is trying to authenticate. This DN is constructed from the passed principalDNPrefix, the user name of the user and the principalDNSuffix as described above. In Example 12.2, “LDIF File Example”, the user name
jsmith
would map to uid=jsmith,ou=People,dc=jboss,dc=org
.
- Distinguished Name (DN)
- In Lightweight Directory Access Protocol (LDAP), the distinguished name uniquely identifies an object in a directory. Each distinguished name must have a unique name and location from all other objects, which is achieved using a number of attribute-value pairs (AVPs). The AVPs define information such as common names, organization unit, among others. The combination of these values results in a unique string required by the LDAP.
Note
The example assumes the LDAP server authenticates users using the
userPassword
attribute of the user's entry (theduke
in this example). Most LDAP servers operate in this manner, however if your LDAP server handles authentication differently you must ensure LDAP is configured according to your production environment requirements.
Once authentication succeeds, the roles on which authorization will be based are retrieved by performing a subtree search of the
rolesCtxDN
for entries whose uidAttributeID match the user. If matchOnUserDN is true, the search will be based on the full DN of the user. Otherwise the search will be based on the actual user name entered. In this example, the search is under ou=Roles,dc=jboss,dc=org
for any entries that have a member
attribute equal to uid=jduke,ou=People,dc=jboss,dc=org
. The search would locate cn=JBossAdmin
under the roles entry.
The search returns the attribute specified in the roleAttributeID option. In this example, the attribute is
cn
. The value returned would be JBossAdmin
, so the jsmith
user is assigned to the JBossAdmin
role.
A local LDAP server often provides identity and authentication services, but is unable to use authorization services. This is because application roles do not always map well onto LDAP groups, and LDAP administrators are often hesitant to allow external application-specific data in central LDAP servers. The LDAP authentication module is often paired with another login module, such as the database login module, that can provide roles more suitable to the application being developed.
An LDAP Data Interchange Format (LDIF) file representing the structure of the directory this data operates against is shown in Example 12.2, “LDIF File Example”.
- LDAP Data Interchange Format (LDIF)
- Plain text data interchange format used to represent LDAP directory content and update requests. Directory content is represented as one record for each object or update request. Content consists of add, modify, delete, and rename requests.
Example 12.2. LDIF File Example
dn: dc=jboss,dc=org objectclass: top objectclass: dcObject objectclass: organization dc: jboss o: JBoss dn: ou=People,dc=jboss,dc=org objectclass: top objectclass: organizationalUnit ou: People dn: uid=jsmith,ou=People,dc=jboss,dc=org objectclass: top objectclass: uidObject objectclass: person uid: jsmith cn: John sn: Smith userPassword: theduke dn: ou=Roles,dc=jboss,dc=org objectclass: top objectclass: organizationalUnit ou: Roles dn: cn=JBossAdmin,ou=Roles,dc=jboss,dc=org objectclass: top objectclass: groupOfNames cn: JBossAdmin member: uid=jsmith,ou=People,dc=jboss,dc=org description: the JBossAdmin group
12.1.2. Password Stacking
Multiple login modules can be chained together in a stack, with each login module providing both the authentication and authorization components. This works for many use cases, but sometimes authentication and authorization are split across multiple user management stores.
Section 12.1.1, “LdapLoginModule”describes how to combine LDAP and a relational database, allowing a user to be authenticated by either system. However, consider the case where users are managed in a central LDAP server but application-specific roles are stored in the application's relational database. The password-stacking module option captures this relationship.
To use password stacking, each login module should set the <module-option>
password-stacking
attribute to useFirstPass
. If a previous module configured for password stacking has authenticated the user, all the other stacking modules will consider the user authenticated and only attempt to provide a set of roles for the authorization step.
When
password-stacking
option is set to useFirstPass
, this module first looks for a shared user name and password under the property names javax.security.auth.login.name and javax.security.auth.login.password respectively in the login module shared state map.
If found, these properties are used as the principal name and password. If not found, the principal name and password are set by this login module and stored under the property names javax.security.auth.login.name and javax.security.auth.login.password respectively.
Note
When using password stacking, set all modules to be required. This ensures that all modules are considered, and have the chance to contribute roles to the authorization process.
Example 12.3. Password Stacking Sample
This example shows how password stacking could be used.
<application-policy name="todo"> <authentication> <login-module code="org.jboss.security.auth.spi.LdapLoginModule" flag="required"> <!-- LDAP configuration --> <module-option name="password-stacking">useFirstPass</module-option> </login-module> <login-module code="org.jboss.security.auth.spi.DatabaseServerLoginModule" flag="required"> <!-- database configuration --> <module-option name="password-stacking">useFirstPass</module-option> </login-module> </authentication> </application-policy>
12.1.3. Password Hashing
Most login modules must compare a client-supplied password to a password stored in a user management system. These modules generally work with plain text passwords, but can be configured to support hashed passwords to prevent plain text passwords from being stored on the server side.
Example 12.4. Password Hashing
The following is a login module configuration that assigns unauthenticated users the principal name
nobody
and contains based64-encoded, MD5 hashes of the passwords in a usersb64.properties
file. The usersb64.properties
file can be part of the deployment classpath, or be saved in the /conf
directory.
<policy> <application-policy name="testUsersRoles"> <authentication> <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" flag="required"> <module-option name="usersProperties">usersb64.properties</module-option> <module-option name="rolesProperties">test-users-roles.properties</module-option> <module-option name="unauthenticatedIdentity">nobody</module-option> <module-option name="hashAlgorithm">MD5</module-option> <module-option name="hashEncoding">base64</module-option> </login-module> </authentication> </application-policy> </policy>
- hashAlgorithm
- Name of the
java.security.MessageDigest
algorithm to use to hash the password. There is no default so this option must be specified to enable hashing. Typical values areMD5
andSHA
. - hashEncoding
- String that specifies one of three encoding types:
base64
,hex
orrfc2617
. The default isbase64
. - hashCharset
- Encoding character set used to convert the clear text password to a byte array. The platform default encoding is the default.
- hashUserPassword
- Specifies the hashing algorithm must be applied to the password the user submits. The hashed user password is compared against the value in the login module, which is expected to be a hash of the password. The default is
true
. - hashStorePassword
- Specifies the hashing algorithm must be applied to the password stored on the server side. This is used for digest authentication, where the user submits a hash of the user password along with a request-specific tokens from the server to be compare. The hash algorithm (for digest, this would be
rfc2617
) is utilized to compute a server-side hash, which should match the hashed value sent from the client.
If you must generate passwords in code,
the org.jboss.security.Util
class provides a static helper method that will hash a password using the specified encoding.
String hashedPassword = Util.createPasswordHash("MD5", Util.BASE64_ENCODING, null, null, "password");
OpenSSL provides an alternative way to quickly generate hashed passwords.
echo -n password | openssl dgst -md5 -binary | openssl base64
In both cases, the text password should hash to
X03MO1qnZdYdgyfeuILPmQ==
. This value must be stored in the user store.
12.1.4. Unauthenticated Identity
Not all requests are received in an authenticated format.
unauthenticated identity
is a login module configuration option that assigns a specific identity (guest, for example) to requests that are made with no associated authentication information. This can be used to allow unprotected servlets to invoke methods on EJBs that do not require a specific role. Such a principal has no associated roles and so can only access either unsecured EJBs or EJB methods that are associated with the unchecked permission constraint.
- unauthenticatedIdentity: This defines the principal name that should be assigned to requests that contain no authentication information.
12.1.5. UsersRolesLoginModule
UsersRolesLoginModule
is a simple login module that supports multiple users and user roles loaded from Java properties files. The user name-to-password mapping file is called users.properties
and the user name-to-roles mapping file is called roles.properties
.
The supported login module configuration options include the following:
- usersProperties
- Name of the properties resource (file) containing the user name to password mappings. This defaults to
<filename_prefix>-users.properties
. - rolesProperties
- Name of the properties resource (file) containing the user name to roles mappings. This defaults to
<filename_prefix>-roles.properties
.
This login module supports password stacking, password hashing, and unauthenticated identity.
The properties files are loaded during initialization using the initialize method thread context class loader. This means that these files can be placed into the Java EE deployment JAR, the JBoss configuration directory, or any directory on the JBoss server or system classpath. The primary purpose of this login module is to easily test the security settings of multiple users and roles using properties files deployed with the application.
Example 12.5. UserRolesLoginModule
<deployment xmlns="urn:jboss:bean-deployer:2.0"> <!-- ejb3 test application-policy definition --> <application-policy xmlns="urn:jboss:security-beans:1.0" name="ejb3-sampleapp"> <authentication> <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" flag="required"> <module-option name="usersProperties">ejb3-sampleapp-users.properties</module-option> <module-option name="rolesProperties">ejb3-sampleapp-roles.properties</module-option> </login-module> </authentication> </application-policy> </deployment>
In Example 12.5, “UserRolesLoginModule”, the
ejb3-sampleapp-users.properties
file uses a username=password
format with each user entry on a separate line:
username1=password1 username2=password2 ...
The
ejb3-sampleapp-roles.properties
file referenced in Example 12.5, “UserRolesLoginModule” uses the pattern username=role1,role2,
with an optional group name value. For example:
username1=role1,role2,... username1.RoleGroup1=role3,role4,... username2=role1,role3,...
The user name.XXX property name pattern present in
ejb3-sampleapp-roles.properties
is used to assign the user name roles to a particular named group of roles where the XXX
portion of the property name is the group name. The user name=... form is an abbreviation for user name.Roles=..., where the Roles
group name is the standard name the JaasSecurityManager
expects to contain the roles which define the users permissions.
The following would be equivalent definitions for the
jduke
user name:
jduke=TheDuke,AnimatedCharacter jduke.Roles=TheDuke,AnimatedCharacter
12.1.6. DatabaseServerLoginModule
The
DatabaseServerLoginModule
is a Java Database Connectivity-based (JDBC) login module that supports authentication and role mapping. Use this login module if you have your user name, password and role information stored in a relational database.
Note
This module supports password stacking, password hashing and unauthenticated identity.
The
DatabaseServerLoginModule
is based on two logical tables:
Table Principals(PrincipalID text, Password text) Table Roles(PrincipalID text, Role text, RoleGroup text)
The
Principals
table associates the user PrincipalID
with the valid password and the Roles
table associates the user PrincipalID
with its role sets. The roles used for user permissions must be contained in rows with a RoleGroup
column value of Roles
.
The tables are logical in that you can specify the SQL query that the login module uses. The only requirement is that the
java.sql.ResultSet
has the same logical structure as the Principals
and Roles
tables described previously. The actual names of the tables and columns are not relevant as the results are accessed based on the column index.
To clarify this notion, consider a database with two tables,
Principals
and Roles
, as already declared. The following statements populate the tables with the following data:
PrincipalID
java
with aPassword
ofechoman
in thePrincipals
tablePrincipalID
java
with a role namedEcho
in theRoles
RoleGroup
in theRoles
tablePrincipalID
java
with a role namedcaller_java
in theCallerPrincipal
RoleGroup
in theRoles
table
INSERT INTO Principals VALUES('java', 'echoman') INSERT INTO Roles VALUES('java', 'Echo', 'Roles') INSERT INTO Roles VALUES('java', 'caller_java', 'CallerPrincipal')
The supported login module configuration options include the following:
- dsJndiName
- The JNDI name for the
DataSource
of the database containing the logicalPrincipals
andRoles
tables. If not specified this defaults tojava:/DefaultDS
. - principalsQuery
- The prepared statement query equivalent to:
select Password from Principals where PrincipalID=?
. If not specified this is the exact prepared statement that will be used. - rolesQuery
- The prepared statement query equivalent to:
select Role, RoleGroup from Roles where PrincipalID=?
. If not specified this is the exact prepared statement that will be used. - ignorePasswordCase
- A boolean flag indicating if the password comparison should ignore case. This can be useful for hashed password encoding where the case of the hashed password is not significant.
- principalClass
- An option that specifies a
Principal
implementation class. This must support a constructor taking a string argument for the principal name.
An example
DatabaseServerLoginModule
configuration could be constructed as follows:
CREATE TABLE Users(username VARCHAR(64) PRIMARY KEY, passwd VARCHAR(64)) CREATE TABLE UserRoles(username VARCHAR(64), userRoles VARCHAR(32))
A corresponding
login-config.xml
entry would be:
<policy> <application-policy name="testDB"> <authentication> <login-module code="org.jboss.security.auth.spi.DatabaseServerLoginModule" flag="required"> <module-option name="dsJndiName">java:/MyDatabaseDS</module-option> <module-option name="principalsQuery">select passwd from Users username where username=?</module-option> <module-option name="rolesQuery">select userRoles, 'Roles' from UserRoles where username=?</module-option> </login-module> </authentication> </application-policy> </policy>
12.1.7. BaseCertLoginModule
BaseCertLoginModule
authenticates users based on X509 certificates. A typical use case for this login module is CLIENT-CERT
authentication in the web tier.
This login module only performs authentication: you must combine it with another login module capable of acquiring authorization roles to completely define access to a secured web or EJB component. Two subclasses of this login module,
CertRolesLoginModule
and DatabaseCertLoginModule
extend the behavior to obtain the authorization roles from either a properties file or database.
The
BaseCertLoginModule
needs a KeyStore
to perform user validation. This is obtained through a org.jboss.security.SecurityDomain
implementation. Typically, the SecurityDomain
implementation is configured using the org.jboss.security.plugins.JaasSecurityDomain
MBean as shown in this jboss-service.xml
configuration fragment:
<mbean code="org.jboss.security.plugins.JaasSecurityDomain" name="jboss.ch8:service=SecurityDomain"> <constructor> <arg type="java.lang.String" value="jmx-console"/> </constructor> <attribute name="KeyStoreURL">resource:localhost.keystore</attribute> <attribute name="KeyStorePass">unit-tests-server</attribute> </mbean>
The configuration creates a security domain with the name
jmx-console
, with a SecurityDomain
implementation available through JNDI under the name java:/jaas/jmx-console
. The security domain follows the JBossSX security domain naming pattern.
Procedure 12.1. Secure Web Applications with Certificates and Role-based Authorization
This procedure describes how to secure a web application, such as the
jmx-console.war,
using client certificates and role-based authorization.
Declare Resources and Roles
Modifyweb.xml
to declare the resources to be secured along with the allowed roles and security domain to be used for authentication and authorization.<?xml version="1.0"?> <web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"> ... <!-- A security constraint that restricts access to the HTML JMX console to users with the role JBossAdmin. Edit the roles to what you want and uncomment the WEB-INF/jboss-web.xml/security-domain element to enable secured access to the HTML JMX console. --> <security-constraint> <web-resource-collection> <web-resource-name>HtmlAdaptor</web-resource-name> <description>An example security config that only allows users with the role JBossAdmin to access the HTML JMX console web application </description> <url-pattern>/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>JBossAdmin</role-name> </auth-constraint> </security-constraint> <login-config> <auth-method>BASIC</auth-method> <realm-name>JBoss JMX Console</realm-name> </login-config> <security-role> <role-name>JBossAdmin</role-name> </security-role> </web-app>
Specify the JBoss Security Domain
In thejboss-web.xml
file, specify the required security domain.<jboss-web> <security-domain>jmx-console</security-domain> </jboss-web>
Specify Login Module Configuration
Define the login module configuration for the jmx-console security domain you just specified. This is done in theconf/login-config.xml
file.<application-policy name="jmx-console"> <authentication> <login-module code="org.jboss.security.auth.spi.BaseCertLoginModule" flag="required"> <module-option name="password-stacking">useFirstPass</module-option> <module-option name="securityDomain">jmx-console</module-option> </login-module> <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" flag="required"> <module-option name="password-stacking">useFirstPass</module-option> <module-option name="usersProperties">jmx-console-users.properties</module-option> <module-option name="rolesProperties">jmx-console-roles.properties</module-option> </login-module> </authentication> </application-policy>
Procedure 12.1, “Secure Web Applications with Certificates and Role-based Authorization”shows the
BaseCertLoginModule
is used for authentication of the client cert, and the UsersRolesLoginModule
is only used for authorization due to the password-stacking=useFirstPass
option. Both the localhost.keystore
and the jmx-console-roles.properties
require an entry that maps to the principal associated with the client cert.
By default, the principal is created using the client certificate distinguished name, such as the DN specified in Example 12.6, “Certificate Example”.
Example 12.6. Certificate Example
[conf]$ keytool -printcert -file unit-tests-client.export Owner: CN=unit-tests-client, OU=JBoss Inc., O=JBoss Inc., ST=Washington, C=US Issuer: CN=jboss.com, C=US, ST=Washington, L=Snoqualmie Pass, EMAILADDRESS=admin @jboss.com, OU=QA, O=JBoss Inc. Serial number: 100103 Valid from: Wed May 26 07:34:34 PDT 2004 until: Thu May 26 07:34:34 PDT 2005 Certificate fingerprints: MD5: 4A:9C:2B:CD:1B:50:AA:85:DD:89:F6:1D:F5:AF:9E:AB SHA1: DE:DE:86:59:05:6C:00:E8:CC:C0:16:D3:C2:68:BF:95:B8:83:E9:58
The
localhost.keystore
would need the certificate in Example 12.6, “Certificate Example” stored with an alias of CN=unit-tests-client, OU=JBoss Inc., O=JBoss Inc., ST=Washington, C=US
. The jmx-console-roles.properties
would also need an entry for the same entry. Since the DN contains characters that are normally treated as delimiters, you must escape the problem characters using a backslash ('\
') as illustrated below.
# A sample roles.properties file for use with the UsersRolesLoginModule CN\=unit-tests-client,\ OU\=JBoss\ Inc.,\ O\=JBoss\ Inc.,\ ST\=Washington,\ C\=US=JBossAdmin admin=JBossAdmin
12.1.8. IdentityLoginModule
IdentityLoginModule
is a simple login module that associates a hard-coded user name to any subject authenticated against the module. It creates a SimplePrincipal
instance using the name specified by the principal
option.
Note
This module supports password stacking.
This login module is useful when you need to provide a fixed identity to a service, and in development environments when you want to test the security associated with a given principal and associated roles.
The supported login module configuration options include:
- principal
- This is the name to use for the
SimplePrincipal
all users are authenticated as. The principal name defaults toguest
if no principal option is specified. - roles
- This is a comma-delimited list of roles that will be assigned to the user.
A sample XMLLoginConfig configuration entry is described below. The entry authenticates all users as the principal named
jduke
and assign role names of TheDuke
, and AnimatedCharacter
:.
<policy> <application-policy name="testIdentity"> <authentication> <login-module code="org.jboss.security.auth.spi.IdentityLoginModule" flag="required"> <module-option name="principal">jduke</module-option> <module-option name="roles">TheDuke,AnimatedCharacter</module-option> </login-module> </authentication> </application-policy> </policy>
12.1.9. RunAsLoginModule
RunAsLoginModule
(org.jboss.security.auth.spi.RunAsLoginModule
) is a helper module that pushes a run as role onto the stack for the duration of the login phase of authentication, and pops the run as role in either the commit or abort phase.
The purpose of this login module is to provide a role for other login modules that must access secured resources in order to perform their authentication (for example, a login module that accesses a secured EJB).
RunAsLoginModule
must be configured ahead of the login modules that require a run as role established.
The only login module configuration option is:
- roleName
- Name of the role to use as the run as role during login phase. If not specified a default of
nobody
is used.
12.1.10. RunAsIdentity Creation
In order for JBoss Enterprise Application Platform to secure access to EJB methods, the user's identity must be known at the time the method call is made.
A user's identity in the server is represented either by a
javax.security.auth.Subject
instance or an org.jboss.security.RunAsIdentity
instance. Both these classes store one or more principals that represent the identity and a list of roles that the identity possesses. In the case of the javax.security.auth.Subject
a list of credentials is also stored.
In the <assembly-descriptor> section of the
ejb-jar.xml
deployment descriptor, you specify one or more roles that a user must have to access the various EJB methods. A comparison of these lists reveals whether the user has one of the roles necessary to access the EJB method.
Example 12.7. org.jboss.security.RunAsIdentity Creation
In the
ejb-jar.xml
file, you specify a <security-identity> element with a <run-as> role defined as a child of the <session> element.
<session> ... <security-identity> <run-as> <role-name>Admin</role-name> </run-as> </security-identity> ... </session>
This declaration signifies that an "Admin" RunAsIdentity role must be created.
To name a principal for the Admin role, you define a
<run-as-principal>
element in the jboss-web.xml
file.
<session> ... <security-identity> <run-as-principal>John</run-as-principal> </security-identity> ... </session>
The
<security-identity>
element in both the ejb-jar.xml
and jboss-web.xml
files are parsed at deployment time. The <run-as>
role name and the <run-as-principal>
name are then stored in the org.jboss.metadata.SecurityIdentityMetaData
class.
Example 12.8. Assigning multiple roles to a RunAsIdentity
You can assign more roles to RunAsIdentity by mapping roles to principals in the
jboss-web.xml
deployment descriptor <assembly-descriptor>
element group.
<assembly-descriptor> ... <security-role> <role-name>Support</role-name> <principal-name>John</principal-name> <principal-name>Jill</principal-name> <principal-name>Tony</principal-name> </security-role> ... </assembly-descriptor>
In Example 12.7, “ org.jboss.security.RunAsIdentity Creation”, the
<run-as-principal>
of "Mark" was created. The configuration in this example extends the "Admin" role, by adding the "Support" role. The new role contains extra principals, including the originally defined principal "John".
The
<security-role>
element in both the ejb-jar.xml
and jboss.xml
files are parsed at deployment time. The <role-name>
and the <principal-name>
data is stored in the org.jboss.metadata.SecurityIdentityMetaData
class.
12.1.11. ClientLoginModule
ClientLoginModule
(org.jboss.security.ClientLoginModule
) is an implementation of LoginModule
for use by JBoss clients for establishing caller identity and credentials. This simply sets the org.jboss.security.SecurityAssociation.principal
to the value of the NameCallback
filled in by the callbackhandler
, and the org.jboss.security.SecurityAssociation.credential
to the value of the PasswordCallback
filled in by the callbackhandler
.
ClientLoginModule
is the only supported mechanism for a client to establish the current thread's caller. Both stand-alone client applications, and server environments (acting as JBoss EJB clients where the security environment has not been configured to use JBossSX transparently) must use ClientLoginModule
.
Note that this login module does not perform any authentication. It merely copies the login information provided to it into the JBoss server EJB invocation layer for subsequent authentication on the server. If you need to perform client-side authentication of users you would need to configure another login module in addition to the
ClientLoginModule
.
The supported login module configuration options include the following:
- multi-threaded
- Value that specifies the way login threads connect to principal and credential storage sources. When set to true, each login thread has its own principal and credential storage and each separate thread must perform its own login. This is useful in client environments where multiple user identities are active in separate threads. When set to false the login identity and credentials are global variables that apply to all threads in the VM. The default setting is
false
. - password-stacking
- Activates client-side authentication of clients using other login modules such as the
LdapLoginModule
. Whenpassword-stacking
option is set touseFirstPass
, the module first looks for a shared user name and password usingjavax.security.auth.login.name
andjavax.security.auth.login.password
respectively in the login module shared state map. This allows a module configured prior to this one to establish a valid JBoss user name and password. - restore-login-identity
- Value that specifies whether the
SecurityAssociation
principal and credential seen on entry to thelogin()
method are saved and restored on either abort or logout. This is necessary if you must change identities and then restore the original caller identity. If set totrue
, the principal and credential information is saved and restored on abort or logout. If set tofalse
, abort and logout clear theSecurityAssociation
. The default value isfalse
.