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)
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 in 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
Create 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 a 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
<UserGroupCreateRequest>
<ID>7</ID>
<Group>new_group</Group>
</UserGroupCreateRequest>
<UserGroupCreateResponse>
<ID>7</ID>
<Success>true</Success>
</UserGroupCreateResponse>
UserGroupDeleteRequest
Delete 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 a 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
<UserGroupDeleteRequest>
<ID>12</ID>
<Group>new_group</Group>
</UserGroupDeleteRequest>
<UserGroupDeleteResponse>
<ID>12</ID>
<Success>true</Success>
</UserGroupDeleteResponse>
UserGroupAddUsersRequest
Add 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 a 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
<UserGroupAddUsersRequest>
<ID>8</ID>
<Group>new_group</Group>
<UserList>
<User>new_user</User>
<User>another_user</User>
</UserList>
</UserGroupAddUsersRequest>
<UserGroupAddUsersResponse>
<ID>8</ID>
<Success>true</Success>
</UserGroupAddUsersResponse>
UserGroupRemoveUsersRequest
Remove one or more users from a 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 a 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
<UserGroupRemoveUsersRequest>
<ID>10</ID>
<Group>new_group</Group>
<UserList>
<User>new_user</User>
</UserList>
</UserGroupRemoveUsersRequest>
<UserGroupRemoveUsersResponse>
<ID>10</ID>
<Success>true</Success>
</UserGroupRemoveUsersResponse>
UserGroupInfoRequest
Retrieve 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. |
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 a 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
<UserGroupInfoRequest>
<ID>9</ID>
<Group>new_group</Group>
</UserGroupInfoRequest>
<UserGroupInfoResponse>
<ID>9</ID>
<Success>true</Success>
<Group>new_group</Group>
<UserList>
<User>new_user</User>
<User>another_user</User>
</UserList>
</UserGroupInfoResponse>
UserGroupQueryRequest
Retrieve the complete list of all groups and their users.
<UserGroupQueryRequest>
<ID>...</ID>
</UserGroupQueryRequest>
| Element | Description |
|---|---|
| ID | Contains the user-specified request ID. |
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 a 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 Their Members
<UserGroupQueryRequest>
<ID>11</ID>
</UserGroupQueryRequest>
<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>