Integrating users from an external directory service

Users in RedHat virtual

In order to interact with Red Hat Virtualization’s management system, user accounts need to be configured and granted access rights. These accounts can come from various sources called user domains. Users are identified by their User Principal Name (UPN) which has the form [email protected]

By default, the initial installation of Red Hat Virtualization creates a local domain called internal, which can contain local user accounts. An initial local user is created in this domain, with the UPN [email protected], which has full administrative control of the Red Hat Virtualization environment.

While it is possible to create additional local users by using the ovirt-aaa-jdbc-tool command, it is a better practice to configure an external domain that gets information about users from an external directory service such as Red Hat Identity Management, Active Directory, OpenLDAP, or one of the many other supported options. These users are referred to as directory users. This allows simplified user and group management from an operational standpoint by using the same single source of truth for RHV user information that the IT organization uses for other account management.

Administratively, users and groups are created in the directory service. Once the directory service is attached to Red Hat Virtualization as an external domain, the users from that service merely need to be configured in Red Hat Virtualization with roles that grant them appropriate levels of access to the Red Hat Virtualization environment.

Directory users can be granted administrative rights. The [email protected] account is generally better used as an emergency administration account if there is a problem with the connection to the directory service.

Attachment of more than one directory server to the Red Hat Virtualization environment is also possible and supported. In case administrators have more than one directory server attached, they are able to choose which one they want to authenticate against by selecting the correct domain from the login menu.

CONFIGURING AN EXTERNAL LDAP PROVIDER

The ovirt-engine-extension-aaa-ldap software package provides support for integration of generic LDAP-based directory services with RHVM. This includes Red Hat Identity Management, Active Directory, OpenLDAP, and a number of other LDAP servers.

The basic procedure to have that package configure RHVM to use an LDAP-based service as an external domain is straightforward. A helper package named ovirt-engine-extension-aaa-ldap-setup provides a configuration script and needs to be installed on your RHVM server. That package also installs ovirt-engine-extension-aaa-ldap as a dependency. Then the command ovirt-engineextension-aaa-ldap-setup is used to configure the LDAP integration with RHVM.

The following discussion looks at how this can be done for two use cases. The first example discusses how to configure Red Hat Identity Manager (based on FreeIPA) as a directory source. The second example does the same with Microsoft Active Directory.

Attaching Red Hat Identity Management (FreeIPA)

Red Hat Identity Management (IdM) is an open source centralized identity, policy, and authorization service included with Red Hat Enterprise Linux that provides an LDAP integration interface. It is based on the upstream FreeIPA project. You can use a Red Hat Identity Management or FreeIPA directory server as an authentication source for your Red Hat Virtualization environment.

There are three basic prerequisites that you need to meet before starting configuration:

  • You must know the fully-qualified DNS domain name of the LDAP server or servers.
  • For a secure LDAP connection, you must have a copy of the public TLS/SSL CA certificate that validates LDAP server’s TLS certificate, in PEM format.
  • You must have a password for an LDAP account that RHVM can use to perform search and login queries on the LDAP server, and you should get the base distinguished name (DN) that should be used for those searches from your directory administrator.

When all the prerequisites are met, you can start the integration process.

  1. On your Red Hat Virtualization Manager, install the ovirt-engine-extension-aaa-ldap-setup package, which also installs the ovirt-engine-extension-aaa-ldap LDAP extension package.
  2. Use the ovirt-engine-extension-aaa-ldap-setup command to start interactive configuration.
  3. From the list of available LDAP implementations, choose the appropriate one for your environment by entering the corresponding number. For Red Hat Identity Management, use IPA (currently number 6).
  4. You are asked whether you want to use DNS to resolve the name of your Identity Management server. Normally, the correct answer is Yes.
  5. Specify how RHVM should find your Red Hat Identity Management LDAP server. You are presented with four options that may be used.
    • Single server expects the fully-qualified domain name of the server.
    • DNS domain LDAP SRV record expects a DNS SRV record which can be used to locate the server.
    • Round-robin between multiple hosts expects a space-separated list of Identity Management servers, among which RHVM will load balance its LDAP requests.
    • Failover between multiple hosts expects a space-separated list of Identity Management servers, and RHVM will send all requests to the first server in the list and only failover to subsequent servers if preceding servers are not responding
  6. You are asked which protocol to use when communicating with the directory server. To protect the LDAP connection with the Identity Management server, it is recommended that you use the StartTLS protocol. You are asked which protocol to use when communicating with the directory server. To protect the LDAP connection with the Identity Management server, it is recommended that you use the StartTLS protocol.
  7. Enter the distinguished name (DN) of the LDAP user that RHVM may use to search the directory. Enter that user’s password (or if anonymous search is allowed, leave the password blank).
  8. Specify the base DN that RHVM should use when searching the LDAP directory.
  9. You are asked if you plan to configure single sign-on on virtual machines using the users provided by the Identity Management servers that you configured for this external domain. If so, enter Yes and look at the Additional Configuration instructions from the Red Hat Virtualization Virtual Machine Management Guide at https://access.redhat.com/documentation/en-us/red_hat_virtualization/4.1/html/ virtual_machine_management_guide/.
  10. Specify the name of the profile for the new external domain. This is the name that will appear in the menu on the login page for the Administration Portal. (This is the domain part of [email protected])
  11. The script prompts you for the username and password of a valid user provided by the Identity Management server. It uses this to attempt authentication as that user in order to test whether your connection to the server is working. You may also be prompted to try some other tests. When you are finished testing, enter Done and the script exits.
  12. Run systemctl restart ovirt-engine to restart the RHVM service.

