Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo

All

  • All
back

NAE-XML Interface Development

User Requests

search

Please Note:

User Requests

The XML Interface accepts requests to:

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

Creates 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>

Note

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.

ElementDescription
IDContains the user-specified request ID.
UserContains the username to create. The username cannot change.
PasswdContains the password for this user.
ModifyUserInfoIndicates whether a user can change his or her own password. Possible values are true or false; the default is false. This element is optional.
CustomAttributeListSpecifies the list of custom attributes. This element can contain multiple CustomerAttribute elements. This element is optional.
CustomAttributeContains one Name and one Value element. This element is optional.

UserCreateResponse

Server response to a UserCreateRequest.

<UserCreateResponse>
   <ID>...</ID>
   <Success>...</Success>
</UserCreateResponse>
ElementDescription
IDContains the user-specified request ID.
SuccessIndicates 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.

Request

<UserCreateRequest>
   <ID>4</ID>
   <User>new_user</User>
   <Passwd>SecretPassword</Passwd>
   <ModifyUserInfo>true</ModifyUserInfo>
</UserCreateRequest>

Response

<UserCreateResponse>
   <ID>4</ID>
   <Success>true</Success>
</UserCreateResponse>

UserDeleteRequest

Deletes an existing user.

The authenticated user must have administrator privileges to delete users.

<UserDeleteRequest>
   <ID>...</ID>
   <User>...</User>
</UserDeleteRequest>
ElementDescription
IDContains the user-specified request ID.
UserContains the username to delete.

UserDeleteResponse

Server response to UserDeleteResponse.

<UserDeleteResponse>
   <ID>...</ID>
   <Success>...</Success>
</UserDeleteResponse>
ElementDescription
IDContains the user-specified request ID.
SuccessIndicates 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.

Request

<UserDeleteRequest>
   <ID>13</ID>
   <User>new_user</User>
</UserDeleteRequest>

Response

<UserDeleteResponse>
   <ID>13</ID>
   <Success>true</Success>
</UserDeleteResponse>

UserModifyRequest

Modifies 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>
ElementDescription
IDContains the user-specified request ID.
UserContains the name of the user to modify.
PasswdContains the password if the password is to be changed. If the element is omitted, the existing password is unchanged. This element is optional.
ModifyUserInfoContains 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.
CustomAttributeListContains 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.
CustomAttributeContains one Name and one Value element. This element is optional.
DeleteCustomAttributeDeletes the custom attributes listed in the Name element.
DeleteAllCustomAttributeDeletes all the user's custom attributes.

UserModifyResponse

Server response to UserModifyRequest.

<UserModifyResponse>
   <ID>...</ID>
   <Success>...</Success>
</UserModifyResponse>
ElementDescription
IDContains the user-specified request ID.
SuccessIndicates 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.

Request

<UserModifyRequest>
   <ID>5</ID>
   <User>new_user</User>
   <Passwd>another_password</Passwd>
</UserModifyRequest>

Response

<UserModifyResponse>
   <ID>5</ID>
   <Success>true</Success>
</UserModifyResponse>

UserInfoRequest

Retrieves 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>
ElementDescription
IDContains the user-specified request ID.
UserContains the subject of the query.

Note

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 UserInfoRequest.

<UserInfoResponse>
    <ID>...</ID>
    <Success>...</Success>
    <User>...</User>
    <ModifyUserInfo>...</ModifyUserInfo>
    <CustomAttributeList>
        <CustomAttribute>
            <Name>...</Name>
            <Value>...</Value>
        </CustomAttribute>
    </CustomAttributeList>
   <GroupList>
        <Group>...</Group>
        ...
   </GroupList>
</UserInfoResponse>
ElementDescription
IDContains the user-specified request ID.
SuccessIndicates 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.
UserContains the subject of the query.
ModifyUserInfoContains the value of the change password permission: true if this user can change their password; false otherwise.
CustomAttributeListContains 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.
GroupListContains a list of groups to which the user belongs. This element is not included if the user does not belong to any groups.
GroupContains the name of the group.

Requesting User Information

In the example below, the client requests information about a user.

Request

<UserInfoRequest>
   <ID>6</ID>
   <User>new_user</User>
</UserInfoRequest>

Response

<UserInfoResponse>
   <ID>6</ID>
   <Success>true</Success>
   <User>new_user</User>
   <ModifyUserInfo>true</ModifyUserInfo>
</UserInfoResponse>

UserQueryRequest

Gets information about all the users defined in the server.

The authenticated user must have administrator privileges to use this request.

<UserQueryRequest>
   <ID>...</ID>
</UserQueryRequest>

Note

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.

ElementDescription
IDContains the user-specified request ID.

UserQueryResponse

Server response to UserQueryRequest.

<UserQueryResponse>
   <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>
ElementDescription
IDContains the user-specified request ID.
SuccessIndicates 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.
UserListContains a list of UserData elements for each user in the system.
UserDataContains a set of User, ModifyUserInfo and, optionally, GroupList elements that describe a user.
UserContains the username.
CustomAttributeListContains 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.
ModifyUserInfoContains the value of the change password permission: true if this user can change their password; false otherwise.
GroupListContains a list of groups to which the user belongs. This element is not included if the user does not belong to any groups.
GroupContains 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.

Request

<UserQueryRequest>
   <ID>3</ID>
</UserQueryRequest>

Response

<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>

On this page