Cloud Administration Anomalous Users API
8 months ago

Cloud Administration Anomalous Users API

Use this REST API to retrieve a list of users who exhibit anomalous behavior. The API retrieves information for each user as described in Response Data. Events are retrieved according to severity, in descending order, and do not contain duplicates. You can filter events by date range. Up to 500 unique anomalous events can be retrieved at any given time.

For more information on identity confidence and anomalous user events, see Identity Confidence.

For information about managing access to this API, see Accessing the Cloud Administration APIs.

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

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 retrieve logs for anomalous user events.

MethodRequest URLResponse BodyResponse Body TypeResponse Codes
GET /AdminInterface/restapi/v1/riskdashboard/anomaloususereventsUser authenticator details with propertyapplication/json200, 400, 403, 429

Request Parameters

Both request parameters are optional.

Note:  The request query parameter values may contain reserve characters that need to be URL encoded. Otherwise, the server may send a 400 Bad Request error. For example, the ISO 8601 Date and Time format may contain the + character if the specific time zone has an offset from UTC, such as+05:30. The + character needs to be encoded as %2B.

NameDescriptionTypeDefault ValueExample
startTimeAfterTimestamp limit. ISO 8601 Date TimeCurrent time - 1 day2021-01-13T11:22:12.828-04:30
endTimeOnOrBefore Timestamp limit.ISO 8601 Date TimeCurrent time2021-01-14T11:22:12.828-04:30

The following table describes how these parameters are used.

Parameter ProvidedResult
Only startTimeAfter

endTimeOnOrBefore = startTimeAfter + 24 hours

Only endTimeOnOrBefore startTimeAfter = endTimeOnOrBefore - 24 hours
BothData is returned for the specified date range. The date range cannot exceed 30 days.
Neither

endTimeOnOrBefore = current Day:Time

startTimeAfter = endTimeOnOrBefore - 24 hours

Example Request with No Parameters

This example returns log data for the past 24 hours.

GET

/AdminInterface/restapi/v1/riskdashboard/anomaloususerevents

Accept: application/json

Authorization: Bearer <JWT token>

Example Request with Start Time Specified

This example returns log data for a specified start time.

GET /AdminInterface/restapi/v1/riskdashboard/anomaloususerevents?startTimeAfter=2021-01-13T11:22:12.828-04:30

Accept: application/json

Authorization: Bearer <JWT token>

Response Metadata

NameDescriptionType
status

The Cloud Access Service (CAS) sends the following status codes when processing input parameters:

  • Status 0 - Successful processing.

  • Status 1 - One of the following errors was found:

    • INVALID_START_TIME indicates the startTimeAfter is greater than the current day:time.

    • INVALID_END_TIME indicates the endTimeOnOrBefore is greater than the current day:time.

    • INVALID_DATETIME_RANGE indicates the startTimeAfter is greater than endTimeOnOrBefore.

    • EXCEEDED_PERMISSIBLE_DATE_RANGE indicates the endTimeOnOrBefore minus startTimeAfter is greater than 30 days.

int
listOfConfidenceEventsExportEntriesList of anomalous user events found during authentication. Boolean flag is TRUE if more than 500 anomalous user events are found. ConfidenceEventsExportDTO
startTimeAfterStart interval for retrieving events.String (format : yyyy-MM-dd HH:mm:SS)
endTimeBeforeEnd interval for retrieving events.String (format : yyyy-MM-dd HH:mm:SS)

Example Response Metadata

{

"status": 0,

"listOfConfidenceEventsExportEntries": {

"confidenceEventsExportEntries":

[

{

...

}

],

"maxEventsExceeded": false

},

"startTimeAfter": "2021-01-13 15:52:828",

"endTimeBefore": "2021-01-14 15:52:828"

}

Response Data

NameDescriptionType
user_emailUser email used for authentication.String
customer_name

Company name specified in My Account > Company Settings.

String
event_transaction_idIdentifies each user event log message.Long
confidenceThe user's overall identity confidence score, which is influenced by the user's separate scores for Device Confidence, Behavior Confidence, and Location Confidence.Double
threshold

Confidence scores higher than this threshold indicate high confidence, while lower scores indicate low confidence. The threshold calculation is based on information collected from all users within your company and adjusts over time as CAS learns about your users and as more users authenticate. The initial default threshold is 0.37. After at least 1,000 authentications have been reached, the threshold is updated daily.

Double
behavior_confidence Level of confidence based on attributes associated with the user's behavior. For example, this score is adjusted when the user successfully authenticates to access the same application within the same timeframe.Double
location_confidence Level of confidence based on attributes associated with the user's location. For example, this score is increased if the user successfully authenticates from the same location every day and decreased if the user successfully authenticates from different locations every day.Double
device_confidence Level of confidence based on attributes associated with the user's device. These attributes describe device characteristics and user behavior. The Device Confidence score starts at 0.0 if the user has not previously used the device and increases each time the user successfully authenticates from the same device.Double
event_at Date and time of user event log, in UTC timezone. Example: 2018-05-13T16:29:59.000 UTCISO 8601 Date Time
top_contributors

If a user's overall Confidence score indicates low confidence, the API reports up to four factors that most contributed to lowering the score. These factors are listed in order from most impactful to less impactful. Factors that contribute to raising a user's overall score are not listed.

List of Strings
severity The difference between the user’s Confidence score and the Confidence Threshold at the time of authentication. The larger the difference, the higher the degree of anomalous behavior. Double
maxEventsExceededThis flag is TRUE if more than 500 anomalous user events are found.Boolean

 

 

Don't see what you're looking for?