Attaching Microsoft Active Directory

You can also use a Microsoft Active Directory server as an authentication source for your Red Hat Virtualization environment.

  • You need to know the Active Directory root domain name (the forest name).
  • You need to know the DNS servers that can resolve the Active Directory forest name.
  • For a secure LDAP connection, you must have a copy of the public TLS/SSL CA certificate that validates the Active Directory server’s TLS certificate, in PEM format.
  • You must have a password for an Active Directory account that RHVM can use to perform search and login queries to the server, unless you enable anonymous search.

When all the prerequisites are met, you can start the integration process.

  1. On your Red Hat Virtualization Manager, install the ovirt-engine-extension-aaa-ldap-setup package, which also installs the ovirt-engine-extension-aaa-ldap LDAP extension package.
  2. Use the ovirt-engine-extension-aaa-ldap-setup command to start interactive configuration.
  3. From the list of available LDAP implementations choose the appropriate one for your environment by entering the corresponding number. For Microsoft Active Directory, use Active Directory (currently number 3).
  4. Specify your Active Directory forest name.
  5. Select the secure protocol for accessing your LDAP server and specify the method used to obtain a CA certificate. Again, Red Hat recommends that you use the StartTLS protocol and provide a PEM-encoded CA certificate that can validate the Active Directory server certificate. Red Hat recommends that you do not select the Insecure option.
  6. Enter the distinguished name (DN) for the Active Directory user that RHVM may use to search the directory. The user must have permission to browse all users and groups on the Active Directory server. Enter that user’s password (or if anonymous search is allowed, leave the password blank).
  7. Specify the name of the profile for the new external domain.
  8. The script prompts you for the username and password of a valid user provided by the Active Directory server to test whether the connection to the server is working. When you have completed testing, enter Done and the script exits.
  9. Run systemctl restart ovirt-engine to restart the RHVM service.

NOTE: These procedures configure RHVM to be able to authenticate users based on information in an external directory service. However, those users still need to be assigned roles to authorize them to use RHVM and work with resources in the Red Hat Virtualization environment.

Controlling user access with roles

PERMISSIONS AND ROLES

New users are typically created in a directory service configured in Red Hat Virtualization as an external domain, using that directory service’s native administration mechanisms. This was discussed in the preceding section of this chapter.

But these new users are not initially authorized to have any access to the Red Hat Virtualization environment. User accounts need to be granted permission to perform actions in the Red Hat Virtualization environment before they can be used. In this section, you learn how to manage user access using preconfigured settings called roles.

The Red Hat Virtualization authorization model is based around users, actions, and objects. Actions are tasks that can be performed, such as starting or stopping a virtual machine, creating a new template, or migrating a virtual machine to a different host.

Each type of action corresponds to a permission. Users have permissions that allow them to perform actions on objects. Objects are things like data centers, clusters, hosts, networks, or virtual machines.

To simplify maintenance, multiple permissions can be combined into a role. A role, in Red Hat Virtualization environment, is a set of privileges permitting access to physical and virtual resources at various levels. The system comes with multiple predefined roles such as SuperUser and PowerUserRole. These roles are meant to make it easier to provide a specific level of access to a user.

