Cloud Administration Add/Remove High-Risk User API

Document created by RSA Information Design and Development Employee on Mar 22, 2019Last modified by RSA Information Design and Development Employee on Oct 20, 2020
Version 23Show Document
  • View in full screen mode

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 RSA NetWitness, has detected suspicious activity.

Note:  This API is available only for Premium Edition.

Authentication

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

Administrative Roles

This API must use an API key that is associated with the Super Administrator role. For more information, see Manage the Cloud Administration API Keys.

Software Developer Kit

You can download the API Software Developer Kit (SDK) from Cloud Administration REST API Download.

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

                        
MethodRequest URLResponse Content TypeResponse BodyResponse Codes
PUT /AdminInterface/restapi/v1/users/highriskapplication/json

List of user emails that failed to update, or none if all succeeded.

200, 207, 403, 500

Example Request Body

The following example displays a request.

PUT /AdminInterface/restapi/v1/users/highrisk

Accept: application/json

Authorization: Bearer <JWT token>

Request Body Parameters

The following table describes the request body parameters.

                           
Request ParameterRequiredDescriptionType
actionYesAdd or remove. Case insensitive.String
usersYes

List of users identified as described in User Identification. Case insensitive. Maximum number of users is 100.

Array

User 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 IdentifierDescription
Email addressThe user's unique email address.

Primary Username or UID

For Active Directory, use sAMAccountName. For LDAP directories, use UID.
Alternate UsernameLDAP 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 Body

The following example displays a request body.

{ "action": "add",

"users": [

"user.one@mycompany.com",

"user.two@mycompany.com",

"user.three@mycompany.com"

]

}

Response

The following table lists the response scenarios.

                                                
ScenarioResponse CodeResponse Body
Successfully updated all users in the request.200OK. 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.403Forbidden.
User not found in the identity source.404User not found.
Multiple users were found for the alternate username.409Multiple users were found for the user identifier
Unexpected error.500Internal server error.

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

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"

}

]

}

Property Response Descriptions

The following table describes properties used in the response.

                            
PropertyDescriptionData Type
user

User's email address.

String
statusCodeHTTP status code for failed operation 400 or 500. See Cloud Administration Add/Remove High-Risk User APIString
errorError message describing the failed operation.String

 

 

 

You are here
Table of Contents > Cloud Administration APIs > Cloud Administration Add/Remove High-Risk Users API

Attachments

    Outcomes