RSA SecurID Access Administration API

Document created by RSA Information Design and Development on Jul 20, 2018Last modified by Andrea Taylor on Jul 23, 2018
Version 5Show Document
  • View in full screen mode

The RSA SecurID Access Log Events API is a REST-based web services interface that allows audit log events to be retrieved from the Cloud Authentication Service. You can use this REST API to import the audit log events into your security information and event management (SIEM) solution, such as RSA NetWitness. Events are retrieved in chronological order in batches, and do not contain duplicates. They can be filtered by date range. Only Administration log events are currently available.

 

The endpoint, which can be either the SIEM or another client, uses the Administration API Key to call the Log Events API. The Super Admin generates this key and provides it to the Endpoint Administrator.

 

See the following instructions to generate an API Key, delete an API Key, regenerate an API Key, and write a client program using the Log Events API.

                           


Add an RSA SecurID Access Administration API Key

The Super Admin generates and downloads an Administration API Key file that contains:

  • Access ID, a unique identifier for the API Key.
  • Access Key, a private key that is needed for REST API clients to sign access tokens.

The Super Admin provides the API Key File to the Endpoint Administrator.

 

The following example displays the contents of an Administration API Key File.

{

"customerName":"mycompanyname",

"accessID":"139f6495-e447-4a26-a765-5c01b6b152d5",

"description":"Integration with RSA NetWitness",

"accessKey":"-----BEGIN RSA PRIVATE KEY-----\n<private key goes here>\n-----END RSA PRIVATE KEY-----\n",

"adminRestApiUrl":"https://access.securid.com/AdminInterface/restapi/"

}

 

Before you begin 

You must be a Super Admin for the Cloud Administration Console to perform this task.

 

Procedure 

  1. In the Cloud Administration Console, click Platform > API Key Management and select the Administration API Key tab.
  2. Click ADD. The new key is displayed.
  3. (Optional) Enter a description that identifies how the key will be used.
  4. Click Save and Download to download and save an API Key File.

 

Note:  The API Key is saved on your server only after you click Save and Download. If you click Regenerate, you cannot use the previous API Key file.

 

After you finish 

Use a secure method to deliver the API Key File to the Endpoint Administrator.

 

Note:  The API Key file contains sensitive data.

 

Delete an RSA SecurID Access API Key File

To delete an API Key File, follow the steps below.

 

Procedure

  1. In the Cloud Administration Console, click Platform > API Key Management and select the Administration API Key tab.
  2. Select next to the API Key File that you want to delete.
  3. When prompted, click Delete.

Regenerate an RSA SecurID Access API Key File

If an API Key File is lost or compromised, you can regenerate an API Key File.

 

Procedure

  1. In the Cloud Administration Console, click Platform > API Key Management and select the Administration API Key tab.
  2. Click Regenerate to generate and download an API Key File.

 

RSA SecurID Access Log Events REST API

The RSA SecurID Access Log Events API is a REST-based web services interface that allows audit log events to be retrieved from the Cloud Authentication Service. You can use this REST API to import the audit log events into your security information and event management (SIEM) solution, such as RSA NetWitness. Events are retrieved in chronological order in batches, and do not contain duplicates. They can be filtered by date range.

 

You can download the API Software Developer Kit (SDK) from: https://community.rsa.com/docs/DOC-94122.

 

The following example shows the method, request URL, body response, response body type, and response codes that are used by the Log Events REST API to retrieve audit log events from the Cloud Authentication Service and deliver them to your SIEM solution.

                        

MethodRequest URLResponse BodyResponse Body TypeResponse Codes
GET/AdminInterface/restapi/v1/adminlog/exportlogsMetadata plus array of Admin log eventsapplication/json200, 400, 403

 

Log Events REST API Parameters

The Log Events API allows the following optional parameters.

                                             

NameDescriptionTypeDefault ValueExample
startTimeAfterStart time of log events.ISO 8601 Date TimeCurrent time - 1 day2018-05-01T11:22:12.828-05:30
endTimeOnOrBeforeEnd time of log events.ISO 8601 Date TimeCurrent time2018-05-09T21:06:33.125-05:30
pageNumberZero-based index of the page to return.Integer05
pageSizeNumber of records to return in a page (or batch). Value between 1-100. Any value specified outside of this range will be treated as 100.Integer10050

 

The following example displays a REST API request with no parameters.

 

GET /AdminInterface/restapi/v1/adminlog/exportlogs

Accept: application/json

Authorization: bearer <JWT token>

 

The following example shows a REST API request with a specified start time.

 

GET /AdminInterface/restapi/v1/adminlog/exportlogs?startTimeAfter=2018-05-01T11:22:12.828-05:30

Accept: application/json

Authorization: bearer <JWT token>

 

The following table shows sample response metadata.

                            

ParameterDescriptionType
totalPages Total number of pages (or batches) of results.Integer
totalElementsTotal number of resultsInteger
pageSize Number of results returned in a page (or batch)Integer

 

The following example shows sample response metadata with 684 total results and a default page size of 100.

{

"totalPages": 7,

"totalElements": 684,

"pageSize": 100,

"elements": [

{

......

}

]

}

 

 

The following table shows API response data.

                                                                                                      

