Red Hat Summit Red Hat SummitSupportConsoleDéveloppeursCommencer un essaiContact

Ce contenu n'est pas disponible dans la langue sélectionnée.

How to Configure Identity Management

Red Hat JBoss Enterprise Application Platform 6.4

How to Configure Identity Management

Red Hat Customer Content Services

Abstract

The intent of this guide is to explore the topic of how to use LDAP directories and other identity stores for user identities and identity management in Red Hat JBoss Enterprise Application Platform 6. This guide expands on basics of LDAP and other concepts covered in the Red Hat JBoss Enterprise Application Platform 6 Security Architecture guide. Specifically, this document provides a practical guide for setting up JBoss EAP 6 to use LDAP for user identity in the Management Interfaces as well setting up LDAP and other identity stores with security domains for use with web applications.
The target audience of this document is JBoss EAP 6 administrators looking for an introduction on configuring LDAP servers and other identity stores for use with the management interfaces and security domains. Before reading this guide, users should read through the Red Hat JBoss Enterprise Application Platform 6 Security Architecture guide and have a solid understanding of security concepts within JBoss EAP 6 as well as some base knowledge surrounding LDAP. This document also makes use of the JBoss EAP 6 CLI interface for performing configuration changes. For more information on using the CLI for both standalone JBoss EAP 6 instances as well as JBoss EAP 6 domains, please consult The Management CLI section of the Red Hat JBoss Enterprise Application Platform 6 Administration and Configuration Guide. After completing this document, readers should have solid foundational knowledge of how LDAP and other identity stores relate to user identities with JBoss EAP 6 as well as a practical understanding of how to configure identity management in JBoss EAP 6.

Chapter 1. Identity Management Overview

The basics behind identity management and identity stores are covered in the Single Sign On (SSO) section of the Red Hat JBoss Enterprise Application Platform 6 Security Architecture guide document. These concepts can also be applied to providing security for the JBoss EAP 6 management interfaces and web applications outside of SSO. More specifically, this document covers configuring different identity stores for identity management in JBoss EAP 6 for securing the management interfaces (LDAP) as well with security domains (LDAP, Database, and Filesystem).

Chapter 2. LDAP Overview

The basics of LDAP as well as a basic use case are described in the LDAP and Example Scenarios sections of the Red Hat JBoss Enterprise Application Platform 6 Security Architecture guide document. It also describes the LDAP-related login modules for security domains in the Security Subsystem section.

In general, LDAP, in the context of JBoss EAP 6, is used as an identity store for security domains and security realms. It can be used to make authentication decisions as well as serve as an authorization authority for JBoss EAP and applications deployed to it. Various role and access information about principals can be stored in an LDAP directory which may be used directly by JBoss EAP 6 or mapped to existing JBoss EAP 6 roles.

Note

Similar to using a database or other external datastores to house identity information, performance of data access and data transport between the datastore and the JBoss EAP 6 instance may have a performance impact on authenticating and authorizing principals.

Chapter 3. Securing the Management Interfaces with LDAP

The Management Interfaces can authenticate against an LDAP server (including Microsoft Active Directory) instead of the property-file based security realms configured by default. This is accomplished by using an LDAP authenticator. An LDAP authenticator operates by first establishing a connection (using an outbound LDAP connection) to the remote directory server. It then performs a search using the username which the user passed to the authentication system, to find the fully-qualified distinguished name (DN) of the LDAP record. If successful, a new connection is established, using the DN of the user as the credential, and password supplied by the user. If this second connection and authentication to the LDAP server is successful, the DN is verified to be valid and authentication has succeeded.

Note

Securing the Management Interfaces with LDAP changes the authentication from digest to BASIC/Plain, which by default, will cause usernames and passwords to be sent over the network in the clear. SSL/TLS can be enabled on the outbound connection to encrypt this traffic and avoid sending this information in the clear.

3.1. Basic setup

To use an LDAP directory server as the authentication source for any or all of the management interfaces, the following procedures must be performed:

  1. Create an outbound connection to the LDAP server.
  2. Create a new LDAP-enabled Security Realm and reference the outbound connection.
  3. Reference the new security realm in the Management Interface.

3.1.1. 1. Creating an Outbound Connection to the LDAP Server

The purpose of creating an outbound LDAP connection is to allow the security realm (and the JBoss EAP instance) to establish a connection to the LDAP server. This is similar to the case of creating a datasource for use with the Database login module in a security domain.

The LDAP outbound connection allows the following attributes:

AttributeRequiredDescription

url

yes

The URL address of the directory server.

search-dn

no

The fully distinguished name (DN) of the user authorized to perform searches.

search-credential

no

The password of the user authorized to perform searches.

initial-context-factory

no

The initial context factory to use when establishing the connection. Defaults to com.sun.jndi.ldap.LdapCtxFactory.

security-realm

no

The security realm to reference to obtain a configured SSLContext to use when establishing the connection.

referrals

no

Specifies the behavior when encountering a referral when doing a search. Valid options are IGNORE, FOLLOW, and THROW. INGORE (default behavior) simply ignores the referral. If set to FOLLOW, when referrals are encountered during a search, the DirContext being used will attempt to follow that referral. This assumes the same connection settings can be used to connect to the second server and the name used in the referral is reachable. If set to THROW, then the DirContext will throw an exception (LdapReferralException) to indicate that a referral is required, which the security realm will handle and attempt to identify an alternative connection to use for the referral.

handles-referrals-for

no

Specifies the referrals a connection can handle. If specifying list of URIs, they should be separated by spaces. This enables a connection with connection properties to be defined and used when different credentials are needed to follow a referral. This is useful in situations where different credentials are needed to authenticate against the second server or for situations where the server returns a name in the referral that is not reachable from the JBoss EAP 6 installation and an alternative address can be substituted.

Note

The search-dn and search-credential are different than the username and password provided by the user. The information provided here is specifically for establishing an initial connection between the JBoss EAP instance and the LDAP server. This connection allows JBoss EAP to perform a subsequent search for the DN of the user trying to authenticate. The DN of the user (which is a result of the search) trying to authenticate and the password they provided are used to establish a second (and separate) connection for completing the authentication process.

Given the example LDAP server, below are the CLI commands and resulting XML configuration for configuring an outbound LDAP connection to it:

Table 3.1. Example LDAP Server
AttributeValue

url

127.0.0.1:389

search-credential

myPass

search-dn

cn=search,dc=acme,dc=com

CLI for Adding the Outbound Connection

/core-service=management/ldap-connection=ldap-connection/:add( \
search-credential=myPass, \
url=ldap://127.0.0.1:389, \
search-dn="cn=search,dc=acme,dc=com")

reload

Resulting XML

