12.3. Included Security Mapping Modules

The following security mapping roles are provided in JBoss EAP 6.
Code Class
PropertiesRoles org.jboss.security.mapping.providers.role.PropertiesRolesMappingProvider
SimpleRoles org.jboss.security.mapping.providers.role.SimpleRolesMappingProvider
DeploymentRoles org.jboss.security.mapping.providers.DeploymentRolesMappingProvider
DatabaseRoles org.jboss.security.mapping.providers.role.DatabaseRolesMappingProvider
LdapRoles org.jboss.security.mapping.providers.role.LdapRolesMappingProvider
LdapAttributes org.jboss.security.mapping.providers.attribute.LdapAttributeMappingProvider
DeploymentRolesMappingProvider

A Role Mapping Module that takes into consideration a principal to roles mapping that can be done in jboss-web.xml and jboss-app.xml deployment descriptors.

Example 12.1. Example

<jboss-web>
...
  <security-role>
      <role-name>Support</role-name>
      <principal-name>Mark</principal-name> 
      <principal-name>Tom</principal-name>
  </security-role>
...
</jboss-web>
org.jboss.security.mapping.providers.DeploymentRoleToRolesMappingProvider

A Role to Roles Mapping Module that takes into consideration a principal to roles mapping that can be done in the deployment descriptors jboss-web.xml and jboss-app.xml. In this case principal-name denotes role to map other roles.

Example 12.2. Example

  <jboss-web>
 ...
    <security-role>
      <role-name>Employee</role-name>
      <principal-name>Support</principal-name>
      <principal-name>Sales</principal-name>
    </security-role>
 ...
  </jboss-web>
Which means that each principal having role Support or Sales will also have role Employee assigned.
org.jboss.security.mapping.providers.OptionsRoleMappingProvider

Role Mapping Provider that picks up the roles from the options and then appends them to the passed Group. Takes the properties style mapping of role name (key) with a comma separated list of roles (values).

org.jboss.security.mapping.providers.principal.SimplePrincipalMappingProvider

A principal mapping provider that takes in a SimplePrincipal and converts into SimplePrincipal with a different principal name.

DatabaseRolesMappingProvider

A MappingProvider that reads roles from a database.

Options:
  • dsJndiName: JNDI name of data source used to map roles to the user.
  • rolesQuery: This option should be a prepared statement equivalent to "select RoleName from Roles where User=?" ? is substituted with current principal name.
  • suspendResume: Boolean - To suspend and later resume transaction associated with current thread while performing search for roles.
  • transactionManagerJndiName: JNDI name of Transaction mamager (default is java:/TransactionManager)
LdapRolesMappingProvider

A mapping provider that assigns roles to an user using a LDAP server to search for the roles.

Options:
  • bindDN: The DN used to bind against the LDAP server for the user and roles queries. This DN needs read and search permissions on the baseCtxDN and rolesCtxDN values.
  • bindCredential: The password for the bindDN. This can be encrypted if the jaasSecurityDomain is specified.
  • rolesCtxDN: The fixed DN of the context to search for user roles. This is not the DN where the actual roles are, but the DN where the objects containing the user roles are. For example, in a Microsoft Active Directory server, this is the DN where the user account is.
  • roleAttributeID: The LDAP attribute which contains the names of authorization roles.
  • roleAttributeIsDN: Whether or not the roleAttributeID contains the fully-qualified DN of a role object. If false, the role name is taken from the value of the roleNameAttributeId attribute of the context name. Certain directory schemas, such as Microsoft Active Directory, require this attribute to be set to true.
  • roleNameAttributeID: Name of the attribute within the roleCtxDN context which contains the role name. If the roleAttributeIsDN property is set to true, this property is used to find the role object's name attribute.
  • parseRoleNameFromDN: A flag indicating if the DN returned by a query contains the roleNameAttributeID. If set to true, the DN is checked for the roleNameATtributeID. If set to false, the DN is not checked for the roleNameAttributeID. This flag can improve the performance of LDAP queries.
  • roleFilter: A search filter used to locate the roles associated with the authenticated user. The input username or userDN obtained from the login module callback is substituted into the filter anywhere a {0} expression is used. The authenticated userDN is substituted into the filter anywhere a {1} is used. An example search filter that matches on the input username is (member={0}). An alternative that matches on the authenticated userDN is (member={1}).
  • roleRecursion: The numbers of levels of recursion the role search will go below a matching context. Disable recursion by setting this to 0.
  • searchTimeLimit: The timeout in milliseconds for the user/role searches. Defaults to 10000 (10 seconds).
  • searchScope: The search scope to use.
PropertiesRolesMappingProvider

A MappingProvider that reads roles from a properties file in the following format: username=role1,role2,...

Options:
  • rolesProperties: Properties formatted file name. Expansion of JBoss variables can be used in form of ${jboss.variable}.
SimpleRolesMappingProvider

A simple MappingProvider that reads roles from the options map. The option attribute name is the name of principal to assign roles to and the attribute value is the comma separated role names to assign to the principal.

Example 12.3. Example

<module-option name="JavaDuke" value="JBossAdmin,Admin"/> 
<module-option name="joe" value="Users"/>
org.jboss.security.mapping.providers.attribute.DefaultAttributeMappingProvider

Checks module and locates principal name from mapping context to create attribute e-mail address from module option named principalName + ".email" and maps it to the given principal.

LdapAttributeMappingProvider

Maps attributes from LDAP to the subject. The options include whatever options your LDAP JNDI provider supports.

Example 12.4. Examples of standard property names include:

Context.INITIAL_CONTEXT_FACTORY = "java.naming.factory.initial"
Context.SECURITY_PROTOCOL = "java.naming.security.protocol"
Context.PROVIDER_URL = "java.naming.provider.url"
Context.SECURITY_AUTHENTICATION = "java.naming.security.authentication"
Options:
  • bindDN: The DN used to bind against the LDAP server for the user and roles queries. This DN needs read and search permissions on the baseCtxDN and rolesCtxDN values.
  • bindCredential: The password for the bindDN. This can be encrypted if the jaasSecurityDomain is specified.
  • baseCtxDN: The fixed DN of the context to start the user search from.
  • baseFilter: A search filter used to locate the context of the user to authenticate. The input username or userDN as obtained from the login module callback is substituted into the filter anywhere a {0} expression is used. This substituion behavior comes from the standard __DirContext.search(Name, String, Object[], SearchControls cons)__ method. An common example search filter is (uid={0}).
  • searchTimeLimit: The timeout in milliseconds for the user/role searches. Defaults to 10000 (10 seconds).
  • attributeList: A comma-separated list of attributes for the user. For example, mail,cn,sn,employeeType,employeeNumber.
  • jaasSecurityDomain: The JaasSecurityDomain to use to decrypt the java.naming.security.principal. The encrypted form of the password is that returned by the JaasSecurityDomain#encrypt64(byte[]) method. The org.jboss.security.plugins.PBEUtils can also be used to generate the encrypted form.