ParameterDescriptionType
eventIdIdentifies the event.String
eventLogDateDate and time of the log event, in UTC timezone. Example: 2018-05-13T16:29:59.000 UTCISO 8601 Date Time
eventTypeAlways set to Administration.String
serverURLThe Administration Server URL.
Example: https://access.securid.com/AdminInterface
String
serverIPAddressIP Address
applicationRSA SecurID Access.String
customerIdInternal company specifier.String
customerNameCompany name, as specified in Company Settings.String
sourceIPAddressIP address used by the Super Admin account that performed the operation.IP Address
adminUserNameUsername or email address used by the Super Admin who performed the operation.String
adminUserRoleRole of the administrator who performed the operation. Values are Super Administrator, Help Desk Administrator, and Support Administrator.String
activityKeyActivity key of the administration operation. See Administration Log Messages for the Cloud Authentication Service String
activityCodeUnique activity code of the administration operation. See Administration Log Messages for the Cloud Authentication Service Integer
resultResult of the administration operation. (SUCCESS or FAILURE)String
reasonKeyReason for failure.String
messageDescribes the administration operation.String
requiresPublishAdministration operation requires a publish. Values are true or false.Boolean

targetObject1Type

Identifies the target object of the administrative activity. Examples of administrative activity are ADD_POLICY and DELETE_POLICY. Publishing does not have a target object.String

 

Example REST API Response

{

"totalPages": 1,

"totalElements": 2,

"pageSize": 100,

"elements": [

{

"eventId": 767,

"eventLogDate": "2018-05-13T16:29:59.000 UTC",

"eventType": "Administration",

"serverURL": "https://access.securid.com/AdminInterface/",

"serverIPAddress": "191.237.22.167",

"application": "RSA SecurID Access",

"customerId": 3,

"customerName": "mycompanyname",

"sourceIPAddress": "1.2.3.4",

"adminUserName": "admin@mycompany.com",

"adminUserRole": "Super Administrator",

"activityKey": "SIGNIN_SUCCESS",

"activityCode": 80001,

"result": "SUCCESS",

"reasonKey": "",

"message": "admin@mycompany.com successfully signed in",

"requiresPublish": false

"targetObject1Id": null,

"targetObject1Name": null,

"targetObject1Type": null,

"targetObject2Id": null,

"targetObject2Name": null,

"targetObject2Type": null

},

{

"eventId": 768,

"eventLogDate": "2018-05-13T16:32:09.000 UTC",

"eventType": "Administration",

"serverURL": "https://access.securid.com/AdminInterface/",

"serverIPAddress": "191.237.22.167", ,

"application": "RSA SecurID Access",

"customerId": 3,

"customerName": "mycompanyname",

"sourceIPAddress": "1.2.3.4",

"adminUserName": "admin@mycompany.com",

"adminUserRole: "Super Administrator",

"activityKey": "ADD_ADMIN_API_KEY",

"activityCode": 80400,

"result": "SUCCESS",

"reasonKey": "",

"message": "admin@mycompany.com added an

Admin API Key 139f6495-e447-4a26-a765-5c01b6152d5",

"requiresPublish": false,

"targetObject1Id": 18,

"targetObject1Name": "139f6495-e447-4a26-a765-5c01b6b152d5",

"targetObject1Type": "ADMIN_API_KEY",

"targetObject2Id": null,

"targetObject2Name": null,

"targetObject2Type": null

}

]

}

 

Log Events REST API Authentication

REST API clients need to authenticate to the Cloud Authentication Service by constructing and using a JSON Web Token (JWT). Each request must contain a valid JWT that must be sent in an HTTP Authorization header.

 

Authorization: Bearer <JWT token>

 

The JSON Web Token (JWT) uses an API key that the Super Admin generates from the Cloud Administration Console. See Add an RSA SecurID Access Administration API KeyAdd an RSA SecurID Access Administration API Key for instructions on generating API keys.

 

The JWT consists of 3 parts: Header, Claims, and Signature.

 

JWT Header

The type must be set to JWT and the RS256 algorithm must be used to sign the token. Other values are not supported and result in an HTTP 403 Authorization error.

 

This is a sample JWT Header.

{

"typ": "JWT",

"alg": "RS256"

}

JWT Claims

The following table lists standard JWT claims that must be present for authentication. All other claims are ignored.

                           

ClaimValue
subAccess ID value of Administration API key that is generated from the Cloud Administration Console.
iatThe time when the JWT was created, specified in Unix Epoch time. Value must not be more than one hour in the past. The token must not be expired. A clock skew of plus or minus (+/-) 60 seconds is allowed.
expExpiration time, in Unix Epoch time. Expiration time must not be in the past, and must not be more than one hour into the future. A clock skew of plus or minus (+/-) 60 seconds is allowed.
audAudience of the claim. Value must be the Log Events Base REST API URL.

 

The following example shows a sample JWT Claims set.

{

"sub": "139f6495-e447-4a26-a765-5c01b6b152d5",

"iat" "1526273000",

"exp": "1526273493",

"aud": "https://access.securid.com/AdminInterface/restapi"

}

JWT Signature

A JWT Signature must be completed with the RS256 algorithm, using the API Access Key.

Token Expiration

Tokens must expire one hour (or less) after they are issued, otherwise the request is rejected.

 

 

 

You are here

Table of Contents > APIs and API Key Management > RSA SecurID Access Administration API

Attachments

    Outcomes