Audit Trail API v2 (REST API)
Prerequisite
The Audit Trail API catalog and addresses can only be accessed when:
you have subscribed the Audit Trail option with TrustBuilder
created a "Logs" enabled certificate API in the administration console
Overview
TrustBuilder MFA provides a Strong Authentication as a Service solution and an fully documented API to manage and browse the Audit trail.
Audit trail life-cycle mechanism
The Audit trail life-cycle is divided in 3 stages with distinctive time-frame, access time and storage mode.
A REST API available in a 3 stages life-cycle
Online
This stage is designed for browsing and troubleshooting recent accesses.
Mainly for Help-desk and Assistance operations
Duration : The last five weeks
Performance bases accesses for frequent exports
Direct access through the API
Archive
This stage is designed for forensic and Business Intelligence purpose
Mainly for Auditing purpose and analysis
Duration : The last 13 month maximum / stored by months
Paginated exports
Glacier
This step is a service (commercial) option and only designed for compliance with specific trades with a legal records obligation
Duration : Years,
Long term archive stored by years
Point to be noted: standard offers are restricted to a 1 Year limit
Time distribution mechanism (Sharding)
Every Audit trail is sharded by time period
API clients *must* specify the requested shard ID(s)
Be mindful of gaps: past shards are always complete but last shards can lack most recent entries
Be mindful of order: trails could be « unsorted » (hence the possibility of gaps)
How to access the TrustBuilder MFA Audit Trail REST API catalog
As stated in the prerequisite, you can only access Audit Trails API address with the “inWebo” option and "logs" enabled certificate.
Please see “Accessing the Audit trail” documentation to get access to our Audit trail API and documentation.
Audit Trail API Interactive Interface and documentation
Here you can access directly the API and the Interactive Interface with its documentation.
Classical Interface: https://kiwi.myinwebo.com/audit/apidocs/public/
Interactive interface: https://kiwi.myinwebo.com/audit/apidocs/public/ui/index.html
Sample of Request URL
https://api.myinwebo.com/audit/v2/customer/logs/archive?limit=50&months=202003&page=0
Sample of CURL command line
curl -X GET --header 'Accept: application/json' 'https://api.myinwebo.com/audit/v2/customer/logs/archive?limit=50&months=202003&page=0'
How to find out the periods (months or weeks) that can be viewed in the audit trail
Each available API endpoint is associated with another endpoint allowing to retrieve the available months
example:
For the / audit / v2 / client / logs / archive endpoint, you can consult the following address: / audit / v2 / client / logs / archive / month
which will return the list of available months (in .json format) at the date of your request.
"202008", "202007", "202006", "202005", "202004", ....
So you don't need to calculate these values before launching your API query.
Paging and "hasMore" value
All the results of the audit trail logs are paginated, so to know when the results exceed the value of the "limit" defined in your REST request, you must check the value "hasMore" in the result .json.
If in the result .json the value "hasMore" returns "false" it means that there is no next page and it is not necessary to continue.
If in the result .json the value "hasMore" returns "true", this means that the result of this request continues on the next page, you will have to re-launch the same request but increasing the value "page" by 1.
Initial "page" value: 0
max "limit" value: 100
Available REST API endpoints in the TrustBuilder MFA Audit trail catalog
The Audit Trail allows you to access to the following categories:
V2 Audit Online Service
This service allows you to access data available in the last 5 weeks of activity / sharded per weeks.
V2 Audit Service
This category allows you to find and browse the activity in the Audit section on a monthly basis.
Starting with the 12th previous month i.e. the current month but from the previous year and ending with the last month (full 12 months available).
V2 Audit Glacier service
This service allows you to get access to data from previous Year / as stated previously this is a specific commercial option
Most TrustBuilder MFA offers are restricted to a 1 Year limit
Legacy and specific audit trail categories
The Audit Trail allows you to access the the following categories
V1 Audit Service (Legacy)
This category is the legacy Audit trail access. Evolutions will be made in the V2 API.
Deletion service for V2 Audit service
This service allows you to delete all Audit Entry lines for a login, in compliance with RGPD standards ( this deletion operation in itself will appear in the logs)
V2 My Audit Service
This category allows users to access their own activity / limited to the login which request this operation
V2 Audit Statistics Service
This category allows users to access a set of data used for the construction of statistics
V2 Export Audit endpoints, for Online and Archive Service
This category allows users to generate specific and timely exports
Characteristic of the unique identifier (ID) used in the log lines
The field used for data exports (ID) is constructed with the date and has the format YYYYMMDDHHmm *******
To export the day of May 13, for example, you will need to specify the following limits:
2020041300000000000
2020041390000000000
An identifier is therefore constructed from the date + random part (this random information is included in the log line)
Audit Trail logs contents
For each API call you will have a dedicate line within the logs with different information depending of the ACTION performed.
Some examples:
Someone creates a new account by using the API loginCreate
It will generate the action CREATE_USER with some other information such as a Result: OK or KO
Someone deletes an account by using the API loginDelete:
It will generate the action DELETE_USER with some other information such as a Result: OK or KO
Someone escalates privileges of another account by using the API loginUpdate:
It will generate the action UPDATE_USER with some other information such as a Result: OK or KO and the new "role" of this user.
Certificate creation events by using the administration console:
It will generate the action CREATE_CERTIFICATE with some other information related to this event
Successful authenticate events: You can have multiple successful event depending of the token used to authenticate
Action CHECK_PUSH_RESULT with Result at OK
Action AUTHORIZE_AUTHENTICATION at OK
Action VALIDATE_OTP at OK
Failed authenticate events:
Action CHECK_PUSH_RESULT with Result at KO
Action AUTHORIZE_AUTHENTICATION with Result at KO
Action VALIDATE_OTP with Result at KO
Audit Trail codes and descriptions
Each ACTION will come with some information such as:
Code | Description |
ID | Unique ID |
correlationId | ID to call the next logs starting from this point |
date | date of the action |
customerId | Unique ID of the customer |
serviceId | Service ID |
sourceIp | IP address source |
targetAccount | Account targeted by the API action |
targetLogin | Login targeted by the API action |
action | Action performed |
status | Results of the action performed |
archiveData | Additional information for this log line in .json format |
archiveDataType | Information related to the action. The content of this field may change depending of the action performed |
troubleshootContext | Information to help troubleshoot in case of issue This field is removed in Archive Audit Trail |
component | Internal name of component used to perform this API request |
server | ID of the server who have handled the API request |
The list of APIs and information logged can evolve
Audit Trail Actions and API calls
You will find below the list of APis call and the ACTION that will be logged in Audit Trail:
Action | Operation | Name (TRAIL) | Category |
LOGIN_CREATE | CREATE_USER | loginCreate | Provisioning |
LOGIN_UPDATE | UPDATE_USER | loginUpdate | Provisioning |
LOGIN_DELETE | DELETE_USER | loginDelete | Provisioning |
LOGIN_SEND_BY_MAIL | SENDMAIL | loginSendByMail | Provisioning |
LOGIN_SEND_BY_SMS | SEND_SMS | loginSendBySms | Provisioning |
LOGIN_ACTIVATE_CODE | ACTIVATE_CODE | loginActivateCode | Provisioning |
LOGIN_GET_INFO_FROM_LINK | GET_CODE_FROM_LINK | loginGetInfoFromLink | Provisioning |
LOGIN_GET_CODE_FROM_LINK | GET_CODE_FROM_LINK | loginGetCodeFromLink | Provisioning |
LOGIN_RESET_PASSWORD_EXTENDED | GET_RESET_CODE | loginResetPwdExtended | Provisioning |
LOGIN_RESET_PASSWORD | GET_RESET_CODE | loginResetPwd | Provisioning |
LOGIN_RESET_PIN_ERROR_COUNTER | RESET_PIN_ERROR_COUNTER | loginResetPINErrorCounter | Provisioning |
LOGIN_RESTORE | RESTORE_USER | loginRestore | Provisioning |
LOGIN_ADD_DEVICE | GET_DEVICE_ACTIVATION_CODE | loginAddDevice | Provisioning |
LOGIN_DELETE_TOOL | DELETE_DEVICE | loginDeleteTool | Provisioning |
GROUP_ACCOUNT_CREATE | CREATE_MEMBERSHIP | groupAccountCreate | Provisioning |
GROUP_ACCOUNT_UPDATE | UPDATE_MEMBERSHIP | groupAccountUpdate | Provisioning |
GROUP_ACCOUNT_DELETE | DELETE_MEMBERSHIP | groupAccountDelete | Provisioning |
SERVICE_CREATE | CREATE_SERVICE | serviceCreate | Configuration |
SERVICE_UPDATE | UPDATE_SERVICE | serviceUpdate | Configuration |
SERVICE_FEATURESET_UPDATE | UPDATE_SERVICE_FEATURESET | serviceFeaturesetUpdate | Configuration |
SERVICE_CONFIGURATION_UPDATE | UPDATE_SERVICE_CONFIGURATION | serviceConfigurationUpdate | Configuration |
SERVICE_BLOCK | BLOCK_SERVICE | serviceBlock | Configuration |
CONNECTOR_ADD | CREATE_CONNECTOR | connectorAdd | Configuration |
CONNECTOR_UPDATE | UPDATE_CONNECTOR | connectorUpdate | Configuration |
CONNECTOR_DELETE | DELETE_CONNECTOR | connectorDelete | Configuration |
SERVICE_GROUP_CREATE | CREATE_GROUP | serviceGroupCreate | Configuration |
SERVICE_GROUP_UPDATE | UPDATE_GROUP | serviceGroupUpdate | Configuration |
SERVICE_GROUP_DELETE | DELETE_GROUP | serviceGroupDelete | Configuration |
SERVICE_FORM_CREATE | CREATE_SECURE_SITE | serviceFormCreate | Configuration |
SERVICE_FORM_UPDATE | UPDATE_SECURE_SITE | serviceFormUpdate | Configuration |
SERVICE_FORM_DELETE | DELETE_SECURE_SITE | serviceFormDelete | Configuration |
SERVICE_POLICY_CREATE | CREATE_POLICY | servicePolicyCreate | Configuration |
SERVICE_POLICY_UPDATE | UPDATE_POLICY | servicePolicyUpdate | Configuration |
SERVICE_POLICY_DELETE | DELETE_POLICY | servicePolicyDelete | Configuration |
SERVICE_ROLE_CREATE | CREATE_ROLE | serviceRoleCreate | Configuration |
SERVICE_ROLE_UPDATE | UPDATE_ROLE | serviceRoleUpdate | Configuration |
SERVICE_ROLE_DELETE | DELETE_ROLE | serviceRoleDelete | Configuration |
CERTIFICATE_CREATE | CREATE_CERTIFICATE | certificateCreate | Configuration |
CERTIFICATE_UPDATE | UPDATE_CERTIFICATE | certificateUpdate | Configuration |
CERTIFICATE_DELETE | DELETE_CERTIFICATE | certificateDelete | Configuration |
RADIUS_ADD | CREATE_RADIUS | radiusAdd | Configuration |
RADIUS_DELETE | DELETE_RADIUS | radiusDelete | Configuration |
AUTHENTICATE | VALIDATE_OTP | authenticate | Authentication |
AUTHENTICATE_WITH_IP | VALIDATE_OTP | authenticateWithIp | Authentication |
AUTHENTICATE_RADIUS | VALIDATE_OTP | authenticateRadius | Authentication |
AUTHENTICATE_EXTENDED | VALIDATE_OTP | authenticateExtended | Authentication |
PUSH_AUTHENTICATE | SEND_PUSH_REQUEST | pushAuthenticate | Authentication |
CHECK_PUSH_RESULT | CHECK_PUSH_RESULT | checkPushResult | Authentication |
SEAL_VERIFY | VALIDATE_SEAL | sealVerify | Authentication |
SEAL_DEFERRED_VERIFY | DEFERRED_VALIDATE_SEAL | sealDeferredVerify | Authentication |
OTP | GENERATE_OTP | otp_finalize | Devices |
ACTIVATE | ACTIVATE | activate_finalize | Devices |
RESET | RESET | reset_finalize | Devices |
PUSH_OTP | PUSH_VALIDATION | pushOtp_finalize | Devices |
PUSH_ACTIVATE | PUSH_ACTIVATION | pushActivateCa_finalize | Devices |
SEAL | GENERATE_SEAL | seal_finalize | Devices |
LOGINS_MIGRATE_PASSWORDS | MIGRATE_PASSWORDS | loginsMigratePasswords | Undefined provisioning |
USER_RETURNING_GET_CODE_FROM_LINK | GET_RETURNING_CODE_FROM_LINK | userReturningGetCodeFromLink | Undefined provisioning |
GROUP_FORM_CREATE | CREATE_GROUP_FORM | groupFormCreate | Undefined configuration |
GROUP_FORM_DELETE | DELETE_GROUP_FORM | groupFormDelete | Undefined configuration |
SERVICE_DELETE | DELETE_SERVICE | serviceDelete | Undefined configuration |
CUSTOMER_CREATE | CREATE_CUSTOMER | customerCreate | Undefined configuration |
CUSTOMER_UPDATE | UPDATE_CUSTOMER | customerUpdate | Undefined configuration |
CUSTOMER_DELETE | DELETE_CUSTOMER | customerDelete | Undefined configuration |
PUSH_SEAL | PUSH_SEAL | pushSeal | Undefined authentication |
LOGIN_MACCESS_DELETE | DELETE_USER_MACCESS | loginMaccessDelete | Undefined authentication |
ADD_SERVICE | ADD_SERVICE | addService_finalize | Undefined devices |
SYNCHRONIZE | SYNCHRONIZE | synchro_finalize | Undefined devices |
MS | MS | ms_finalize | Undefined devices |
ACTIVATE_TB | ACTIVATE_TB | activateTB_finalize | Undefined devices |
CHECK_PUSH | CHECK_PUSH | checkPush_finalize | Undefined devices |
PASSWORD | PASSWORD | password_finalize | Undefined devices |
PUSH_REGISTRATION | PUSH_REGISTRATION | pushRegistration_finalize | Undefined devices |
MESSAGES | MESSAGES | messages_finalize | Undefined devices |
NEW_SN | NEW_SN | newsn_finalize | Undefined devices |
GET_SN | GET_SN | getsn_finalize | Undefined devices |
SET_BIOKEY | SET_BIOKEY | setBiokey_finalize | Undefined devices |
STATUS | STATUS | status_finalize | Undefined devices |
PUSH_OTP_REQUEST | PUSH_OTP_REQUEST | pushOtpRequest_finalize | Undefined devices |
PUSH_OTP_GET_RESULT | PUSH_OTP_GET_RESULT | pushOtpGetResult_finalize | Undefined devices |
PUSH_ACTIVATION_REQUEST | PUSH_ACTIVATION_REQUEST | pushActivationRequest_finalize | Undefined devices |
PUSH_ACTIVATION_GET_CODE | PUSH_ACTIVATION_GET_CODE | pushActivationGetCode_finalize | Undefined devices |
FORGOT_PASSWORD | FORGOT_PASSWORD | forgotPassword_finalize | Undefined devices |
EMAIL_RECOVERY | EMAIL_RECOVERY | emailRecovery_finalize | Undefined devices |
CHECK_LOGIN | CHECK_LOGIN | checkLogin_finalize | Undefined devices |
UPGRADE | UPGRADE | upgrade_finalize | Undefined devices |
DISCONNECT | DISCONNECT | disconnect_finalize | Undefined devices |
EXPORT | EXPORT | export_finalize | Undefined devices |
SET_PASSWORD | SET_PASSWORD | setPassword_finalize | Undefined devices |
PRE_AUTH | PRE_AUTH | preauth_finalize | Undefined devices |
PUSH_REMOTE_OTP_GET_RESULT | PUSH_REMOTE_OTP_GET_RESULT | pushRemoteOtpGetResult_finalize | Undefined devices |
PUSH_REMOTE_OTP_RESULT | PUSH_REMOTE_OTP_RESULT | pushRemoteOtpRequest_finalize | Undefined devices |
The list of APIs and information logged can evolve
Potential key <-> value generated depending of the APIsI
Each API will generate an action with complementary information in the archiveData and troubleshootContext fields such as
Field | Comments |
id | Unique ID |
serviceId | Service ID |
login | login of the user |
date | date of the action |
method | When calling the TrustBuilder MFA API / Method used in the operation |
errcode | When calling the TrustBuilder MFA API / API Return Code / OK / NOK or Specific ErrorCode of a call |
tooltype | if indicated type of TrustBuilder MFA or Web Application used for a call (Authenticator...) |
toolversion | if indicated version of TrustBuilder MFA or Web Application used for a call |
toollibversion | Version of the TrustBuilder MFA library used by this Application |
toolplatform | Authentication plateform and mode used |
useripaddr | When available, User IP address indicated in the request |
role | Role information in the performed operation (Administration console) |
createdby | Role Id |
adminLogin | For Administration console operation / Administrator Login who performed this operation |
objectInfo | Information about the action (label certificate for example) |
apiVersion | Version of the TrustBuilder MFA API called in this operation |
deviceType | Type of Device used, Android, iPhone, |
deviceAlias | If indicated the Alias of the device used in the operation |
deviceName | if indicated Name of the end-device Mobile / Workstation |
deviceVersion | if indicated Version of the end-device Mobile / Workstation |
deviceLibVersion | if indicated Lib version used on the end-device Mobile / Workstation |
secondFactor | Second Factor used |
serviceName | Name of the service, displayed during user operations |
userAgent | if available "userAgent" information of Browser / Internet Application used |
withoutPinForced | Settings "Without PIN" Forced in Site parameters for chosen Secure site |
sealedData | sealedData information used in specific API call |
extraFields | if used in the operation "Extrafields" / option to add Extra Fields in the user profile |
lang | Language Attribute in User profile to display operation |
codeType | Type of code created for Activations |
rejectReason | When failing, indicated reason if directly available in error codes |
roleId | When Provisioning operation RoleID used for updating user roles |
roleName | When Provisioning operation name of the role used for updating user roles |
certId | TrustBuilder MFA Certificate ID used in API call (generated in the Administration console) |
The list of APIs and information logged can evolve