<outbound-connections>
  <ldap name="ldap-connection"
        url="ldap://127.0.0.1:389"
        search-dn="cn=search,dc=acme,dc=com"
        search-credential="myPass"/>
</outbound-connections>

Note

The above CLI commands were done assuming a standalone instance of JBoss EAP 6. For more details on using the CLI with JBoss EAP 6 domains, please consult The Management CLI section of the Red Hat JBoss Enterprise Application Platform 6 Administration and Configuration Guide.

Note

This creates an clear connection between the JBoss EAP instance and the LDAP server. For more details on setting up an encrypted connection using SSL/TLS, please see the Section 3.2, “Using SSL/TLS for the Outbound LDAP Connection”.

3.1.2. 2. Creating a new LDAP-Enabled Security Realm

Once the outbound LDAP connection has been created, a new LDAP-Enabled security realm must be created to use it.

The LDAP security realm has the following configuration attributes:

AttributeDescription

connection

The name of the connection defined in outbound-connections to use to connect to the LDAP directory.

base-dn

The distinguished name of the context to begin searching for the user.

recursive

Whether the search should be recursive throughout the LDAP directory tree, or only search the specified context. Defaults to false.

user-dn

The attribute of the user that holds the distinguished name. This is subsequently used to test authentication as the user can complete. Defaults to dn.

allow-empty-passwords

This attribute determines whether an empty password is accepted. The default value for this attribute is false.

username-attribute

Either username-attribute or advanced-filter must be specified. The name of the attribute to search for the user. This filter performs a simple search where the user name entered by the user matches the specified attribute.

advanced-filter

Either username-attribute or advanced-filter must be specified. The fully defined filter used to search for a user based on the supplied user ID. This attribute contains a filter query in standard LDAP syntax. The filter must contain a variable in the following format: {0}. This is later replaced with the user name supplied by the user. More specifics and examples on using advanced-filter can be found in the <advanced-filter> part of the Combining LDAP and RBAC for Authorization section.

Warning

It is important to ensure that empty LDAP passwords are not allowed since it is a serious security concern. Unless this behavior is specifically desired in the environment, ensure empty passwords are not allowed and allow-empty-passwords remains false.

Here are the CLI commands and resulting XML configuration for configuring an LDAP-enabled security realm using the ldap-connection outbound LDAP connection.

CLI

/core-service=management/security-realm=ldap-security-realm:add

/core-service=management/security-realm=ldap-security-realm/authentication=ldap:add( \
connection="ldap-connection", base-dn="cn=users,dc=acme,dc=com", \
username-attribute="sambaAccountName")
reload

Resulting XML

<security-realm name="ldap-security-realm">
  <authentication>
    <ldap connection="ldap-connection" base-dn="cn=users,dc=acme,dc=com">
      <username-filter attribute="sambaAccountName"/>
    </ldap>
  </authentication>
</security-realm>

Note

The above CLI commands were done assuming a standalone instance of JBoss EAP 6. For more details on using the CLI with JBoss EAP 6 domains, please consult The Management CLI section of the Red Hat JBoss Enterprise Application Platform 6 Administration and Configuration Guide.

3.1.3. 3. Reference the new security realm in the Management Interface

Once a security realm has been created and is using the outbound LDAP connection, that new security realm must be referenced by the management interfaces.

CLI Command for Updating the HTTP Interface

/core-service=management/management-interface=http-interface/:write-attribute( \
name=security-realm,value="ldap-security-realm")

CLI Command for Updating the Native Interface

/core-service=management/management-interface=native-interface/:write-attribute( \
name=security-realm,value="ldap-security-realm")

Resulting XML

<management-interfaces>
  <native-interface security-realm="ldap-security-realm">
    <socket-binding native="management-native"/>
  </native-interface>
  <http-interface security-realm="ldap-security-realm">
    <socket-binding http="management-http"/>
  </http-interface>
</management-interfaces>

Note

The above CLI commands were done assuming a standalone instance of JBoss EAP 6. For more details on using the CLI with JBoss EAP 6 domains, please consult The Management CLI section of the Red Hat JBoss Enterprise Application Platform 6 Administration and Configuration Guide.

3.2. Using SSL/TLS for the Outbound LDAP Connection

JBoss EAP 6 can be configured to use an outbound connection to an LDAP server using SSL/TLS. To create an outbound LDAP connection secured by SSL/TLS, the following procedures must be performed:

  1. Configure a security realm with a keystore and truststore for the outbound LDAP connection to use.
  2. Create an Outbound LDAP Connection with the SSL/TLS URL and Security Realm.
  3. Create a new security realm that uses the outbound ldap connection for use by the management interfaces.

3.2.1. 1. Configuring a Security Realm for the Outbound LDAP Connection to Use

The security realm must contain a keystore configured with the key that the JBoss EAP 6 server will use to decrypt/encrypt communications between itself and the LDAP server. This keystore will also allow the JBoss EAP 6 instance to verify itself against the LDAP server. The security realm must also contain a truststore that contains the LDAP server’s certificate (or the certificate of the certificate authority used to sign the LDAP server’s certificate). See Setting up 2-Way SSL/TLS for the Management Interfaces in the JBoss EAP 6 How to Configure Server Security guide for instructions on configuring keystores and truststores and creating a security realm that uses them.

3.2.2. 2. Create an Outbound LDAP Connection with the SSL/TLS URL and Security Realm

Similar to the process defined in Creating an Outbound Connection to the LDAP Server, an outbound LDAP connection should be created, but using the SSL/TLS URL for the LDAP server and the SSL/TLS security realm.

Once the outbound LDAP connection and SSL/TLS security realm for the LDAP server have been created, the the outbound LDAP connection needs to be updated with that information.

Example CLI for Adding the Outbound Connection with an SSL/TLS URL

/core-service=management/ldap-connection=ldap-connection/:add( \
search-credential=myPass, \
url=ldaps://LDAP_HOST:LDAP_PORT, \
search-dn="cn=search,dc=acme,dc=com")

Adding the security realm with the SSL/TLS certificates

/core-service=management/ldap-connection=ldap-connection:write-attribute( \
name=security-realm,value="CertificateRealm")

reload

Resulting XML

<outbound-connections>
  <ldap name="ldap-connection" url="ldaps://LDAP_HOST:LDAP_PORT"
  security-realm="CertificateRealm"
  search-dn="cn=search,dc=acme,dc=com"
  search-credential="myPass" />
</outbound-connections>

Note

The above CLI commands were done assuming a standalone instance of JBoss EAP 6. For more details on using the CLI with JBoss EAP 6 domains, please consult The Management CLI section of the Red Hat JBoss Enterprise Application Platform 6 Administration and Configuration Guide.

3.2.3. 3. Creating a New Security Realm that uses the Outbound LDAP Connection for use by the Management Interfaces

