10.12.2. Use LDAP to Authenticate to the Management Interfaces

To use an LDAP directory server as the authentication source for the Management Console, Management CLI, or Management API, you need to perform the following procedures:
  1. Create an outbound connection to the LDAP server.
  2. Create an LDAP-enabled security realm.
  3. Reference the new security domain in the Management Interface.
Create an Outbound Connection to an LDAP Server

The LDAP outbound connection allows the following attributes:

Table 10.1. Attributes of an LDAP Outbound Connection

Attribute Required Description
url yes
The URL address of the directory server.
search-dn yes
The fully distinguished name (DN) of the user authorized to perform searches.
search-credentials yes
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.

Example 10.13. Add an LDAP Outbound Connection

This example adds an outbound connection with the following properties set:
  • Search DN: cn=search,dc=acme,dc=com
  • Search Credential: myPass
  • URL: ldap://127.0.0.1:389
The first command adds the security realm. 
/host=master/core-service=management/security-realm=ldap_security_realm:add
The second command adds the LDAP connection. 
/host=master/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")
Create an LDAP-Enabled Security Realm

The Management Interfaces can authenticate against LDAP server instead of the property-file based security realms configured by default. The LDAP authenticator operates by first establishing a 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. A new connection is established, using the DN of the user as the credential, and password supplied by the user. If this authentication to the LDAP server is successful, the DN is verified to be valid.

The LDAP security realm needs the following configuration attributes and elements in order to perform its functions.
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.
One of username-filter or advanced-filter, as a child element
The username-filter takes a single attribute called attribute, whose value is the name of the LDAP attribute which holds the username, such as userName or sambaAccountName.
The advanced-filter takes a single attribute called filter. This attribute contains a filter query in standard LDAP syntax. Be cautious to escape any & characters by changing them to &amp;. An example of a filter is: 
(&(sAMAccountName={0})(memberOf=cn=admin,cn=users,dc=acme,dc=com))
After escaping the ampersand character, the filter appears as: 
(&amp;(sAMAccountName={0})(memberOf=cn=admin,cn=users,dc=acme,dc=com))

Example 10.14. XML Representing an LDAP-enabled Security Realm

This example uses the following parameters:
  • connection - ldap_connection
  • base-dn - cn=users,dc=acme,dc=com.
  • username-filter - attribute="sambaAccountName" 
<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>

Warning

It is important to ensure that you do not allow empty LDAP passwords; unless you specifically desire this in your environment, it is a serious security concern.
EAP 6.1 includes a patch for CVE-2012-5629, which sets the allowEmptyPasswords option for the LDAP login modules to false if the option is not already configured. For older versions, this option should be configured manually

Example 10.15. Add an LDAP Security Realm

The command below adds a security realm and sets its attributes for a standalone server. 
/host=master/core-service=management/security-realm=ldap_security_realm/authentication=ldap:add(base-dn="DC=mycompany,DC=org", recursive=true, username-attribute="MyAccountName", connection="ldap_connection")
Apply the New Security Realm to the Management Interface

After you create a security realm, you need to reference it in the configuration of your management interface. The management interface will use the security realm for HTTP digest authentication.

Example 10.16. Apply the Security Realm to the HTTP Interface

After this configuration is in place, and you restart the host controller, the web-based Management Console will use LDAP to authenticate its users. 
/host=master/core-service=management/management-interface=http-interface/:write-attribute(name=security-realm,value=ldap-security-realm)
Configure a Managed Domain Member to Authenticate using Microsoft Active Directory

To configure a host in a managed domain to authenticate to Microsoft Active Directory, follow this procedure, which creates a security domain and maps roles to Active Directory groups, using JAAS authentication. This procedure is required because Microsoft Active Directory allows binding with an empty password. This procedure prevents an empty password from being used within the application platform.

Before performing this procedure, you need to know the name of your host controller. This example assumes the host controller is named master.

  1. Add a new <security-realm> named ldap_security_realm, and configure it to use JAAS.

    The following Management CLI commands add the new security realm and set its authentication mechanism. Change the name of the host as required. 
    /host=master/core-service=management/security-realm=ldap_security_realm/:add
    /host=master/core-service=management/security-realm=ldap_security_realm/authentication=jaas/:add(name=managementLDAPDomain)

  2. Configure the <http-interface> to use the new security realm.

    The following Management CLI command configures the HTTP interface. 
    /host=master/core-service=management/management-interface=http-interface/:write-attribute(name=security-realm,value=ldap_security_realm)

  3. Configure JBoss Enterprise Application Platform to add the custom JAAS configuration to its start-up parameters.

    Edit the EAP_HOME/bin/domain.conf file. Search for the HOST_CONTROLLER_JAVA_OPTS variable. This is where you add directives for the JVM which are needed before JBoss Enterprise Application Platform starts. The following is an example of the default contents of this parameter: 
    HOST_CONTROLLER_JAVA_OPTS="$JAVA_OPTS"
    Add the following directive to the line: -Djava.security.auth.login.config=/opt/jboss-eap-6.0/domain/configuration/jaas.conf"
    The edited line is similar to the following: 
    -Djava.security.auth.login.config=/opt/jboss-eap-6.0/domain/configuration/jaas.conf"

  4. Add the login module to the module options.

    In the same file, find the line containing the following: 
    JBOSS_MODULES_SYSTEM_PKGS="org.jboss.byteman"
    Change that line to read as follows. Make sure not to insert any extra spaces. 
    JBOSS_MODULES_SYSTEM_PKGS="org.jboss.byteman,com.sun.security.auth.login"
    Save and close the domain.conf file.

  5. Create the JAAS configuration which will be added to the classpath.

    Create a new file at the following location: EAP_HOME/domain/configuration/jaas.conf
    The file should contain the following contents. Edit the parameters to match your own environment. 
    managementLDAPDomain {
    org.jboss.security.auth.spi.LdapExtLoginModule required
        java.naming.factory.initial="com.sun.jndi.ldap.LdapCtxFactory"
        java.naming.provider.url="ldap://your_active_directory_host:389"
        java.naming.security.authentication="simple"
        bindDN="cn=Administrator,cn=users,dc=domain,dc=your_company,dc=com"
        bindCredential="password"
        baseCtxDN="cn=users,dc=domain,dc=redhat,dc=com"
        baseFilter="(&(sAMAccountName={0})(|(memberOf=cn=Domain Guests,cn=Users,dc=domain,dc=acme,dc=com)(memberOf=cn=Domain Admins,cn=Users,dc=domain,dc=acme,dc=com)))"
        allowEmptyPasswords="false"
        rolesCtxDN="cn=users,dc=domain,dc=acme,dc=com"
        roleFilter="(cn=no such group)"
        searchScope="SUBTREE_SCOPE";
};
  6. Restart JBoss Enterprise Application Platform and your HTTP interface uses your LDAP server for authentication.
Report a bug