Chapter 10. Security Mapping Modules

The following security mapping modules are provided in JBoss EAP.

ClassCodeType

org.jboss.security.mapping.providers.role.PropertiesRolesMappingProvider

PropertiesRoles

role

org.jboss.security.mapping.providers.role.SimpleRolesMappingProvider

SimpleRoles

role

org.jboss.security.mapping.providers.DeploymentRolesMappingProvider

DeploymentRoles

role

org.jboss.security.mapping.providers.role.DatabaseRolesMappingProvider

DatabaseRoles

role

org.jboss.security.mapping.providers.role.LdapRolesMappingProvider

LdapRoles

role

org.jboss.security.mapping.providers.attribute.LdapAttributeMappingProvider

LdapAttributes

attribute

org.jboss.security.mapping.providers.DeploymentRoleToRolesMappingProvider

 

role

org.jboss.security.mapping.providers.attribute.DefaultAttributeMappingProvider

 

attribute

Note

The mapping module functionality is only invoked for role type mapping modules. To invoke other mapping module types, the mapping functionality needs to be invoked in the application or in a custom login module.

10.1. PropertiesRolesMappingProvider

Code: PropertiesRoles

Class: org.jboss.security.mapping.providers.role.PropertiesRolesMappingProvider

Type: role

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

OptionTypeDefaultDescription

rolesProperties

String

roles.properties

Properties formatted file name. Expansion of JBoss EAP variables can be used in form of ${jboss.variable}.

10.2. SimpleRolesMappingProvider

Code: SimpleRoles

Class: org.jboss.security.mapping.providers.role.SimpleRolesMappingProvider

Type: role

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

<module-option name="JavaDuke" value="JBossAdmin,Admin"/>
<module-option name="joe" value="Users"/>

10.3. DeploymentRolesMappingProvider

Code: DeploymentRoles

Class: org.jboss.security.mapping.providers.DeploymentRolesMappingProvider

Type: role

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

<jboss-web>
...
​  <security-role>
​      <role-name>Support</role-name>
​      <principal-name>Mark</principal-name>
​      <principal-name>Tom</principal-name>
​  </security-role>
...
</jboss-web>

10.4. DatabaseRolesMappingProvider

Code: DatabaseRoles

Class: org.jboss.security.mapping.providers.role.DatabaseRolesMappingProvider

Type: role

A MappingProvider that reads roles from a database.

OptionTypeDefaultDescription

dsJndiName

String

 

JNDI name of data source used to map roles to the user.

rolesQuery

String

 

This option should be a prepared statement equivalent to select RoleName from Roles where User=?. ? is substituted with current principal name.

suspendResume

boolean

true

If true, will suspend and later resume transaction associated with current thread while performing search for roles.

transactionManagerJndiName

String

java:/TransactionManager

JNDI name of transaction manager.

10.5. LdapRolesMappingProvider

Code: LdapRoles

Class: org.jboss.security.mapping.providers.role.LdapRolesMappingProvider

Type: role

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

OptionTypeDefaultDescription

bindDN

String

 

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

String

 

The password for the bindDN. This can be encrypted via the vault mechanism.

rolesCtxDN

String

 

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

String

role

The LDAP attribute which contains the names of authorization roles.

roleAttributeIsDN

boolean

false

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

String

name

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

boolean

false

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

String

 

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. An example search filter that matches on the input username is (member={0}).

roleRecursion

number

0

The numbers of levels of recursion the role search will go below a matching context. Disable recursion by setting this to 0.

searchTimeLimit

number

10000

The timeout in milliseconds for the user/role searches.

searchScope

String

SUBTREE_SCOPE

The search scope to use.

10.6. LdapAttributeMappingProvider

Code: LdapAttributes

Class: org.jboss.security.mapping.providers.attribute.LdapAttributeMappingProvider

Type: attribute

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

Examples of Standard Property Names

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"

OptionTypeDefaultDescription

bindDN

String

 

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

String

 

The password for the bindDN. This can be encrypted if the jaasSecurityDomain is specified.

baseCtxDN

String

 

The fixed DN of the context to start the user search from.

baseFilter

String

 

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 substitution behavior comes from the standard DirContext.search(Name, String, Object[], SearchControls cons) method. A common example search filter is (uid={0}).

searchTimeLimit

number

10000

The timeout in milliseconds for the user/role searches.

attributeList

String

 

A comma-separated list of attributes for the user. For example, mail,cn,sn,employeeType,employeeNumber.

jaasSecurityDomain

String

 

The JaasSecurityDomain to use to decrypt the java.naming.security.credentials. The encrypted form of the password is that returned by the JaasSecurityDomain#decode64(String) method. The org.jboss.security.plugins.PBEUtils can also be used to generate the encrypted form.

10.7. DeploymentRoleToRolesMappingProvider

Class: org.jboss.security.mapping.providers.DeploymentRoleToRolesMappingProvider

Type: role

A Role to Roles Mapping Module that takes into consideration a role to roles mapping. This can be defined in the deployment descriptors jboss-web.xml and jboss-app.xml. In this case, all the principal-name elements denote the roles that will replace the given role in role-name. ⁠

Example

<jboss-web>
...
​    <security-role>
​      <role-name>Employee</role-name>
​      <principal-name>Support</principal-name>
​      <principal-name>Sales</principal-name>
    </security-role>
...
</jboss-web>

In the above example, each principal having the role Employee will have this role replaced with Support and Sales. If it is desired for the principal to retain the Employee role as well as gain the Support and Sales roles, <principal-name>Employee</principal-name> should be added.

Note

This mapping provider does not have a code associated with it so the full class name must be in the code field when configuring.

10.8. DefaultAttributeMappingProvider

Class: org.jboss.security.mapping.providers.attribute.DefaultAttributeMappingProvider

Type: attribute

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

Example

<module-option name="admin.email" value="jduke@redhat.com"/>

In the above example, the attribute email with a value jduke@redhat.com is added for the principal admin.

Note

This mapping provider does not have a code associated with it so the full class name must be in the code field when configuring.





Revised on 2019-09-26 10:41:37 UTC