Follow the procedures outlined in sections Creating a new LDAP-Enabled Security Realm and Reference the new security realm in the Management Interface.

3.3. LDAP and RBAC

RBAC (Role-Based Access Control) is a mechanism for specifying a set of permissions (roles) for a set of management users, allowing users to be granted different management responsibilities without giving them full, unrestricted access. For more specific details on RBAC, please see the Role-Based Access Control section of the Red Hat JBoss Enterprise Application Platform 6 Security Architecture guide.

RBAC is used only for authorization, with authentication being handled separately. Since LDAP can be used for authentication as well as authorization, JBoss EAP 6 may be configured to use RBAC for authorization without LDAP (using LDAP or any other mechanism for authentication). JBoss EAP 6 may also be configured to use RBAC combined with LDAP for making authorization decisions in the management interfaces.

3.3.1. Using LDAP and RBAC Independently

JBoss EAP 6 allows for authentication and authorization to be configured independently in security realms. This enables LDAP to be configured as an authentication mechanism and RBAC to be configured as an authorization mechanism. If configured in this manner, when a user attempts to access a management interface, they will first be authenticated using the configured LDAP server. If successful, the user’s role (and configured permissions of that role) will be determined using only RBAC (independent of any group information found in the LDAP server).

For more details on using just RBAC as an authorization mechanism for the management interfaces, please see the Server Security guide. For more details on configuring LDAP for authentication with the management interfaces, please see the previous section on the topic.

3.3.2. Combining LDAP and RBAC for Authorization

Users who have authenticated using an LDAP server (or using the properties file), can be members of user groups. A user group is simply an arbitrary label that can be assigned to one or more users. RBAC can be configured to use this group information to automatically assign a role to a user or exclude a user from a role.

An LDAP directory contains entries for user accounts and groups, cross referenced by attributes. Depending on the LDAP server configuration, a user entity may map the groups the user belongs to through memberOf attributes; a group entity may map which users belong to it through uniqueMember attributes; or a combination of the two. Once a user is successfully authenticated to the LDAP server, a group search is performed to load that user’s group information. Depending on the directory server in use, group searches can be performed using their simple name (usually the username used in authentication) or by using the distinguished name of the user’s entry in the directory. Group searches (<group-search>) as well as mapping between a username and a distinguished name (<username-to-dn>) are configured when setting up LDAP as an authorization mechanism in a security realm.

Once a user’s group membership information is determined from the LDAP server, a mapping within the RBAC configuration is used to determine what role(s) a user has. This mapping is configured to explicitly include or exclude groups as well as individual users.

Note

The authentication step of a user connecting to the server always happens first. Once the user is successfully authenticated the server loads the user’s groups. The authentication step and the authorization step each require a connection to the LDAP server. The security realm optimizes this process by reusing the authentication connection for the group loading step.

3.3.2.2. Using username-to-dn

It is possible to define rules within the authorization section to convert a user’s simple user name to their distinguished name. The username-to-dn element specifies how to map the user name to the distinguished name of their entry in the LDAP directory. This element is optional and only required when both of the following are true:

  • The authentication and authorization steps are against different LDAP servers.
  • The group search uses the distinguished name.
Note

This could also be applicable in instances where the security realm supports both LDAP and Kerberos authentication and a conversion is needed for Kerberos, if LDAP authentication has been performed the DN discovered during authentication can be used.

It contains the following attributes:

Table 3.5. username-to-dn
AttributeDescription

force

The result of a user name to distinguished name mapping search during authentication is cached and reused during the authorization query when the force attribute is set to "false". When force is true, the search is performed again during authorization (while loading groups). This is typically done when different servers perform authentication and authorization.

username-to-dn can be configured with one of the following:

<username-is-dn>
This specifies that the user name entered by the remote user is the user’s distinguished name.

username-is-dn Example

<security-realm name="ldap-security-realm">
  <authentication>
    <ldap connection="ldap-connection" >
      <!-- configuration -->
    </ldap>
  </authentication>
  <authorization>
    <ldap connection="ldap-connection">
      <username-to-dn force="false">
        <username-is-dn />
      </username-to-dn>
      <!-- configuration -->
    </ldap>
  </authorization>
</security-realm>

This defines a 1:1 mapping and there is no additional configuration.

<username-filter>
A specified attribute is searched for a match against the supplied user name.

username-filter Example

<security-realm name="ldap-security-realm">
  <authentication>
    <ldap connection="ldap-connection" >
      <!-- configuration -->
    </ldap>
  </authentication>
  <authorization>
    <ldap connection="ldap-connection">
      <username-to-dn force="true">
        <username-filter base-dn="dc=people,dc=harold,dc=example,dc=com" recursive="false" attribute="sn" user-dn-attribute="dn" />
      </username-to-dn>
      <!-- configuration -->
    </ldap>
  </authorization>
</security-realm>

AttributeDescription

base-dn

The distinguished name of the context to begin the search.

recursive

Whether the search will extend to sub contexts. Defaults to false.

attribute

The attribute of the users entry to try and match against the supplied user name. Defaults to uid.

user-dn-attribute

The attribute to read to obtain the users distinguished name. Defaults to dn.

<advanced-filter>
This option uses a custom filter to locate the users distinguished name.

advanced-filter Example

<security-realm name="ldap-security-realm">
  <authentication>
    <ldap connection="ldap-connection" >
      <!-- configuration -->
    </ldap>
  </authentication>
  <authorization>
    <ldap connection="ldap-connection">
      <username-to-dn force="true">
        <advanced-filter base-dn="dc=people,dc=harold,dc=example,dc=com" recursive="false" filter="sAMAccountName={0}" user-dn-attribute="dn" />
      </username-to-dn>
      <!-- configuration -->
    </ldap>
  </authorization>
</security-realm>

For the attributes that match those in the username-filter example, the meaning and default values are the same. There is one additional attribute:

AttributeDescription

filter

Custom filter used to search for a user’s entry where the user name will be substituted in the {0} place holder.

Important

The XML must remain valid after the filter is defined so if any special characters are used (such as &) ensure the proper form is used. For example &amp; for the & character.

3.3.2.3. Mapping LDAP Group Information to RBAC Roles

Once the connection to the LDAP server has been created and the group searching has been properly configured, a mapping needs to be created between the LDAP groups and RBAC roles. This mapping can be both inclusive as well as exclusive and enables users to be automatically assigned one or more roles based on their group membership information.

Warning

If RBAC is not already configured, pay close attention when doing so, especially if switching to a newly-created LDAP-enabled realm. Enabling RBAC without having users and roles properly configured could result in administrators being unable to login to the management interfaces.

Note

