SupportConsoleDevelopersStart a trialContact

15.3. Configuring an External LDAP Provider

15.3.1. Configuring an External LDAP Provider (Interactive Setup)

The ovirt-engine-extension-aaa-ldap extension allows users to customize their external directory setup easily. The ovirt-engine-extension-aaa-ldap extension supports many different LDAP server types, and an interactive setup script is provided to assist you with the setup for most LDAP types.

If the LDAP server type is not listed in the interactive setup script, or you want to do more customization, you can manually edit the configuration files. See Section 15.3.3, “Configuring an External LDAP Provider (Manual Method)” for more information.

For an Active Directory example, see Section 15.3.2, “Attaching an Active Directory”.

Prerequisites:

  • You must know the domain name of the DNS or the LDAP server.
  • To set up secure connection between the LDAP server and the Manager, ensure that a PEM-encoded CA certificate has been prepared.
  • Have at least one set of account name and password ready to perform search and login queries to the LDAP server.

Configuring an External LDAP Provider

  1. On the Red Hat Virtualization Manager, install the LDAP extension package: 

    # yum install ovirt-engine-extension-aaa-ldap-setup

  2. Run ovirt-engine-extension-aaa-ldap-setup to start the interactive setup: 

    # ovirt-engine-extension-aaa-ldap-setup

  3. Select an LDAP type by entering the corresponding number. If you are not sure which schema your LDAP server is, select the standard schema of your LDAP server type. For Active Directory, follow the procedure at Section 15.3.2, “Attaching an Active Directory”. 

    Available LDAP implementations:
 1 - 389ds
 2 - 389ds RFC-2307 Schema
 3 - Active Directory
 4 - IBM Security Directory Server
 5 - IBM Security Directory Server RFC-2307 Schema
 6 - IPA
 7 - Novell eDirectory RFC-2307 Schema
 8 - OpenLDAP RFC-2307 Schema
 9 - OpenLDAP Standard Schema
10 - Oracle Unified Directory RFC-2307 Schema
11 - RFC-2307 Schema (Generic)
12 - RHDS
13 - RHDS RFC-2307 Schema
14 - iPlanet
Please select:

  4. Press Enter to accept the default and configure domain name resolution for your LDAP server name: 

    It is highly recommended to use DNS resolution for LDAP server.
If for some reason you intend to use hosts or plain address disable DNS usage.
Use DNS (Yes, No) [Yes]:

  5. Select a DNS policy method:

    • For option 1, the DNS servers listed in /etc/resolv.conf are used to resolve the IP address. Check that the /etc/resolv.conf file is updated with the correct DNS servers.

    • For option 2, enter the fully qualified domain name (FQDN) or the IP address of the LDAP server. You can use the dig command with the SRV record to find out the domain name. An SRV record takes the following format: 

      _service._protocol.domain_name

      Example: dig _ldap._tcp.redhat.com SRV.

    • For option 3, enter a space-separated list of LDAP servers. Use either the FQDN or IP address of the servers. This policy provides load-balancing between the LDAP servers. Queries are distributed among all LDAP servers according to the round-robin algorithm.

    • For option 4, enter a space-separated list of LDAP servers. Use either the FQDN or IP address of the servers. This policy defines the first LDAP server to be the default LDAP server to respond to queries. If the first server is not available, the query will go to the next LDAP server on the list. 

      1 - Single server
2 - DNS domain LDAP SRV record
3 - Round-robin between multiple hosts
4 - Failover between multiple hosts
Please select:

  6. Select the secure connection method your LDAP server supports and specify the method to obtain a PEM-encoded CA certificate:

    • File allows you to provide the full path to the certificate.
    • URL allows you to specify a URL for the certificate.
    • Inline allows you to paste the content of the certificate in the terminal.
    • System allows you to specify the default location for all CA files.

    • Insecure skips certificate validation, but the connection is still encrypted using TLS. 

      NOTE:
It is highly recommended to use secure protocol to access the LDAP server.
Protocol startTLS is the standard recommended method to do so.
Only in cases in which the startTLS is not supported, fallback to non standard ldaps protocol.
Use plain for test environments only.
Please select protocol to use (startTLS, ldaps, plain) [startTLS]: startTLS
Please select method to obtain PEM encoded CA certificate (File, URL, Inline, System, Insecure):
Please enter the password:
      Note

      LDAPS stands for Lightweight Directory Access Protocol Over Secure Socket Links. For SSL connections, select the ldaps option.

  7. Enter the search user distinguished name (DN). The user must have permissions to browse all users and groups on the directory server. The search user must be specified in LDAP annotation. If anonymous search is allowed, press Enter without any input. 

    Enter search user DN (for example uid=username,dc=example,dc=com or leave empty for anonymous): uid=user1,ou=Users,ou=department-1,dc=example,dc=com
