Overview
Overview
The Cirrus Log API is a REST-based API that retrieves event logs that can be imported into an enterprise log management system, such as a Security Incident and Event Management (SIEM) tool. Event logs are stored for the last 90 days. To enable the Cirrus Identity Log API, you must purchase the Add-On service. Once the service is enabled, it is easy to get started.
Log API was designed to be a generic API targeted to teams who have the development capability to integrate with their SIEM provider. Cirrus does not provide any SIEM-specific documentation. If you have specific questions about connecting to the API or the LogAPI elements themselves to see if they match what you are looking for we can answer those, but we rely on you to know your SIEM and how that works.
The API Documentation for Log API provides the detailed information on the API endpoints and a mechanism for which to test them. This document is designed to help you get started. Supplementary information is available in the Appendix.
Please note the rate limiting recommendations in the API documentation. You may keep querying until the nextToken value in the response is the same as what you supplied in the request. At that point, we recommend a 5-minute wait before the next API call. This should allow you to catch up with log events if, for some reason, you were unable to poll the API endpoint for some time and knew the nextToken from where you left off.
Steps to Implement
Step 1 - Create a credential. Customers create their own Cirrus Identity Log API Add-On credentials to access the API endpoints.
Step 2 - Review API documentation and test your credentials. Supplementary information is available in the Appendix.
Step 3 (optional) - Connect to the API using your SIEM tool according to their documentation.
Additional Help
If you would like a guided implementation with one of our technical implementation leads, email us at support@cirrusidentity.com and we will assign someone to work with you. This option involves scheduling a call with the team and walking you through the process outlined in Step 2 and being available to answer any questions.
Appendix - Supplement to LogAPI Documentation
The following information is supplemental to the LogAPI Documentation and may be added there in the future.
Additional Information Regarding Query Parameters
The parameter settings allow you to filter the log results to show specific log event information instead of receiving all the log events for you.
Additional descriptions for the individual Query Types
- logType: allows you to filter the response to show ‘authentication’ (SAML) or ‘CAS’ Bridge log data
- logSubtype: ‘request’ and ‘success’ relate to ‘authentication’ (SAML) bridge authentications. ‘login’, ‘samlValidate’, ‘serviceValidate’, and ‘validate’ refer to the functions used for the authentication and validation processes for CAS services.
- tenant: this refers to different instances of a Cirrus product. If you had two Cirrus Proxies each would be its own tenant
- service: a list of Cirrus products that you may subscribe to and want to filter on
Additional descriptions for Response Codes
- 403: not authorized to access orgUrl
- 422: validation error - malformed request
- 500: server error on the Cirrus side
Additional information regarding the successful response, under Schemas > LogApiResponse > logEvents
- timeStampISO: time of the event
- sp: service provider generating the request:
- user: the user who is authenticating
- attributes: the attributes and values in the assertion
Can I go back to a point in time to collect data?
The initial starting point for requesting API data will be the nextToken you receive after making your first API GET orgLogs request. You will need to keep track of nextToken. From then on, you can use the nextToken identifiers to pull log data. You cannot pick a point in the past before you started using the API to poll log data. Cirrus retains 90 days of log data.