Users can be assigned roles which apply to the entire Red Hat Virtualization environment, or only to a specific object (such as a virtual machine or a datacenter). If a user is assigned a role on an object that contains other objects, then the user gets the same role on all objects in the container.

For example, if a user is assigned the HostAdmin role on a cluster, then the user gets the HostAdmin role on all hosts in that cluster.

NOTE: To perform certain actions, a user may need to have permissions (or roles) on multiple objects. Copying a template between storage domains, for example, requires the user to have relevant permissions on both storage domains.

The following graphic shows how permissions are inherited between objects.

The hierarchical layout of objects in Red Hat Virtualization

Role Types

Red Hat Virtualization comes with a variety of pre-configured roles.

Two types of roles exist in the Red Hat Virtualization environment:

  • Administrator role – This type of role allows access to the Administration Portal. Using these roles, users are able to manage physical and virtual resources.
  • User role – This type of role allows access to the User Portal and determines what a user can see and do in the User Portal

User Roles

There are three basic predefined user roles.

  • UserRole allows users to log in to the User Portal. It also allows the use of assigned virtual machines.
  • PowerUserRole allows users to create virtual machines and templates. For example, a user with this role in a data center can create virtual machines and templates in that data center. This is useful for offloading administrative tasks.
  • UserVmManager allows users to manage virtual machines and to create and use snapshots. If a user creates a virtual machine with the User Portal, that user automatically gets this role on that virtual machine.

The following table gives you details about the permissions that users gain when granted one of the basic user roles:

User Roles (Basic)

ROLE PRIVILEGES NOTES
UserRole Most basic role available. Gives the user access and use of virtual machines. User with this role assigned is able to log in to the User Portal. Can use the assigned virtual machines as well as check the state and view the details of them.
PowerUserRole Gives the user permission to manage and create virtual machines and templates. User with this role assigned at a data center level can create virtual machines and templates in that data center.
UserVmManager Gives the user administrator permission for a specific virtual machine. User with this role assigned can manage virtual machines and use snapshots. When creating a virtual machine in the User Portal, users are automatically assigned that role for the virtual machine.

For finer control, a number of advanced user roles have also been predefined:

User Roles (Advanced)

ROLE PRIVILEGES NOTES
UserTemplateBasedVm Gives the user limited privileges to using only Templates. User with this role assigned can create virtual machines based on templates.
DiskOperator Gives the user privileges to manage virtual disks. User with this role assigned can use, view, and edit virtual disks.
VmCreator Gives the user permission to create virtual machines using User Portal. Users with this role assigned can create virtual machines using User Portal.
TemplateCreator Gives the user privileges to create, edit, manage, and remove templates. User with this role assigned can create, remove, and edit templates.
DiskCreator Gives the user permission to create, edit, manage, and remove virtual disks. User with this role can create, remove, manage, and edit virtual disks within the assigned part of the environment.
TemplateOwner Gives the user privileges to edit and remove templates, as well as assign user permissions for templates. User with this role can edit and remove templates, as well as assign user permissions for templates. It is automatically assigned to the user who creates a template.
VnicProfileUser Gives the user permission to attach of detach network interfaces. User with this role can attach or detach network interfaces from logical networks.

Administrator Roles

There are also three basic administrator roles: SuperUser, ClusterAdmin, and DataCenterAdmin.

  • SuperUser gives the user full permissions across all objects and levels in your Red Hat Virtualization environment. The [email protected] user has this role.
  • Cluster Admin gives the user administrative permissions for all resources in a specific cluster.
  • DataCenter Admin gives the user administrative permissions across all objects in a specific data center, except for storage.

The following table gives you details about the permissions that users gain when granted one of the basic administrator roles:

Administrator Roles (Basic)

ROLE PRIVILEGES NOTES
SuperUser System Administrator of the whole environment. User with this role assigned has full permissions across all objects and levels.
ClusterAdmin Cluster Administrator. User with this role assigned at a cluster level has administrative permissions for a specific cluster and all of its resources.
DataCenterAdmin Data Center Administrator. User with this role assigned has administrative permissions for all objects in a specific data center except for storage.

There are also a number of advanced administrator roles to provide finer access control:

Administrator Roles (Advanced)