Enter search user password:

  8. Enter the base DN: 

    Please enter base DN (dc=redhat,dc=com) [dc=redhat,dc=com]: ou=department-1,dc=redhat,dc=com

  9. Select Yes if you intend to configure single sign-on for virtual machines. Note that the feature cannot be used with single sign-on to the Administration Portal feature. The script reminds you that the profile name must match the domain name. You will still need to follow the instructions in Configuring Single Sign-On for Virtual Machines in the Virtual Machine Management Guide. 

    Are you going to use Single Sign-On for Virtual Machines (Yes, No) [Yes]:

  10. Specify a profile name. The profile name is visible to users on the login page. This example uses redhat.com.

    Note

    To rename the profile after the domain has been configured, edit the ovirt.engine.aaa.authn.profile.name attribute in the /etc/ovirt-engine/extensions.d/redhat.com-authn.properties file. Restart the ovirt-engine service for the changes to take effect. 

    Please specify profile name that will be visible to users: redhat.com

    Figure 15.1. The Administration Portal Login Page

    AAA login profile
    Note

    Users must select the profile from the drop-down list when logging in for the first time. The information is stored in browser cookies and preselected the next time the user logs in.

  11. Test the login function to ensure your LDAP server is connected to your Red Hat Virtualization environment properly. For the login query, enter your user name and password: 

    NOTE:
It is highly recommended to test drive the configuration before applying it into engine.
Login sequence is executed automatically, but it is recommended to also execute Search sequence manually after successful Login sequence.

Please provide credentials to test login flow:
Enter user name:
Enter user password:
[ INFO  ] Executing login sequence...
...
[ INFO  ] Login sequence executed successfully

  12. Check that the user details are correct. If the user details are incorrect, select Abort: 

    Please make sure that user details are correct and group membership meets expectations (search for PrincipalRecord and GroupRecord titles).
Abort if output is incorrect.
Select test sequence to execute (Done, Abort, Login, Search) [Abort]:

  13. Manually testing the Search function is recommended. For the search query, select Principal for user accounts or Group for group accounts. Select Yes to Resolve Groups if you want the group account information for the user account to be returned. Three configuration files are created and displayed in the screen output. 

    Select test sequence to execute (Done, Abort, Login, Search) [Search]: Search
Select entity to search (Principal, Group) [Principal]:
Term to search, trailing '*' is allowed: testuser1
Resolve Groups (Yes, No) [No]:

  14. Select Done to complete the setup: 

    Select test sequence to execute (Done, Abort, Login, Search) [Abort]: Done
[ INFO  ] Stage: Transaction setup
[ INFO  ] Stage: Misc configuration
[ INFO  ] Stage: Package installation
[ INFO  ] Stage: Misc configuration
[ INFO  ] Stage: Transaction commit
[ INFO  ] Stage: Closing up
CONFIGURATION SUMMARY
Profile name is: redhat.com
The following files were created:
    /etc/ovirt-engine/aaa/redhat.com.properties
    /etc/ovirt-engine/extensions.d/redhat.com.properties
    /etc/ovirt-engine/extensions.d/redhat.com-authn.properties
[ INFO  ] Stage: Clean up
Log file is available at /tmp/ovirt-engine-extension-aaa-ldap-setup-20171004101225-mmneib.log:
[ INFO  ] Stage: Pre-termination
[ INFO  ] Stage: Termination

  15. Restart the ovirt-engine service. The profile you have created is now available on the Administration Portal and the VM Portal login pages. To assign the user accounts on the LDAP server appropriate roles and permissions, for example, to log in to the VM Portal, see Section 15.6, “Administering User Tasks From the Administration Portal”. 

    # systemctl restart ovirt-engine.service
Note

For more information, see the LDAP authentication and authorization extension README file at /usr/share/doc/ovirt-engine-extension-aaa-ldap-version.

15.3.2. Attaching an Active Directory

