14.3. Configuring an External LDAP Provider

Procedure 14.1. Configuring an External LDAP Provider

1. On the Red Hat Enterprise 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. 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 engine service for the changes to take effect.

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

   

   Figure 14.1. The Administration Portal Login Page

   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.
4. 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 14.3.2, “Attaching an Active Directory”.

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

5. 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]:

6. Select a DNS policy method by entering the corresponding number:

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

   • For option 1, the DNS servers listed in /etc/resolv.conf is used to resolve the IP address. Ensure the /etc/resolv.conf file is updated with the correct DNS servers.
     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. For example: dig _ldap._tcp.redhat.com SRV.
   • For option 2, enter the domain name of the DNS server. A DNS search is performed to look up the SRV records to find out the domain name of the LDAP server.
   • 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.
7. 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 default location for all CA files. If the insecure mode is selected, the connection is still encrypted using TLS but certificate validation is skipped.

   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 SSL or TLS Connections between the Manager and an LDAP Server”.
8. 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 (empty for anonymous): uid=user1,ou=Users,dc=test,dc=redhat,dc=com
   Enter search user password:

9. Test the search and login function to ensure the your LDAP server is connected to your Red Hat Enterprise 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.
   Perform at least one Login sequence and one Search 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. Restart the engine service. The profile you have created is now available on the Administration Portal and the User Portal login pages. To assign the user accounts on the LDAP server appropriate roles and permissions, for example to log in to the User Portal, see Section 14.7, “Administering User Tasks From the Administration Portal”.

    # service ovirt-engine restart

Procedure 14.2. Configuring an External LDAP Provider

1. On the Red Hat Enterprise 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. 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 14.2. The Administration Portal Login Page

   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.
4. Select an LDAP type by entering the corresponding number. The LDAP related questions after this step is different for different LDAP types.

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

5. 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

6. 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 SSL or TLS Connections between the Manager and an LDAP Server”.
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 of LDAP annotation. If anonymous search is allowed, press Enter without any input.

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

8. Test the search and login function to ensure your LDAP server is connected to your Red Hat Enterprise 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.
   Perform at least one Login sequence and one Search 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

9. The profile you have created is now available on the Administration Portal and the User Portal login pages. To assign the user accounts on the LDAP server appropriate roles and permissions, for example to log in to the User Portal, see Section 14.7, “Administering User Tasks From the Administration Portal”.

Procedure 14.3. Configuring an External LDAP Provider Manually

1. On the Red Hat Enterprise 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 User 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 14.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 SSL or TLS Connections between the Manager and an LDAP Server”.

   Example 14.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 User 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 14.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 14.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:

   # service ovirt-engine restart

9. The example profile you have created is now available on the Administration Portal and the User Portal login pages. To give the user accounts on the LDAP server appropriate permissions, for example to log in to the User Portal, see the Red Hat Enterprise Virtualization Manager User Tasks section of the Red Hat Enterprise Virtualization Administration Guide.