User Requests
The XML Interface accepts requests to:
Create users (see UserCreateRequest)
Delete users (see UserDeleteRequest)
Change user password or password permissions (see UserModifyRequest)
List the custom attributes and group membership of a specific user (see UserInfoRequest)
List all users (see UserQueryRequest)
User and group administration is unavailable with global sessions. Furthermore, administration is very limited for users without User Administration Permission. Such users can only query information about themselves using the UserInfoRequest element; all other user-related requests will yield an Insufficient Permissions error.
UserCreateRequest
Create a new user.
The authenticated user must have administrator privileges to create new users.
<UserCreateRequest>
<ID>...</ID>
<User>...</User>
<Passwd>...</Passwd>
<ModifyUserInfo>...</ModifyUserInfo> # optional
<CustomAttributeList>
<CustomAttribute> #optional
<Name>...</Name>
<Value>...</Value>
</CustomAttribute>
</CustomAttributeList>
</UserCreateRequest>
The users created using this request are added to the Key Users group, which enables these users to perform basic key operations. However, while creating users from the CipherTrust Manager UI or REST interface, the users created are not added automatically to the Key Users group. This step needs to be done separately.
| Element | Description |
|---|---|
| ID | Contains the user-specified request ID. |
| User | Contains the username to create. The username cannot change. |
| Passwd | Contains the password for this user. |
| ModifyUserInfo | Indicates whether a user can change his or her own password. Possible values are true or false; the default is false. This element is optional. |
| CustomAttributeList | Specifies the list of custom attributes. This element can contain multiple CustomerAttribute elements. This element is optional. |
| CustomAttribute | Contains one Name and one Value element. This element is optional. |
UserCreateResponse
Server response to a UserCreateRequest.
<UserCreateResponse>
<ID>...</ID>
<Success>...</Success>
</UserCreateResponse>
| 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 user 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
In the example below, the client creates a new user.
<UserCreateRequest>
<ID>4</ID>
<User>new_user</User>
<Passwd>SecretPassword</Passwd>
<ModifyUserInfo>true</ModifyUserInfo>
</UserCreateRequest>
<UserCreateResponse>
<ID>4</ID>
<Success>true</Success>
</UserCreateResponse>
UserDeleteRequest
Delete an existing user.
The authenticated user must have administrator privileges to delete users.
<UserDeleteRequest>
<ID>...</ID>
<User>...</User>
</UserDeleteRequest>
| Element | Description |
|---|---|
| ID | Contains the user-specified request ID. |
| User | Contains the username to delete. |
UserDeleteResponse
Server response to a UserDeleteResponse.
<UserDeleteResponse>
<ID>...</ID>
<Success>...</Success>
</UserDeleteResponse>
| 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 user 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
Below, the client deletes a user from the server.
<UserDeleteRequest>
<ID>13</ID>
<User>new_user</User>
</UserDeleteRequest>
<UserDeleteResponse>
<ID>13</ID>
<Success>true</Success>
</UserDeleteResponse>
UserModifyRequest
Modify the password or the Change Password permission for a user.
Users with administrator privileges can change the password or the Change Password permission for any user.
Users without administrator privileges may only change their own password through this interface if they have the Change Password permission enabled. They may not modify the Change Password permission.
<UserModifyRequest>
<ID>...</ID>
<User>...</User>
<Passwd>...</Passwd> # optional
<ModifyUserInfo>true</ModifyUserInfo> # optional
<CustomAttributeList> # include to add or update
<CustomAttribute> # custom attributes, optional
<Name>...</Name>
<Value>...</Value>
</CustomAttribute>
...
</CustomAttributeList>
<DeleteCustomAttribute> # include to delete an existing
<Name>...</Name> # custom attribute
<Name>...</Name>
</DeleteCustomAttribute>
<DeleteAllCustomAttributes/> # include to delete all custom attributes
</UserModifyRequest>
| Element | Description |
|---|---|
| ID | Contains the user-specified request ID. |
| User | Contains the name of the user to modify. |
| Passwd | Contains the password if the password is to be changed. If the element is omitted, the existing password is unchanged. This element is optional. |
| ModifyUserInfo | Contains the new password permission, if the permission is to be changed. Setting the value to true enables the user to change their own password. Setting the value to false disables this ability. If the element is omitted, the existing permission is unchanged. This element is optional. |
| CustomAttributeList | Contains the custom attributes that will be added or updated. Child elements are CustomAttribute, Name, and Value. Values must be base64 encoded, and input is considered as text. If your original data contains non-printable characters, convert the original data to hex values, and then convert the hex values to base64. |
| CustomAttribute | Contains one Name and one Value element. This element is optional. |
| DeleteCustomAttribute | Deletes the custom attributes listed in the Name element. |
| DeleteAllCustomAttribute | Deletes all the user's custom attributes. |
UserModifyResponse
Server response to a UserModifyRequest.
<UserModifyResponse>
<ID>...</ID>
<Success>...</Success>
</UserModifyResponse>
| 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 modifications are implemented. 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. |
Modifying a User's Password
In the example below, the client modifies the password for a user.
<UserModifyRequest>
<ID>5</ID>
<User>new_user</User>
<Passwd>another_password</Passwd>
</UserModifyRequest>
<UserModifyResponse>
<ID>5</ID>
<Success>true</Success>
</UserModifyResponse>
UserInfoRequest
Retrieve information about a single user.
Any user can request information about themselves; only users with administrator permissions can request information about other users.
<UserInfoRequest>
<ID>...</ID>
<User>...</User>
</UserInfoRequest>
| Element | Description |
|---|---|
| ID | Contains the user-specified request ID. |
| User | Contains the subject of the query. |
By default, the system-defined groups are visible but can be masked 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.
UserInfoResponse
Server response to a UserInfoRequest.
<UserInfoResponse>
<ID>...</ID>
<Success>...</Success>
<User>...</User>
<ModifyUserInfo>...</ModifyUserInfo>
<CustomAttributeList>
<CustomAttribute>
<Name>...</Name>
<Value>...</Value>
</CustomAttribute>
</CustomAttributeList>
<GroupList>
<Group>...</Group>
...
</GroupList>
</UserInfoResponse>
| Element | Description |
|---|---|
| ID | Contains the user-specified request ID. |
| Success | Indicates whether the operation was successful. true indicates success. false indicates failure. When the operation is successful, the response element will contain the User, ModifyUserInfo, GroupList, and Group elements described below. When the operation fails, the element 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. |
| User | Contains the subject of the query. |
| ModifyUserInfo | Contains the value of the change password permission: true if this user can change their password; false otherwise. |
| CustomAttributeList | Contains the list of custom attributes. The actual values are base64 encoded. This element is not included if the user does not have any associated custom attributes. |
| GroupList | Contains a list of groups to which the user belongs. This element is not included if the user does not belong to any groups. |
| Group | Contains the name of the group. |
Requesting User Information
In the example below, the client requests information about a user.
<UserInfoRequest>
<ID>6</ID>
<User>new_user</User>
</UserInfoRequest>
<UserInfoResponse>
<ID>6</ID>
<Success>true</Success>
<User>new_user</User>
<ModifyUserInfo>true</ModifyUserInfo>
</UserInfoResponse>
UserQueryRequest
Get information about all the users defined in the server.
The authenticated user must have administrator privileges to use this request.
<UserQueryRequest>
<ID>...</ID>
</UserQueryRequest>
By default, the system-defined groups are visible but can be masked 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.
| Element | Description |
|---|---|
| ID | Contains the user-specified request ID. |
UserQueryResponse
Server response to a UserQueryRequest.
<ID>...</ID>
<Success>...</Success>
<UserList>
<UserData>
<User>...</User>
<ModifyUserInfo>...</ModifyUserInfo>
<CustomAttributeList>
<CustomAttribute>
<Name>...</Name>
<Value>...</Value>
</CustomAttribute>
</CustomAttributeList>
<ModifyUserInfo>...</ModifyUserInfo>
<GroupList>
<Group>...</Group>
...
</GroupList>
</UserData>
...
</UserList>
</UserQueryResponse>
| 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 response element will contain the elements described below. 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. |
| UserList | Contains a list of UserData elements for each user in the system. |
| UserData | Contains a set of User, ModifyUserInfo and, optionally, GroupList elements that describe a user. |
| User | Contains the username. |
| CustomAttributeList | Contains the list of custom attributes. The actual values are base64 encoded. This element is not included if the user does not have any associated custom attributes. |
| ModifyUserInfo | Contains the value of the change password permission: true if this user can change their password; false otherwise. |
| GroupList | Contains a list of groups to which the user belongs. This element is not included if the user does not belong to any groups. |
| Group | Contains the name of the group. |
Querying for all User Information
In the example below, the client requests information about all of the NAE users on a CipherTrust Manager Appliance.
<UserQueryRequest>
<ID>3</ID>
</UserQueryRequest>
<UserQueryResponse>
<ID>3</ID>
<Success>true</Success>
<UserDataList>
<UserData>
<User>NAE_User1</User>
<ModifyUserInfo>true</ModifyUserInfo>
<GroupList>
<Group>group1</Group>
</GroupList>
</UserData>
<UserData>
<User>NAE_User2</User>
<ModifyUserInfo>true</ModifyUserInfo>
</UserData>
<User>NAE_User3</User>
<ModifyUserInfo>true</ModifyUserInfo>
</UserData>
</UserDataList>
</UserQueryResponse>