Prerequisites

  • You need to know the Active Directory forest name. The forest name is also known as the root domain name.

    Note

    Examples of the most common Active Directory configurations, which cannot be configured using the ovirt-engine-extension-aaa-ldap-setup tool, are provided in /usr/share/ovirt-engine-extension-aaa-ldap/examples/README.md.

  • You need to either add the DNS server that can resolve the Active Directory forest name to the /etc/resolv.conf file on the Manager, or note down the Active Directory DNS servers and enter them when prompted by the interactive setup script.
  • To set up secure connection between the LDAP server and the Manager, ensure a PEM-encoded CA certificate has been prepared. See Section D.2, “Setting Up Encrypted Communication between the Manager and an LDAP Server” for more information.
  • Unless anonymous search is supported, a user with permissions to browse all users and groups must be available on the Active Directory to be used as the search user. Note down the search user’s distinguished name (DN). Do not use the administrative user for the Active Directory.
  • You must have at least one account name and password ready to perform search and login queries to the Active Directory.
  • If your Active Directory deployment spans multiple domains, be aware of the limitation described in the /usr/share/ovirt-engine-extension-aaa-ldap/profiles/ad.properties file.

Configuring an External LDAP Provider

  1. On the Red Hat Virtualization Manager, install the LDAP extension package: 

    # yum install ovirt-engine-extension-aaa-ldap-setup

  2. Run ovirt-engine-extension-aaa-ldap-setup to start the interactive setup: 

    # ovirt-engine-extension-aaa-ldap-setup

  3. Select an LDAP type by entering the corresponding number. The LDAP-related questions after this step are different for different LDAP types. 

    Available LDAP implementations:
 1 - 389ds
 2 - 389ds RFC-2307 Schema
 3 - Active Directory
 4 - IBM Security Directory Server
 5 - IBM Security Directory Server RFC-2307 Schema
 6 - IPA
 7 - Novell eDirectory RFC-2307 Schema
 8 - OpenLDAP RFC-2307 Schema
 9 - OpenLDAP Standard Schema
10 - Oracle Unified Directory RFC-2307 Schema
11 - RFC-2307 Schema (Generic)
12 - RHDS
13 - RHDS RFC-2307 Schema
14 - iPlanet
Please select: 3

  4. Enter the Active Directory forest name. If the forest name is not resolvable by your Manager’s DNS, the script prompts you to enter a space-separated list of Active Directory DNS server names. 

    Please enter Active Directory Forest name: ad-example.redhat.com
[ INFO  ] Resolving Global Catalog SRV record for ad-example.redhat.com
[ INFO  ] Resolving LDAP SRV record for ad-example.redhat.com

  5. Select the secure connection method your LDAP server supports and specify the method to obtain a PEM-encoded CA certificate. The file option allows you to provide the full path to the certificate. The URL option allows you to specify a URL to the certificate. Use the inline option to paste the content of the certificate in the terminal. The system option allows you to specify the location for all CA files. The insecure option allows you to use startTLS in insecure mode. 

    NOTE:
It is highly recommended to use secure protocol to access the LDAP server.
Protocol startTLS is the standard recommended method to do so.
Only in cases in which the startTLS is not supported, fallback to non standard ldaps protocol.
Use plain for test environments only.
Please select protocol to use (startTLS, ldaps, plain) [startTLS]: startTLS
Please select method to obtain PEM encoded CA certificate (File, URL, Inline, System, Insecure): File
Please enter the password:
    Note

    LDAPS stands for Lightweight Directory Access Protocol Over Secure Socket Links. For SSL connections, select the ldaps option.

    For more information on creating a PEM-encoded CA certificate, see Section D.2, “Setting Up Encrypted Communication between the Manager and an LDAP Server”.

  6. Enter the search user distinguished name (DN). The user must have permissions to browse all users and groups on the directory server. The search user must be of LDAP annotation. If anonymous search is allowed, press Enter without any input. 

    Enter search user DN (empty for anonymous): cn=user1,ou=Users,dc=test,dc=redhat,dc=com