ROLE PRIVILEGES NOTES
TemplateAdmin Virtual machines template administrator. User with this role assigned can create, delete and configure the storage domains, and network details of templates.
StorageAdmin Storage administrator. User with this role assigned can create, delete, and manage assigned storage domains.
HostAdmin Host administrator. Can attach, remove, configure and manage a host.
NetworkAdmin Network administrator. User with this role assigned can create, remove, and edit the network of a particular data center or cluster.
GlusterAdmin Gluster storage administrator. User with this role can create, remove, and manage Gluster storage volumes.
VmImporterExporter Import or export administrator. User with this role can import and export virtual machines.

As you can see in the preceding tables, there are many existing roles to choose from. You should use these roles to better manage user access and to delegate administrative authority. In particular, instead of having everyone use the [email protected] account, you should assign SystemAdmin to specific users to ensure proper tracking of activity and compliance.

Assign less comprehensive roles to appropriate users in order to offload administrative tasks. DataCenterAdmin, ClusterAdmin, and PowerUserRole are particularly useful for this purpose

NOTE: The default roles cannot be changed or removed. It is possible to clone the default roles for customization, or to create entirely new roles.

Assigning Roles to Users

Before assigning permissions or roles to a user, you must make sure the user exists in an external domain or local domain. Normally, you would do that with the administrative tools used by your domain’s directory service. Once you have done that, you can use the Administration Portal to grant the user any desired permissions or roles.

Assigning System-wide Roles to Users

To assign a role to a user applicable to all objects in the Red Hat Virtualization environment:

1. Log in to the Administration Portal as a user that has been assigned the SuperUser role, for example as [email protected] user.

2. On the header bar, click Configure to open the Configure dialog window.

Accessing configure dialog window

3. Click the System Permissions label.

4. Click Add to open the Add System Permission to User dialog window.

Adding users

5. Under the Search field, select the appropriate profile to use and click the GO button to view a list of all users and groups.

6. Select the appropriate user by using the check box next to that user.

7. At the bottom of the dialog window, select the appropriate role to assign to that user by clicking the drop-down list under Role to Assign.

Adding permissions

8. Click the OK button to confirm.

9. To verify that the user has been granted the correct permissions, log in to the appropriate portal using that user’s credentials.

Assigning Resource-specific Roles to Users

Sometimes users should be assigned a role that only applies to a subset of resources in the Red Hat Virtualization environment. Depending on the role assigned, users are able to access and use the resources.

This is the procedure for assigning roles to users at the resource level:

1. Pick a resource in the resource tab by clicking on it, and select a resource in the results list.

Accessing Resources

2. For the selected resource, click on the Permissions tab to access the list of assigned users,users’s roles, and inherited permissions.

Adding Permissions RHV

3. Click Add to open the Add Permission to User dialog window.

4. Under Search field, select the appropriate profile to use and click the GO button to view a list of all users and groups.

5. Select the appropriate user by using the check box next to that user.

6. At the bottom of the dialog window, select the appropriate role to assign to that user by clicking the drop-down list under Role to Assign.

7. To confirm, click the OK button.

8. To verify that the user has been added with the correct permission, login to the appropriate portal with the user’s credentials, and access that resource.

Resetting the internal administration user’s password

The [email protected] account is created at installation time as a default user that has the system-wide SuperUser role. Like root on a Red Hat Enterprise Linux system, it can be useful as an emergency administration account if your external directory service is down.

From time to time, you may need to change or reset the password for this account. You can do this with the ovirt-aaa-jdbc-tool command. After the change is made, you do not have to restart anything in your RHV environment for the change to take effect.

To change the password for the internal admin user, follow this procedure:

1. Log in to the RHVM server.

2. To change the password, run the ovirt-aaa-jdbc-tool command. Using the user password-reset subcommand, specify the name of the user. Set a password expiry time with the –password-valid-to=2020-08-01 12:00:00Z” option. If you do not specify the expiry time, the password expiry will be set to the current time.

[[email protected] ~]# ovirt-aaa-jdbc-tool user password-reset admin 
> --password-valid-to="2025-08-01 12:00:00Z"
Password: new_password
Reenter password: new_password
updating user admin...
user updated successfully

User accounts in the internal local domain follow this password policy by default:
– Passwords must be six characters long.
– The last three passwords cannot be used again.

You can list or change the default policy by running ovirt-aaa-jdbc-tool with the settings subcommand. Detailed information on how to do so is beyond the scope of this course.

NOTE: If you attempt to log in to RHVM as the admin account too many times with the wrong password, the account may be locked. You can unlock the account as root on the RHVM server by running the command:

[[email protected] ~]# ovirt-aaa-jbdc-tool user unlock admin
updating user admin...
user updated successfully