The below CLI commands were done assuming a standalone instance of JBoss EAP 6. For more details on using the CLI with JBoss EAP 6 domains, please consult The Management CLI section of the Red Hat JBoss Enterprise Application Platform 6 Administration and Configuration Guide.

Ensure RBAC is Enabled and Configured

Before mappings between LDAP and RBAC Roles can be used, RBAC must enabled and initially configured. 

/core-service=management/access=authorization:read-attribute(name=provider)

It should yield the following result: 

{
    "outcome" => "success",
    "result" => "rbac"
}

For more information on enabling and configuring RBAC, please see the Enabling Role-Based Access Control section of the Red Hat JBoss Enterprise Application Platform 6 How to Configure Server Security guide.

Verify Existing List of Roles

Use the read-children-names operation to get a complete list of the configured roles: 

/core-service=management/access=authorization:read-children-names(child-type=role-mapping)

Which should yield a list of roles: 

{
    "outcome" => "success",
    "result" => [
        "Administrator",
        "Deployer",
        "Maintainer",
        "Monitor",
        "Operator",
        "SuperUser"
    ]
}

In addition, all existing mappings for a role may be checked: 

/core-service=management/access=authorization/role-mapping=Administrator:read-resource(recursive=true)
{
    "outcome" => "success",
    "result" => {
        "include-all" => false,
        "exclude" => undefined,
        "include" => {
            "user-theboss" => {
                "name" => "theboss",
                "realm" => undefined,
                "type" => "USER"
            },
            "user-harold" => {
                "name" => "harold",
                "realm" => undefined,
                "type" => "USER"
            },
            "group-SysOps" => {
                "name" => "SysOps",
                "realm" => undefined,
                "type" => "GROUP"
            }
        }
    }
}

Configure a Role-Mapping entry

If a role does not already have a Role-Mapping entry, one needs to be created. For instance: 