Enter search user password:

  7. Specify whether to use single sign-on for virtual machines. This feature is enabled by default, but cannot be used if single sign-on to the Administration Portal is enabled. The script reminds you that the profile name must match the domain name. You will still need to follow the instructions in Configuring Single Sign-On for Virtual Machines in the Virtual Machine Management Guide. 

    Are you going to use Single Sign-On for Virtual Machines (Yes, No) [Yes]:

  8. Specify a profile name. The profile name is visible to users on the login page. This example uses redhat.com. 

    Please specify profile name that will be visible to users:redhat.com

    Figure 15.2. The Administration Portal Login Page

    AAA login profile
    Note

    Users need to select the desired profile from the drop-down list when logging in for the first time. The information is then stored in browser cookies and preselected the next time the user logs in.

  9. Test the search and login function to ensure your LDAP server is connected to your Red Hat Virtualization environment properly. For the login query, enter the account name and password. For the search query, select Principal for user accounts, and select Group for group accounts. Enter Yes to Resolve Groups if you want the group account information for the user account to be returned. Select Done to complete the setup. Three configuration files are created and displayed in the screen output. 

    NOTE:
It is highly recommended to test drive the configuration before applying it into engine.
Login sequence is executed automatically, but it is recommended to also execute Search sequence manually after successful Login sequence.
Select test sequence to execute (Done, Abort, Login, Search) [Abort]: Login
Enter search user name: testuser1
Enter search user password:
[ INFO  ] Executing login sequence...
...
Select test sequence to execute (Done, Abort, Login, Search) [Abort]: Search
Select entity to search (Principal, Group) [Principal]:
Term to search, trailing '*' is allowed: testuser1
Resolve Groups (Yes, No) [No]:
[ INFO  ] Executing login sequence...
...
Select test sequence to execute (Done, Abort, Login, Search) [Abort]: Done
[ INFO  ] Stage: Transaction setup
[ INFO  ] Stage: Misc configuration
[ INFO  ] Stage: Package installation
[ INFO  ] Stage: Misc configuration
[ INFO  ] Stage: Transaction commit
[ INFO  ] Stage: Closing up
          CONFIGURATION SUMMARY
          Profile name is: redhat.com
          The following files were created:
              /etc/ovirt-engine/aaa/redhat.com.properties
              /etc/ovirt-engine/extensions.d/redhat.com-authz.properties
              /etc/ovirt-engine/extensions.d/redhat.com-authn.properties
[ INFO  ] Stage: Clean up
          Log file is available at /tmp/ovirt-engine-extension-aaa-ldap-setup-20160114064955-1yar9i.log:
[ INFO  ] Stage: Pre-termination
[ INFO  ] Stage: Termination
  10. The profile you have created is now available on the Administration Portal and the VM Portal login pages. To assign the user accounts on the LDAP server appropriate roles and permissions, for example, to log in to the VM Portal, see Section 15.6, “Administering User Tasks From the Administration Portal”.
Note

For more information, see the LDAP authentication and authorization extension README file at /usr/share/doc/ovirt-engine-extension-aaa-ldap-version.

15.3.3. Configuring an External LDAP Provider (Manual Method)

The ovirt-engine-extension-aaa-ldap extension uses the LDAP protocol to access directory servers and is fully customizable. Kerberos authentication is not required unless you want to enable the single sign-on to the VM Portal or the Administration Portal feature.

If the interactive setup method in the previous section does not cover your use case, you can manually modify the configuration files to attach your LDAP server. The following procedure uses generic details. Specific values depend on your setup.

Configuring an External LDAP Provider Manually

  1. On the Red Hat Virtualization Manager, install the LDAP extension package: 

    # yum install ovirt-engine-extension-aaa-ldap

  2. Copy the LDAP configuration template file into the /etc/ovirt-engine directory. Template files are available for active directories (ad) and other directory types (simple). This example uses the simple configuration template. 

    # cp -r /usr/share/ovirt-engine-extension-aaa-ldap/examples/simple/. /etc/ovirt-engine

  3. Rename the configuration files to match the profile name you want visible to users on the Administration Portal and the VM Portal login pages: 

    # mv /etc/ovirt-engine/aaa/profile1.properties /etc/ovirt-engine/aaa/example.properties
# mv /etc/ovirt-engine/extensions.d/profile1-authn.properties /etc/ovirt-engine/extensions.d/example-authn.properties
# mv /etc/ovirt-engine/extensions.d/profile1-authz.properties /etc/ovirt-engine/extensions.d/example-authz.properties

  4. Edit the LDAP property configuration file by uncommenting an LDAP server type and updating the domain and passwords fields: 

    #  vi /etc/ovirt-engine/aaa/example.properties

    Example 15.1. Example profile: LDAP server section

    # Select one
