Product SiteDocumentation Site

Chapter 18. Users

Users are exposed in a top-level collection and are referenced with the rel="users" link. Individual user elements contain the following:

Element property icons

The icons used in the properties column of this table are described in Table 8.1, “Element property icons”
Element Type Description Properties
id GUID Globally unique identifier for this user
user_name string The user principal name (may be used as a more convenient identifier when adding a new user)
name string A free-text name for the user
description string A free-text description of the user
domain string The containing Active Directory domain
groups complex A list of Active Directory groups for this user
Example 18.1. An XML representation of a user resource
GET /rhevm-api/users HTTP/1.1
Accept: application/xml

<user id="225f15cd-e891-434d-8262-a66808fcb9b1"
  href="/rhevm-api/users/225f15cd-e891-434d-8262-a66808fcb9b1">
    <name>RHEV-M Admin</name>
    <actions/>
    <link rel="roles"
      href="/rhevm-api/users/225f15cd-e891-434d-8262-a66808fcb9b1/roles"/>
    <link rel="tags"
      href="/rhevm-api/users/225f15cd-e891-434d-8262-a66808fcb9b1/tags"/>
    <domain>domain.example.com</domain>
    <logged_in>false</logged_in>
    <user_name>rhevmadmin@domain.example.com</user_name>
    <groups>
        <group>Group Policy Creator Owners@domain.example.com/Users</group>
        <group>Domain Admins@domain.example.com/Users</group>
        <group>Enterprise Admins@domain.example.com/Users</group>
        <group>Schema Admins@domain.example.com/Users</group>
        <group>Administrators@domain.example.com/Builtin</group>
    </groups>
</user>

The users collection is POSTed to add an existing Active Directory user to the Red Hat Enterprise Virtualization Manager database. The client-provided new user representation must include an embedded roles list with at least one initial role to assign to the user. For example, the following request assigns two initial roles to the user joe@domain.example.com:
POST /rhevm-api/users HTTP/1.1
Content-Type: application/xml
Accept: application/xml

<user>
    <user_name>joe@domain.example.com</user_name>
    <roles>
        <role>
            <name>RHEVMPowerUser</name>
        </role>
        <role id="00000000-0000-0000-0001-000000000003"/>
    </roles>
</user>
The new user is identified either by Red Hat Enterprise Virtualization Manager user ID or via the Active Directory user principal name (UPN). The user ID format reported from the Active Directory domain might be different to the expected Red Hat Enterprise Virtualization Manager format, such as in LDIF. [7] , the ID has the opposite byte order and is base-64 encoded). Hence it is usually more convenient to refer to the new user by UPN.

Note

The user exists in the Active Directory domain before it is added to the Red Hat Enterprise Virtualization Manager database. An API user had the option to query this domain through the domains collection prior to creation of the user.
Roles are identified either by name or ID. The example above shows both approaches.
Further roles are attached or detached with POST or DELETE requests to the roles sub-collection of an individual user. The example below illustrates how the RHEVMVDIUser role may be added to the role assignments for a particular user.

Note

The embedded user roles list of the user element is only used for the initial creation. All interactions post-creation with the user's role assignments go through the roles sub-collection.
POST /rhevm-api/users/225f15cd-e891-434d-8262-a66808fcb9b1/roles HTTP/1.1
Content-Type: application/xml
Accept: application/xml

<role>
    <name>RHEVMVDIUser</name>
</role>

Note

Users are not updated with the PUT verb. The only changes allowed post-creation are in the user's role assignments.
Users may be removed from the Red Hat Enterprise Virtualization Manager database via DELETE on the top level users collection. The Active Directory domain will remain unchanged after such a deletion.


[7] The LDAP Data Interchange Format is described in RFC 2849.