Cloud Administration Add/Remove High-Risk User APICloud Administration Add/Remove High-Risk User API
Use the Cloud Administration Add/Remove High-Risk User List API to add or remove one or more users from a high-risk user list. You can determine authentication and access requirements for users who are identified as high risk. These might be users whose accounts have been compromised, or for whom a third-party security information and event management (SIEM) solution, such as NetWitness, has detected suspicious activity.
Note: This API is available only for Cloud Premier.
AuthenticationAuthentication
Clients calling this API must authenticate themselves by including a JSON Web Token in a request. For instructions on using this token, see Authentication for the Cloud Administration REST APIs.
Administrative RolesAdministrative Roles
This API must use an API key that is associated with the Super Administrator role. For more information, see Manage the Cloud Administration REST API Keys.
Software Developer KitSoftware Developer Kit
You can download the API Software Developer Kit (SDK) from Cloud Administration REST API Download.
Request RequirementsRequest Requirements
Use the following information to add or remove one or more users from the high-risk user list.
Note: The high-risk user list supports user emails. The sAMAccountName attribute is not supported.
| Method | Request URL | Response Content Type | Response Body | Response Codes |
|---|---|---|---|---|
| PUT |
/AdminInterface/restapi/v1/users/highrisk |
application/json |
List of user emails that failed to update, or none if all succeeded. |
200, 207, 403, 500 |
Example Request BodyExample Request Body
The following example displays a request.
PUT /AdminInterface/restapi/v1/users/highrisk
Accept: application/json
Authorization: Bearer <JWT token>
Request Body ParametersRequest Body Parameters
The following table describes the request body parameters.
| Request Parameter | Required | Description | Type |
|---|---|---|---|
| action | Yes | Add or remove. Case insensitive. | String |
| users | Yes |
List of users identified as described in User Identification. Case insensitive. Maximum number of users is 100. |
Array |
User IdentificationUser Identification
The request can identify users as described in the following table. Make sure the appropriate identity source attributes are configured as described in Add an Identity Source for the Cloud Authentication Service and Directory Server Attributes Synchronized for Authentication.
| User Identifier | Description |
|---|---|
| Email address | The user's unique email address. |
|
Primary Username or UID |
For Active Directory, use sAMAccountName. For LDAP directories, use UID. |
| Alternate Username | LDAP attribute containing the user's alternate username. For example, this can be used to represent the UserPrincipalName in Azure Active Directory. |
When the Cloud Authentication Service receives a list of users, it first searches for users' email addresses. If it cannot find a user's email address, it searches for the user's Primary Username or UID, and finally for the Alternate Username. Searching by Primary Username or Alternate Username can result in multiple conflicting matches. When searching by Primary Username, the Cloud Authentication Service selects the user with the latest creation entry. When searching by Alternate Username, no user is selected and the API responds with an HTTP failed status code.
Example Request BodyExample Request Body
The following example displays a request body.
{ "action": "add",
"users": [
"user.one@mycompany.com",
"user.two@mycompany.com",
"user.three@mycompany.com"
]
}
ResponseResponse
The following table lists the response scenarios.
| Scenario | Response Code | Response Body |
|---|---|---|
| Successfully updated all users in the request. | 200 | OK. No body is returned. |
| Partially successful in updating users in the request. | 207 |
Multi-status list of user emails that did not update from the request. See Cloud Administration Add/Remove High-Risk User API. |
| Invalid request body parameters. | 400 |
Bad request caused by one of the following: Invalid property. Invalid or missing action code. Empty list of emails. Number of emails exceeds maximum allowed value of 100. |
| Not authorized to perform the request. | 403 | Forbidden. |
| User not found in the identity source. | 404 | User not found. |
| Multiple users were found for the alternate username. | 409 | Multiple users were found for the user identifier |
| Unexpected error. | 500 | Internal server error. |
Multi-Status Objects ResponseMulti-Status Objects Response
When a partial success occurs, each failed user is listed in the response, along with the status code.
Example Partial Success Response Body Example Partial Success Response Body
The following example displays a partial success response body.
{
"users": [
{
"id": "user.one@company.com",
"statusCode": 404,
"error": "User not found"
},
{
"id": "user.two@company.com",
"statusCode": 409,
"error": "Multiple users were found for the user identifier"
}
]
}
Response Property DescriptionsResponse Property Descriptions
The following table describes properties used in the response.
| Property | Description | Data Type |
|---|---|---|
| user |
User's email address. |
String |
| statusCode | HTTP status code for failed operation 400 or 500. See Response Codes. | String |
| error | Error message describing the failed operation. | String |