#
include = <openldap.properties>
#include = <389ds.properties>
#include = <rhds.properties>
#include = <ipa.properties>
#include = <iplanet.properties>
#include = <rfc2307-389ds.properties>
#include = <rfc2307-rhds.properties>
#include = <rfc2307-openldap.properties>
#include = <rfc2307-edir.properties>
#include = <rfc2307-generic.properties>

# Server
#
vars.server = ldap1.company.com

# Search user and its password.
#
vars.user = uid=search,cn=users,cn=accounts,dc=company,dc=com
vars.password = 123456

pool.default.serverset.single.server = ${global:vars.server}
pool.default.auth.simple.bindDN = ${global:vars.user}
pool.default.auth.simple.password = ${global:vars.password}

    To use TLS or SSL protocol to interact with the LDAP server, obtain the root CA certificate for the LDAP server and use it to create a public keystore file. Uncomment the following lines and specify the full path to the public keystore file and the password to access the file.

    Note

    For more information on creating a public keystore file, see Section D.2, “Setting Up Encrypted Communication between the Manager and an LDAP Server”.

    Example 15.2. Example profile: keystore section

    # Create keystore, import certificate chain and uncomment
# if using tls.
pool.default.ssl.startTLS = true
pool.default.ssl.truststore.file = /full/path/to/myrootca.jks
pool.default.ssl.truststore.password = password

  5. Review the authentication configuration file. The profile name visible to users on the Administration Portal and the VM Portal login pages is defined by ovirt.engine.aaa.authn.profile.name. The configuration profile location must match the LDAP configuration file location. All fields can be left as default. 

    # vi /etc/ovirt-engine/extensions.d/example-authn.properties

    Example 15.3. Example authentication configuration file

    ovirt.engine.extension.name = example-authn
ovirt.engine.extension.bindings.method = jbossmodule
ovirt.engine.extension.binding.jbossmodule.module = org.ovirt.engine-extensions.aaa.ldap
ovirt.engine.extension.binding.jbossmodule.class = org.ovirt.engineextensions.aaa.ldap.AuthnExtension
ovirt.engine.extension.provides = org.ovirt.engine.api.extensions.aaa.Authn
ovirt.engine.aaa.authn.profile.name = example
ovirt.engine.aaa.authn.authz.plugin = example-authz
config.profile.file.1 = ../aaa/example.properties

  6. Review the authorization configuration file. The configuration profile location must match the LDAP configuration file location. All fields can be left as default. 

    # vi /etc/ovirt-engine/extensions.d/example-authz.properties

    Example 15.4. Example authorization configuration file

    ovirt.engine.extension.name = example-authz
ovirt.engine.extension.bindings.method = jbossmodule
ovirt.engine.extension.binding.jbossmodule.module = org.ovirt.engine-extensions.aaa.ldap
ovirt.engine.extension.binding.jbossmodule.class = org.ovirt.engineextensions.aaa.ldap.AuthzExtension
ovirt.engine.extension.provides = org.ovirt.engine.api.extensions.aaa.Authz
config.profile.file.1 = ../aaa/example.properties

  7. Ensure that the ownership and permissions of the configuration profile are appropriate: 

    # chown ovirt:ovirt /etc/ovirt-engine/aaa/example.properties
# chmod 600 /etc/ovirt-engine/aaa/example.properties

  8. Restart the engine service: 

    # systemctl restart ovirt-engine.service
  9. The example profile you have created is now available on the Administration Portal and the VM Portal login pages. To give the user accounts on the LDAP server appropriate permissions, for example, to log in to the VM Portal, see Section 15.6, “Administering User Tasks From the Administration Portal”.
Note

For more information, see the LDAP authentication and authorization extension README file at /usr/share/doc/ovirt-engine-extension-aaa-ldap-version.

15.3.4. Removing an External LDAP Provider

This procedure shows you how to remove an external configured LDAP provider and its users.

Removing an External LDAP Provider

  1. Remove the LDAP provider configuration files, replacing the default name profile1: 

    # rm /etc/ovirt-engine/extensions.d/profile1-authn.properties
# rm /etc/ovirt-engine/extensions.d/profile1-authz.properties
# rm /etc/ovirt-engine/aaa/profile1.properties

  2. Restart the ovirt-engine service: 

    # systemctl restart ovirt-engine
  3. In the Administration Portal, in the Users resource tab, select the users of this provider (those whose Authorization provider is profile1-authz) and click Remove.
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.