/core-service=management/access=authorization/role-mapping=Auditor:read-resource()
{
    "outcome" => "failed",
    "failure-description" => "JBAS014807: Management resource '[
    (\"core-service\" => \"management\"),
    (\"access\" => \"authorization\"),
    (\"role-mapping\" => \"Auditor\")
]' not found"
}

To add a role mapping: 

/core-service=management/access=authorization/role-mapping=Auditor:add()
{
    "outcome" => "success"
}

To verify: 

/core-service=management/access=authorization/role-mapping=Auditor:read-resource()
{
    "outcome" => "success",
    "result" => {
        "include-all" => false,
        "exclude" => undefined,
        "include" => undefined
    }
}
⁠

Add Groups to the Role for Inclusion and Exclusion

Groups may be added for inclusion or exclusion from a role.

Note

The exclusion mapping takes precedence or the inclusion mapping.

To add a group for inclusion: 

/core-service=management/access=authorization/role-mapping=Auditor/include=group-GroupToInclude:add(name=GroupToInclude, type=GROUP)

To add a group for exclusion: 

/core-service=management/access=authorization/role-mapping=Auditor/exclude=group-GroupToExclude:add(name=GroupToExclude, type=GROUP)

To check the result: 

[standalone@localhost:9999 /] /core-service=management/access=authorization/role-mapping=Auditor:read-resource(recursive=true)
{
    "outcome" => "success",
    "result" => {
        "include-all" => false,
        "exclude" => {"group-GroupToExclude" => {
            "name" => "GroupToExclude",
            "realm" => undefined,
            "type" => "GROUP"
        }},
        "include" => {"group-GroupToInclude" => {
            "name" => "GroupToInclude",
            "realm" => undefined,
            "type" => "GROUP"
        }}
    }
}

Removing a Group from a Role

Groups that are added for exclusion or inclusion may also be removed

To remove a group from inclusion: 

/core-service=management/access=authorization/role-mapping=Auditor/include=group-GroupToInclude:remove

To remove a group from exclusion: 

/core-service=management/access=authorization/role-mapping=Auditor/exclude=group-GroupToExclude:remove

3.4. Enabling Caching

Security Realms also offer the ability to cache the results of LDAP queries for both authentication as well as group loading. This enables the results of different queries to be reused across multiple searches by different users in certain circumstances (e.g. iteratively querying the group membership information of groups). There are three different caches available, each of which are configured separately and operate independently:

  • authentication
  • group-to-principal
  • username-to-dn

3.4.1. Cache Configuration

Even though the caches are independent of one another, all three are configured in the same manner. Each cache offers the following configuration options:

AttributeDescription

type

This defines the eviction straregy that the cache will adhere to. Options are by-access-time and by-search-time. by-access-time evicts items from the cache after a certain period of time has elapsed since their last access. by-search-time evicts items based on how long they have been in the cache regardless of their last access.

eviction-time

This defines the time (in seconds) used for evictions depending on the strategy.

cache-failures

This is a boolean that enables/disables the caching of failed searches. This has the potential for preventing an LDAP server from being repeatedly access by the same failed search, but it also has the potential to fill up the cache with searches for users that do not exist. This setting is particularly important for the authentication cache.

max-cache-size

This defines maximum size (number of items) of the cache, which in-turn dictates when items will begin getting evicted. Old items are evicted from the cache to make room for new authentication and searches as needed, meaning max-cache-size will not prevent new authentication attempts or searches from occuring.

3.4.2. Example

Note

This example assumes a security realm has been created named LDAPRealm that connects to an existing LDAP server and is configured for authentication and authorization. The commands to display the current configuration are detailed in a later section. More details on creating a security realm that uses LDAP can be found here.

Example Base Configuration

​"core-service" : {
​        "management" : {
​            "security-realm" : {
​                "LDAPRealm" : {
​                    "authentication" : {"ldap" : {
​                        "allow-empty-passwords" : false,
​                        "base-dn" : "...",
​                        "connection" : "MyLdapConnection",
​                        "recursive" : false,
​                        "user-dn" : "dn",
​                        "username-attribute" : "uid",
​                        "cache" : null
​                    }},
​                    "authorization" : {"ldap" : {
​                        "connection" : "MyLdapConnection",
​                        "group-search" : {"group-to-principal" : {
​                            "base-dn" : "...",
​                            "group-dn-attribute" : "dn",
​                            "group-name" : "SIMPLE",
​                            "group-name-attribute" : "uid",
​                            "iterative" : true,
​                          "principal-attribute" : "uniqueMember",
​                            "search-by" : "DISTINGUISHED_NAME",
​                            "cache" : null
​                        }},
​                        "username-to-dn" : {"username-filter" : {
​                            "attribute" : "uid",
​                            "base-dn" : "...",
​                            "force" : false,
​                            "recursive" : false,
​                            "user-dn-attribute" : "dn",
​                            "cache" : null
​                        }}
​                    }},
​                }
​            }
​        }

In all areas where "cache" : null appear, a cache may be configured:

Authentication
During authentication the user’s distinguished name is discovered using this definition and an attempt to connect to the LDAP server and verify their identity is made using these credentials.
A group-search definition
There is the group search definition, in this case it is an iterative search (because iterative is set to true in the sample configuration above). First, a search will be performed to find all groups the user is a direct member of. After that, a search will be performed for each of those groups to identify if they have membership to other groups. This process continues until either a cyclic reference is detected or the final groups are not members of any further groups.
A username-to-dn definition in group search
Group searching relies on the availability of the users distinguished name. This section is not used in all situations, but it can be used as a second attempt to discover a user’s distinguished name. This, for instance, may be useful or even required when a second form of authentication was supported (e.g. local authentication).
3.4.2.1. Reading the Current Cache Configuration
Note

The CLI commands used in this and subsequent sections use LDAPRealm for the name of the security realm. This should be substituted for the name of the actual realm being configured.

CLI Command to Read the Current Cache Configuration

/core-service=management/security-realm=LDAPRealm:read-resource(recursive=true)

Output

​​{
​    "outcome" => "success",
​    "result" => {
​        "map-groups-to-roles" => true,
​        "authentication" => {"ldap" => {
​            "advanced-filter" => undefined,
​            "allow-empty-passwords" => false,
​            "base-dn" => "dc=example,dc=com",
​            "connection" => "ldapConnection",
​            "recursive" => true,
​            "user-dn" => "dn",
​            "username-attribute" => "uid",
​            "cache" => undefined
​        }},
​        "authorization" => {"ldap" => {
​            "connection" => "ldapConnection",
​            "group-search" => {"principal-to-group" => {
​                "group-attribute" => "description",
​                "group-dn-attribute" => "dn",
​                "group-name" => "SIMPLE",
​                "group-name-attribute" => "cn",
​                "iterative" => false,
​                "prefer-original-connection" => true,
​                "skip-missing-groups" => false,
​                "cache" => undefined
​            }},
​            "username-to-dn" => {"username-filter" => {
​                "attribute" => "uid",
​                "base-dn" => "ou=Users,dc=jboss,dc=org",
​                "force" => true,
​                "recursive" => false,
​                "user-dn-attribute" => "dn",
​                "cache" => undefined
​            }}
​        }},
​        "plug-in" => undefined,
​        "server-identity" => undefined
​    }
​}

3.4.2.2. Enabling a Cache
Note

The CLI commands used in this and subsequent sections configure the cache in the authentication portion of the security realm (i.e. /authentication=ldap/). Caches in the authorization portion may also be configured in a similar manner by updating the path of the command.

CLI for Enabling a Cache

/core-service=management/security-realm=LDAPRealm/authentication=ldap/cache=by-access-time:add( \
eviction-time=300, cache-failures=true, max-cache-size=100)

This commands adds a by-access-time cache for authentication with an eviction time of 300 seconds (5 minutes) and a max cache size of 100 items. In addition, failed searches will be cached. Alternatively, a by-search-time cache could also be configured: 

/core-service=management/security-realm=LDAPRealm/authentication=ldap/cache=by-search-time:add( \
eviction-time=300, cache-failures=true, max-cache-size=100)
3.4.2.3. Inspecting an Existing Cache

CLI for Inspecting an Existing Cache

/core-service=management/security-realm=LDAPRealm/authentication=ldap/cache=by-access-time:read-resource(include-runtime=true)

Output

{
    "outcome" => "success",
    "result" => {
        "cache-failures" => true,
        "cache-size" => 1,
        "eviction-time" => 300,
        "max-cache-size" => 100
    }
}

The include-runtime attribute adds the cache-size element, which displays the current number of items in the cache (1 in this case).

3.4.2.4. Testing an Existing Cache’s Contents

CLI for Testing an Existing Cache’s Contents

/core-service=management/security-realm=LDAPRealm/authentication=ldap/cache=by-access-time:contains(name=TestUserOne)

Output

{
    "outcome" => "success",
    "result" => true
}

This shows that an entry for TestUserOne exists the in the cache.

3.4.2.5. Flushing a Cache

An entire cache may be flushed as can individual items from a cache.

CLI for Flushing a Single Item

/core-service=management/security-realm=LDAPRealm/authentication=ldap/cache=by-access-time:flush-cache(name=TestUserOne)

CLI for Flushing an Entire Cache

/core-service=management/security-realm=LDAPRealm/authentication=ldap/cache=by-access-time:flush-cache()

3.4.2.6. Removing a Cache

CLI for Removing a Cache

/core-service=management/security-realm=LDAPRealm/authentication=ldap/cache=by-access-time:remove()

reload

Chapter 4. Configuring a Security Domain to use LDAP

Security domains can be configured to use an LDAP server for authentication and authorization by using a login module. The basics of security domains and login modules are covered in the Red Hat JBoss Enterprise Application Platform 6 Security Architecture guide. LdapExtended is the preferred login module for integrating with LDAP servers (including Active Directory), but there are several other LDAP login modules that can be used as well. Specifically, the Ldap, AdvancedLdap, and AdvancedAdLdap can also be used to configure a security domain to use LDAP. This section uses the LdapExtended login module to illustrate how to create a security domain that uses an LDAP for authentication and authorization, but the other LDAP login modules may be used as well. For more details on the other LDAP login modules, please see the Red Hat JBoss Enterprise Application Platform 6 Security Guide.

4.1. LdapExtended Login Module

The LdapExtended (org.jboss.security.auth.spi.LdapExtLoginModule) is a login module implementation that uses searches to locate the bind user and associated roles on LDAP server. The roles query recursively follows DNs to navigate a hierarchical role structure. For the vast majority of cases when using LDAP with security domains, the LdapExtedned login module should be used, especially with LDAP implementations that are not Active Directory.

Table 4.1. Complete LdapExtended Login Module Configuration Options
OptionTypeDefaultDescription

java.naming.factory.initial

class name

com.sun.jndi.ldap.LdapCtxFactory

InitialContextFactory implementation class name.

java.naming.provider.url

ldap:// URL

If the value of java.naming.security.protocol is SSL, ldap://localhost:636, otherwise ldap://localhost:389

URL for the LDAP server.

java.naming.security.authentication

none, simple, or the name of a SASL mechanism

The default is simple. If the property is explicitly undefined, the behavior is determined by the service provider.

The security level to use to bind to the LDAP server.

java.naming.security.protocol

transport protocol

If unspecified, determined by the provider.

The transport protocol to use for secure access, such as SSL.

baseCtxDN

fully-qualified DN

none

The fixed DN of the top-level context to begin the user search.

bindCredential

string, optionally encrypted

none

Used to store the credentials for the DN.

bindDN

fully-qualified DN

none

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.

baseFilter

LDAP filter string

none

A search filter used to locate the context of the user to authenticate. The input username or userDN obtained from the login module callback is substituted into the filter anywhere a {0} expression is used. A common example for the search filter is (uid={0}).

rolesCtxDN

fully-qualified DN

none

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.

roleFilter

LDAP filter string

none

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}).

roleAttributeID

attribute

roles

Name of the attribute containing the user roles.

roleAttributeIsDN

true or false

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.

defaultRole

Role name

none

A role included for all authenticated users

parseRoleNameFromDN

true or false

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.

parseUsername

true or false

false

A flag indicating if the DN is to be parsed for the username. If set to true, the DN is parsed for the username. If set to false the DN is not parsed for the username. This option is used together with usernameBeginString and usernameEndString.

usernameBeginString

string

none

Defines the string which is to be removed from the start of the DN to reveal the username. This option is used together with usernameEndString.

usernameEndString

string

none

Defines the string which is to be removed from the end of the DN to reveal the username. This option is used together with usernameBeginString.

roleNameAttributeID

attribute

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.

distinguishedNameAttribute

attribute

distinguishedName

The name of the attribute in the user entry that contains the DN of the user. This may be necessary if the DN of the user itself contains special characters (backslash for example) that prevent correct user mapping. If the attribute does not exist, the entry’s DN is used.

roleRecursion

integer

0

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

searchTimeLimit

integer

10000 (10 seconds)

The timeout in milliseconds for user or role searches.

searchScope

One of: OBJECT_SCOPE, ONELEVEL_SCOPE, SUBTREE_SCOPE

SUBTREE_SCOPE

The search scope to use.

allowEmptyPasswords

true or false

false

Whether to allow empty passwords. Most LDAP servers treat empty passwords as anonymous login attempts. To reject empty passwords, set this to false.

referralUserAttributeIDToCheck

attribute

none

If you are not using referrals, this option can be ignored. When using referrals, this option denotes the attribute name which contains users defined for a certain role (for example, member), if the role object is inside the referral. Users are checked against the content of this attribute name. If this option is not set, the check will always fail, so role objects cannot be stored in a referral tree.

The authentication happens as follows:

  1. An initial bind to the LDAP server is done using the bindDN and bindCredential options. The bindDN is a LDAP user with the ability to search both the baseCtxDN and rolesCtxDN trees for the user and roles. The user DN to authenticate against is queried using the filter specified by the baseFilter attribute.
  2. The resulting user DN is authenticated by binding to the LDAP server using the user DN as the InitialLdapContext environment Context.SECURITY_PRINCIPAL. The Context.SECURITY_CREDENTIALS property is set to the String password obtained by the callback handler.

4.1.1. Configuring a Security Domain to use the LdapExtended Login Module

Example Data (LDIF format)

dn: uid=jduke,ou=Users,dc=jboss,dc=org
objectClass: inetOrgPerson
objectClass: person
objectClass: top
cn: Java Duke
sn: duke
uid: jduke
userPassword: theduke
# =============================
dn: uid=hnelson,ou=Users,dc=jboss,dc=org
objectClass: inetOrgPerson
objectClass: person
objectClass: top
cn: Horatio Nelson
sn: Nelson
uid: hnelson
userPassword: secret
# =============================
dn: ou=groups,dc=jboss,dc=org
objectClass: top
objectClass: organizationalUnit
ou: groups
# =============================
dn: uid=ldap,ou=Users,dc=jboss,dc=org
objectClass: inetOrgPerson
objectClass: person
objectClass: top
cn: LDAP
sn: Service
uid: ldap
userPassword: randall
# =============================
dn: ou=Users,dc=jboss,dc=org
objectClass: top
objectClass: organizationalUnit
ou: Users
# =============================
dn: dc=jboss,dc=org
objectclass: top
objectclass: domain
dc: jboss
# =============================
dn: uid=GroupTwo,ou=groups,dc=jboss,dc=org
objectClass: top
objectClass: groupOfNames
objectClass: uidObject
cn: GroupTwo
member: uid=jduke,ou=Users,dc=jboss,dc=org
uid: GroupTwo
# =============================
dn: uid=GroupThree,ou=groups,dc=jboss,dc=org
objectClass: top
objectClass: groupOfUniqueNames
objectClass: uidObject
cn: GroupThree
uid: GroupThree
uniqueMember: uid=GroupOne,ou=groups,dc=jboss,dc=org
# =============================
dn: uid=HTTP,ou=Users,dc=jboss,dc=org
objectClass: inetOrgPerson
objectClass: person
objectClass: top
cn: HTTP
sn: Service
uid: HTTP
userPassword: httppwd
# =============================
dn: uid=GroupOne,ou=groups,dc=jboss,dc=org
objectClass: top
objectClass: groupOfUniqueNames
objectClass: uidObject
cn: GroupOne
uid: GroupOne
uniqueMember: uid=jduke,ou=Users,dc=jboss,dc=org
uniqueMember: uid=hnelson,ou=Users,dc=jboss,dc=org

CLI Commands for Adding the LdapExtended Login Module

/subsystem=security/security-domain=testLdapExtendedExample:add(cache-type=default)

/subsystem=security/security-domain=testLdapExtendedExample/authentication=classic:add
/subsystem=security/security-domain=testLdapExtendedExample/authentication=classic/login-module=LdapExtended:add( \
  code=LdapExtended, \
  flag=required, \
  module-options=[ \
    ("java.naming.factory.initial"=>"com.sun.jndi.ldap.LdapCtxFactory"), \
    ("java.naming.provider.url"=>"ldap://localhost:10389"), \
    ("java.naming.security.authentication"=>"simple"), \
    ("bindDN"=>"uid=ldap,ou=Users,dc=jboss,dc=org"), \
    ("bindCredential"=>"randall"), \
    ("baseCtxDN"=>"ou=Users,dc=jboss,dc=org"), \
    ("baseFilter"=>"(uid={0})"), \
    ("rolesCtxDN"=>"ou=groups,dc=jboss,dc=org"), \
    ("roleFilter"=>"(uniqueMember={1})"), \
    ("roleAttributeID"=>"uid"), \
  ])
reload

Resulting XML

<security-domain name="testLdapExtendedExample" cache-type="default">
  <authentication>
    <login-module code="LdapExtended" flag="required">
      <module-option name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory"/>
      <module-option name="java.naming.provider.url" value="ldap://localhost:10389"/>
      <module-option name="java.naming.security.authentication" value="simple"/>
      <module-option name="bindDN" value="uid=ldap,ou=Users,dc=jboss,dc=org"/>
      <module-option name="bindCredential" value="randall"/>
      <module-option name="baseCtxDN" value="ou=Users,dc=jboss,dc=org"/>
      <module-option name="baseFilter" value="(uid={0})"/>
      <module-option name="rolesCtxDN" value="ou=groups,dc=jboss,dc=org"/>
      <module-option name="roleFilter" value="(uniqueMember={1})"/>
      <module-option name="roleAttributeID" value="uid"/>
    </login-module>
  </authentication>
</security-domain>

Note

The above CLI commands were done assuming a standalone instance of JBoss EAP 6. For more details on using the CLI with JBoss EAP 6 domains, please consult The Management CLI section of the Red Hat JBoss Enterprise Application Platform 6 Administration and Configuration Guide.

4.1.1.1. Configuring a Security Domain to use the LdapExtended Login Module for Active Directory

For Microsoft Active Directory, the LdapExtended Login Module may be used.

Default AD Configuration

The example below represents the configuration for a default Active Directory configuration.

Some Active Directory configurations may require searching against the Global Catalog on port 3268 instead of the usual port 389. This is most likely when the Active Directory forest includes multiple domains.

Example Configuration for the LdapExtended Login Module for a Default AD Configuration

<security-domain name="AD_Default" cache-type="default">
  <authentication>
    <login-module code="LdapExtended" flag="required">
      <module-option name="java.naming.provider.url" value="ldap://ldaphost.jboss.org"/>
      <module-option name="bindDN" value="JBOSSsearchuser"/>
      <module-option name="bindCredential" value="password"/>
      <module-option name="baseCtxDN" value="CN=Users,DC=jboss,DC=org"/>
      <module-option name="baseFilter" value="(sAMAccountName={0})"/>
      <module-option name="rolesCtxDN" value="CN=Users,DC=jboss,DC=org"/>
      <module-option name="roleFilter" value="(sAMAccountName={0})"/>
      <module-option name="roleAttributeID" value="memberOf"/>
      <module-option name="roleAttributeIsDN" value="true"/>
      <module-option name="roleNameAttributeID" value="cn"/>
      <module-option name="searchScope" value="ONELEVEL_SCOPE"/>
      <module-option name="allowEmptyPasswords" value="false"/>
    </login-module>
  </authentication>
</security-domain>

Recursive AD Configuration

The example below implements a recursive role search within Active Directory. The key difference between this example and the default Active Directory example is that the role search has been replaced to search the member attribute using the DN of the user. The login module then uses the DN of the role to find groups of which the group is a member.

Example Configuration for the LdapExtended Login Module for a Default AD Configuration with Recursive Search

<security-domain name="AD_Recursive" cache-type="default">
  <authentication>
    <login-module code="LdapExtended" flag="required">
      <module-option name="java.naming.provider.url" value="ldap://ldaphost.jboss.org"/>
      <module-option name="java.naming.referral" value="follow"/>
      <module-option name="bindDN" value="JBOSSsearchuser"/>
      <module-option name="bindCredential" value="password"/>
      <module-option name="baseCtxDN" value="CN=Users,DC=jboss,DC=org"/>
      <module-option name="baseFilter" value="(sAMAccountName={0})"/>
      <module-option name="rolesCtxDN" value="CN=Users,DC=jboss,DC=org"/>
      <module-option name="roleFilter" value="(member={1})"/>
      <module-option name="roleAttributeID" value="cn"/>
      <module-option name="roleAttributeIsDN" value="false"/>
      <module-option name="roleRecursion" value="2"/>
      <module-option name="searchScope" value="ONELEVEL_SCOPE"/>
      <module-option name="allowEmptyPasswords" value="false"/>
    </login-module>
  </authentication>
</security-domain>

Chapter 5. Configuring a Security Domain to use a Database

Similar to LDAP, security domains can be configured to use a database for authentication and authorization by using a login module.

5.1. Database Login Module

The Database login module is a Java Database Connectivity-based (JDBC) login module that supports authentication and role mapping. This login module is used if username, password and role information are stored in a relational database.

This works by providing a reference to logical tables containing Principals and Roles in the expected format. For example: 

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 users 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 a Password of echoman in the Principals table
  • PrincipalID java with a role named Echo in the RolesRoleGroup in the Roles table
  • PrincipalID java with a role named caller-java in the CallerPrincipalRoleGroup in the Roles table
Table 5.1. Complete Database Login Module Options
OptionTypeDefaultDescription

digestCallback

A fully-qualified classname

none

The class name of the DigestCallback implementation that includes pre/post digest content like salts for hashing the input password. Only used if hashAlgorithm has been specified.

dsJndiName

A JNDI resource

java:/DefaultDS

The name of the JNDI resource storing the authentication information. This option is required.

hashAlgorithm

String

Use plain passwords

The message digest algorithm used to hash passwords. Supported algorithms depend on the Java Security Provider, but the following are supported: MD5, SHA-1, and SHA-256.

hashCharset

String

The platform’s default encoding

The name of the charset/encoding to use when converting the password String to a byte array. This includes all supported Java charset names.

hashEncoding

String

Base64

The string encoding format to use.

ignorePasswordCase

boolean

false

A flag indicating if the password comparison should ignore case.

inputValidator

A fully-qualified classname

none

The instance of the InputValidator implementation used to validate the username and password supplied by the client.

principalsQuery

prepared SQL statement

select Password from Principals where PrincipalID=?

The prepared SQL query to obtain the information about the principal.

rolesQuery

prepared SQL statement

none

The prepared SQL query to obtain the information about the roles. It should be equivalent to select Role, RoleGroup from Roles where PrincipalID=?, where Role is the role name and the RoleGroup column value should always be either Roles with a capital R or CallerPrincipal.

storeDigestCallback

A fully-qualified classname

none

The class name of the DigestCallback implementation that includes pre/post digest content like salts for hashing the store/expected password. Only used if hashStorePassword or hashUserPassword is true and hashAlgorithm has been specified.

suspendResume

boolean

true

Whether any existing JTA transaction should be suspended during database operations.

throwValidatorError

boolean

false

A flag that indicates whether validation errors should be exposed to clients or not

transactionManagerJndiName

JNDI Resource

java:/TransactionManager

The JNDI name of the transaction manager used by the login module.

5.1.1. Configuring a Security Domain to use the Database Login Module

Before configuring a security domain to use the Database login module, a datasource must be properly configured. For more information on creating and configure datasources in JBoss EAP 6 please see the Datasource Management section of the Red Hat JBoss Enterprise Application Platform 6 Administration and Configuration Guide.

Once a datasource has been properly configured, a security domain may be configured to use the Database login module. The below example assumes a datasource named MyDatabaseDS has been created and properly configured with a database that is constructed with the following: 

CREATE TABLE Users(username VARCHAR(64) PRIMARY KEY, passwd VARCHAR(64))
CREATE TABLE UserRoles(username VARCHAR(64), role VARCHAR(32))

CLI Commands for Adding the Database Login Module

/subsystem=security/security-domain=testDB:add

/subsystem=security/security-domain=testDB/authentication=classic:add
/subsystem=security/security-domain=testDB/authentication=classic/login-module=Database:add( \
  code=Database, \
  flag=required, \
  module-options=[ \
    ("dsJndiName"=>"java:/MyDatabaseDS"), \
    ("principalsQuery"=>"select passwd from Users where username=?"), \
    ("rolesQuery"=>"select role, 'Roles' from UserRoles where username=?") \
  ])
reload

Resulting XML

<security-domain name="testDB">
  <authentication>
    <login-module code="Database" flag="required">
      <module-option name="dsJndiName" value="java:/MyDatabaseDS"/>
      <module-option name="principalsQuery" value="select passwd from Users where username=?"/>
      <module-option name="rolesQuery" value="select role, 'Roles' from UserRoles where username=?"/>
    </login-module>
  </authentication>
</security-domain>

Chapter 6. Configuring a Security Domain to use a Filesystem

Security domains can also be configured to use a filesystem as an identity store for authentication and authorization by using a login module.

6.1. UsersRoles Login Module

UsersRoles login module is a simple login module that supports multiple users and user roles loaded from Java properties files. 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. The default username-to-password mapping filename is users.properties and the default username-to-roles mapping filename is roles.properties.

Note

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 on the classpath of the Java EE deployment (for example, into the WEB-INF/classes folder in the WAR archive), or into any directory on the server classpath.

Table 6.1. Complete UsersRoles Login Module Options
OptionTypeDefaultDescription

usersProperties

Path to a file or resource.

users.properties

The file or resource which contains the user-to-password mappings. The format of the file is username=password

rolesProperties

Path to a file or resource.

roles.properties

The file or resource which contains the user-to-role mappings. The format of the file is username=role1,role2,role3

password-stacking

useFirstPass or false

false

A value of useFirstPass indicates that this login module should first look to the information stored in the LoginContext for the identity. This option can be used when stacking other login modules with this one.

hashAlgorithm

String representing a password hashing algorithm.

none

The name of the java.security.MessageDigest algorithm to use to hash the password. There is no default so this option must be explicitly set to enable hashing. When hashAlgorithm is specified, the clear text password obtained from the CallbackHandler is hashed before it is passed to UsernamePasswordLoginModule.validatePassword as the inputPassword argument. The password stored in the users.properties file must be comparably hashed.

hashEncoding

base64 or hex

base64

The string format for the hashed password, if hashAlgorithm is also set.

hashCharset

string

The default encoding set in the container’s runtime environment

The encoding used to convert the clear-text password to a byte array.

unauthenticatedIdentity

principal name

none

Defines the principal name assigned to requests which contain no authentication information. This can allow unprotected servlets to invoke methods on EJBs that do not require a specific role. Such a principal has no associated roles and can only access unsecured EJBs or EJB methods that are associated with the unchecked permission constraint.

6.1.1. Configuring a Security Domain to use the UsersRoles Login Module

The below example assumes the following files have been created and are available on the application’s classpath:

  • sampleapp-users.properties
  • sampleapp-roles.properties

CLI Commands for Adding the UserRoles Login Module

/subsystem=security/security-domain=sampleapp:add

/subsystem=security/security-domain=sampleapp/authentication=classic:add
/subsystem=security/security-domain=sampleapp/authentication=classic/login-module=UsersRoles:add( \
  code=UsersRoles, \
  flag=required, \
  module-options=[ \
    ("usersProperties"=>"sampleapp-users.properties"), \
    ("rolesProperties"=>"sampleapp-roles.properties") \
  ])
reload

Resulting XML

<security-domain name="sampleapp">
  <authentication>
    <login-module code="UsersRoles" flag="required">
      <module-option name="usersProperties" value="sampleapp-users.properties"/>
      <module-option name="rolesProperties" value="sampleapp-roles.properties"/>
    </login-module>
  </authentication>
</security-domain>

Chapter 7. Configuring a Security Domain to use a Security Mapping

Adding a security mapping to a security domain allows for authentication and authorization information to be combined after the authentication or authorization happens, but before the information is passed to the application. For more information on security mapping, please see the Security Mapping section of the Red Hat JBoss Enterprise Application Platform 6 Security Architecture guide.

To add a security mapping to an existing security domain, a code, type, and relavant module options must be configured. The code field is the short name (e.g. SimpleRoles, PropertiesRoles, DatabaseRoles) or class name of the security mapping module. The type field refers to the type of mapping this module performs, and the allowed values are principal, role, attribute, or credential. For a full list of the available security mapping modules and their module options, refer to the Security Mapping Modules section of the Red Hat JBoss Enterprise Application Platform 6 Security Guide.

Example CLI Commands for Adding a SimpleRoles Security Mapping to an Existing Security Domain

/subsystem=security/security-domain=sampleapp/mapping=classic:add

/subsystem=security/security-domain=sampleapp/mapping=classic/mapping-module=SimpleRoles:add( \
code=SimpleRoles, \
type=role, \
module-options=[("user1"=>"specialRole")])
reload

Resulting XML

<security-domain name="sampleapp">
  <authentication>
  ...
  </authentication>
  <mapping>
    <mapping-module code="SimpleRoles" type="role">
      <module-option name="user1" value="specialRole"/>
    </mapping-module>
  </mapping>
</security-domain>

Chapter 8. Standalone vs. Domain Mode Considerations

Setting up identity management with an LDAP server (including Microsoft Active Directory) or any other identity store for Authentication and/or Authorization for both Security Realms as well as Security Domains are essentially the same regardless whether they are used in a standalone or managed domain. Just as with any other configuration setting, the standalone configuration resides in the standalone.xml file and the configuration for a managed domain resides in the domain.xml and host.xml files.

Legal Notice

Copyright © 2022 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Red Hat logoGithubRedditYoutubeTwitter

Apprendre

Essayez, achetez et vendez

Communautés

À propos de la documentation Red Hat

Nous aidons les utilisateurs de Red Hat à innover et à atteindre leurs objectifs grâce à nos produits et services avec un contenu auquel ils peuvent faire confiance. Découvrez nos récentes mises à jour.

Rendre l’open source plus inclusif

Red Hat s'engage à remplacer le langage problématique dans notre code, notre documentation et nos propriétés Web. Pour plus de détails, consultez le Blog Red Hat.

À propos de Red Hat

Nous proposons des solutions renforcées qui facilitent le travail des entreprises sur plusieurs plates-formes et environnements, du centre de données central à la périphérie du réseau.

© 2024 Red Hat, Inc.