User Group Requests
The XML Interface accepts requests to:
Create groups (See UserGroupCreateRequest)
Delete groups (See UserGroupDeleteRequest)
Add users to a group (See UserGroupAddUsersRequest)
Remove users from a group (See UserGroupRemoveUsersRequest)
List all users in a specific group (See UserGroupInfoRequest)
List all users in all groups (See UserGroupQueryRequest)
Caution
The server must be configured to use the local user directory. If the server uses an LDAP user directory, sending the requests described here will force the server to close the XML connection with an error.
To allow the full range of user group operations, log on to the XML interface with a user with User Administration Permission. You can enable and disable this permission on the User & Group Configuration page. For more information, see the Local Users and Groups chapter of the CipherTrust Manager Appliance User Guide.
User group administration is unavailable with global sessions and for users without User Administration Permission. Group-related requests will yield an Insufficient Permissions error.
UserGroupCreateRequest
Creates a new user group.
The authenticated user must have NAE administrator privileges to create new groups.
<UserGroupCreateRequest>
<ID>...</ID>
<Group>...</Group>
</UserGroupCreateRequest>
| Element | Description |
|---|---|
| ID | Contains the user-specified request ID. |
| Group | Contains the name of the group to create. |
UserGroupCreateResponse
Server response to UserGroupCreateRequest.
<UserGroupCreateResponse>
<ID>...</ID>
<Success>...</Success>
</UserGroupCreateResponse>
| Element | Description |
|---|---|
| ID | Contains the user-specified request ID. |
| Success | Indicates if the operation was successful. true indicates success. false indicates failure. When the operation is successful, the new group is created. When the operation fails, the response contains the FatalError and ErrorString elements to illustrate why the failure occurred and help you troubleshoot. For a list of possible error IDs and strings, see Error Messages. |
Creating a User Group
Request
<UserGroupCreateRequest>
<ID>7</ID>
<Group>new_group</Group>
</UserGroupCreateRequest>
Response
<UserGroupCreateResponse>
<ID>7</ID>
<Success>true</Success>
</UserGroupCreateResponse>
UserGroupDeleteRequest
Deletes an existing group.
The authenticated user must have NAE administrator privileges to delete groups.
<UserGroupDeleteRequest>
<ID>...</ID>
<Group>...</Group>
</UserGroupDeleteRequest>
| Element | Description |
|---|---|
| ID | Contains the user-specified request ID. |
| Group | Contains the name of the group to delete. |
UserGroupDeleteResponse
Server response to UserGroupDeleteRequest.
<UserGroupDeleteResponse>
<ID>...</ID>
<Success>...</Success>
</UserGroupDeleteResponse>
| Element | Description |
|---|---|
| ID | Contains the user-specified request ID. |
| Success | Indicates if the operation was successful. true indicates success. false indicates failure. When the operation is successful, the new group is deleted. When the operation fails, the response contains the FatalError and ErrorString elements to illustrate why the failure occurred and help you troubleshoot. For a list of possible error IDs and strings, see Error Messages. |
Deleting a User Group
Request
<UserGroupDeleteRequest>
<ID>12</ID>
<Group>new_group</Group>
</UserGroupDeleteRequest>
Response
<UserGroupDeleteResponse>
<ID>12</ID>
<Success>true</Success>
</UserGroupDeleteResponse>
UserGroupAddUsersRequest
Adds one or more users to a group.
The authenticated user must have administrator privileges to change any of the user lists of any groups.
<UserGroupAddUsersRequest>
<ID>...</ID>
<Group>...</Group>
<UserList>
<User>...</User>
<User>...</User>
...
</UserList>
</UserGroupAddUsersRequest>
| Element | Description |
|---|---|
| ID | Contains the user-specified request ID. |
| Group | Contains the name of the group to modify. |
| UserList | Contains the list of users to add. |
| User | Contains the username. The user must exist on the CipherTrust Manager. If any of the usernames do not exist, the entire request will fail. A user may belong to multiple groups. |
UserGroupAddUsersResponse
Server response to UserGroupAddUsersRequest.
<UserGroupAddUsersResponse>
<ID>...</ID>
<Success>...</Success>
</UserGroupAddUsersResponse>
| Element | Description |
|---|---|
| ID | Contains the user-specified request ID. |
| Success | Indicates if the operation was successful. true indicates success. false indicates failure. When the operation is successful, the user is added to the group. When the operation fails, the response contains the FatalError and ErrorString elements to illustrate why the failure occurred and help you troubleshoot. For a list of possible error IDs and strings, see Error Messages. |
Adding Users to a Group
Request
<UserGroupAddUsersRequest>
<ID>8</ID>
<Group>new_group</Group>
<UserList>
<User>new_user</User>
<User>another_user</User>
</UserList>
</UserGroupAddUsersRequest>
Response
<UserGroupAddUsersResponse>
<ID>8</ID>
<Success>true</Success>
</UserGroupAddUsersResponse>
UserGroupRemoveUsersRequest
Removes one or more users from group.
Removing a user from a group does not delete the user from the server or from any other groups. The authenticated user must have administrator privileges to change any of the user lists of any groups.
<UserGroupRemoveUsersRequest>
<ID>...</ID>
<Group>...</Group>
<UserList>
<User>...</User>
<User>...</User>
...
</UserList>
</UserGroupRemoveUsersRequest>
| Element | Description |
|---|---|
| ID | Contains the user-specified request ID. |
| Group | Contains the name of the group to modify. |
| UserList | Contains the list of users to remove. |
| User | Contains the username. |
UserGroupRemoveUsersResponse
Server response to UserGroupRemoveUsersRequest.
<UserGroupRemoveUsersResponse>
<ID>...</ID>
<Success>...</Success>
</UserGroupRemoveUsersResponse>
| Element | Description |
|---|---|
| ID | Contains the user-specified request ID. |
| Success | Indicates if the operation was successful. true indicates success. false indicates failure. When the operation is successful, the user is removed from the group. When the operation fails, the response contains the FatalError and ErrorString elements to illustrate why the failure occurred and help you troubleshoot. For a list of possible error IDs and strings, see Error Messages. |
Removing Users from a Group
Request
<UserGroupRemoveUsersRequest>
<ID>10</ID>
<Group>new_group</Group>
<UserList>
<User>new_user</User>
</UserList>
</UserGroupRemoveUsersRequest>
Response
<UserGroupRemoveUsersResponse>
<ID>10</ID>
<Success>true</Success>
</UserGroupRemoveUsersResponse>
UserGroupInfoRequest
Retrieves the list of users belonging to that group.
<UserGroupInfoRequest>
<ID>...</ID>
<Group>...</Group>
</UserGroupInfoRequest>
| Element | Description |
|---|---|
| ID | Contains the user-specified request ID. |
| Group | Contains the subject of the query. |
Note
By default, information on the system-defined groups is visible but can be masked, and the request can be made to fail if the mask_system_groups flag for the NAE interface is set to true. The flag can be changed using the ksctl utility. For details, refer to To create/modify the NAE interface to mask system groups from NAE requests.
Server response to UserGroupInfoRequest.
<UserGroupInfoResponse>
<ID>...</ID>
<Success>...</Success>
<Group>...</Group>
<UserList>
<User>...</User>
<User>...</User>
...
</UserList>
</UserGroupInfoResponse>
| Element | Description |
|---|---|
| ID | Contains the user-specified request ID. |
| Success | Indicates if the operation was successful. true indicates success. false indicates failure. When the operation is successful, the group information is returned. When the operation fails, the response contains the FatalError and ErrorString elements to illustrate why the failure occurred and help you troubleshoot. For a list of possible error IDs and strings, see Error Messages. |
| Group | Contains the subject of the query. |
| UserList | Contains the list of users that belong to this group. |
| User | Contains the username. |
Listing Group Members for a Group
Request
<UserGroupInfoRequest>
<ID>9</ID>
<Group>new_group</Group>
</UserGroupInfoRequest>
Response
<UserGroupInfoResponse>
<ID>9</ID>
<Success>true</Success>
<Group>new_group</Group>
<UserList>
<User>new_user</User>
<User>another_user</User>
</UserList>
</UserGroupInfoResponse>
UserGroupQueryRequest
Retrieves the complete list of all groups and their users.
<UserGroupQueryRequest>
<ID>...</ID>
</UserGroupQueryRequest>
| Element | Description |
|---|---|
| ID | Contains the user-specified request ID. |
Note
By default, the information of the system-defined groups is listed, but you can mask it by setting the mask_system_groups flag to true for the NAE interface. The flag can be changed using the ksctl utility. For details, refer to To create/modify the NAE interface to mask system groups from NAE requests.
UserGroupQueryResponse
Server response to UserGroupQueryRequest.
<UserGroupQueryResponse>
<ID>...</ID>
<Success>...</Success>
<GroupList>
<GroupData>
<Group>...</Group>
<UserList>
<User>...</User>
<User>...</User>
...
</UserList>
</GroupData>
...
</GroupList>
</UserGroupQueryResponse>
| Element | Description |
|---|---|
| ID | Contains the user-specified request ID. |
| Success | Indicates if the operation was successful. true indicates success. false indicates failure. When the operation is successful, the group information is returned. When the operation fails, the response contains the FatalError and ErrorString elements to illustrate why the failure occurred and help you troubleshoot. For a list of possible error IDs and strings, see Error Messages. |
| GroupList | Contains a list of GroupData elements for each group in the system. |
| GroupData | Contains the Group and UserList elements that describe the group. |
| Group | Contains the name of a group. |
| UserList | Contains the list of users that belong to this group. |
| User | Contains the username. |
Listing all Groups and Members
Request
<UserGroupQueryRequest>
<ID>11</ID>
</UserGroupQueryRequest>
Response
<UserGroupQueryResponse>
<ID>11</ID>
<Success>true</Success>
<GroupDataList>
<GroupData>
<Group>group1</Group>
<UserList>
<User>NAE_User1</User>
</UserList>
</GroupData>
<GroupData>
<Group>new_group</Group>
<UserList>
<User>another_user</User>
</UserList>
</GroupData>
</GroupDataList>
</UserGroupQueryResponse>
