====== Audit - Reading audit information ======
This article shows how to connect CzechIdM to automated security monitoring system (SIEM). This form of integration is necessary in many organizations. IdM, being the central point where identities and their roles are managed, is just another piece of the security monitoring mosaic.

<note tip>Starting CzechIdM 11.2.0, we discourage reading audit information using REST as is explained on this page.

Please, use specialized [[devel:documentation:audit:dev:audit_logging_for_siem_tools|audit logging functionality]].</note>

===== Important events to monitor =====
For the basics, we recommend to monitor following events:
  * Successful login.
  * Unsuccessful login.
  * New identity created.
  * Identity deleted.
  * Identity enabled.
  * Identity disabled.
  * Identity password changed.
  * Privilege/role assigned to identity.
  * Privilege/role revoked from identity.
  * Role request approved.
  * Role request rejected.
  * New role created.
  * Role modified.
  * Role deleted.

For each event, we recommend to monitor (at least):
  * Who performed the change / initiated the event.
  * Which object was changed.
  * When was the action performed.

===== Reading audits programmatically =====
In essence, everyone can read audit events using RESTapi. The user must be authenticated and authorized. In our examples, we will read audits using ''curl''.
When using automated tool, use some reasonable time period (say 15 minutes) between reading new audit events. You can specify the time range of audit events in the REST query.
CzechIdM provides its response in JSON format. In the examples below, the response is redacted (and commented) for clarity.

==== Successful login ====
<note important>This example explains some of the response fields and overall structure of the response. Those comments and fields may be ommitted or redacted in the rest of examples. Please read through this example carefully.</note>
**Request**
<code>
GET /idm/api/v1/audits/search/quick
?size=99999
&page=0
&sort=timestamp,desc
&face=BETWEEN
&from=2019-08-12T09%3A50%3A00.000Z
&till=2019-08-12T10%3A00%3A00.000Z
&type=eu.bcvsolutions.idm.core.model.entity.IdmPassword
&changedAttributesList=lastSuccessfulLogin
</code>

**Response**
<code>
"audits": [{
         // unique audit id
         "id": 3104,
         "entityId": "ff261f34-8133-4ae3-8244-30dd6371f0a3",
         // timestamp of the event
         "timestamp": 1565179463761,
         ... redacted ...
         // who performed the change
         "modifierId": "644f4790-607e-4933-b6bc-397d9da34544",
         "modifier": "admin",
         ... redacted ...
         // owner of the "password" object = the user who logged himself in
         "ownerId": "644f4790-607e-4933-b6bc-397d9da34544",
         "ownerCode": "admin",
         ... redacted ...
},{
         ... redacted ...
}]
</code>
==== Unsuccessful login ====
**Request**
<code>
GET /idm/api/v1/audits/search/quick
?size=99999
&page=0
&sort=timestamp,desc
&face=BETWEEN
&from=2019-08-12T09%3A50%3A00.000Z
&till=2019-08-12T10%3A00%3A00.000Z
&type=eu.bcvsolutions.idm.core.model.entity.IdmPassword
&changedAttributesList=unsuccessfulAttempts
</code>

**Response**
<code>
{
      "id" : 305,
      "timestamp" : 1565603696834,
      "modifier" : "[GUEST]",
      "ownerCode" : "admin",
      ... redacted ...
      "_embedded" : {
        ... redacted ...
        ,
        "ownerId" : {
          ... redacted ...
          // username of the unsuccessful logon
          "username" : "admin",
        }
      }
}
</code>
==== New identity created ====
**Request**
<code>
GET /idm/api/v1/audits/search/quick
?size=99999
&page=0
&sort=timestamp,desc
&face=BETWEEN
&from=2019-08-12T10%3A00%3A00.000Z
&till=2019-08-12T10%3A10%3A00.000Z
&type=eu.bcvsolutions.idm.core.model.entity.IdmIdentity
&modification=ADD
</code>

**Response**
<code>
{
      "id" : 316,
      "timestamp" : 1565604153572,
      // who created
      "modifierId" : "3eb704d3-c177-4ffa-b889-34926c8e05c2",
      "modifier" : "admin",
      // login of created identity
      "ownerId" : "a72d5188-8e1b-47dc-b6af-7e44d8ba92c9",
      "ownerCode" : "john_doe",
      ... redacted ...
}
</code>
==== Identity deleted ====
**Request**
<code>
GET /idm/api/v1/audits/search/quick
?size=99999
&page=0
&sort=timestamp,desc
&face=BETWEEN
&from=2019-08-12T10%3A30%3A00.000Z
&till=2019-08-12T10%3A40%3A00.000Z
&type=eu.bcvsolutions.idm.core.model.entity.IdmIdentity
&modification=DEL
</code>

**Response**
<code>
{
      "id" : 328,
      "timestamp" : 1565606265372,
      "modifier" : "admin",
      "ownerCode" : "john_doe",
      ... redacted ...
}
</code>
==== Identity enabled ====
**Request**
<code>
GET /idm/api/v1/audits/search/quick
?size=99999
&page=0
&sort=timestamp,desc
&type=eu.bcvsolutions.idm.core.model.entity.IdmIdentity
&changedAttributesList=disabled
&changedAttributesList=state
&withVersion=true
&modification=MOD
</code>

**Response**
<code>
{
      "id" : 330,
      "timestamp" : 1565606400341,
      "modifier" : "admin",
      "ownerCode" : "john_doe",
      ... redacted ...
      "entity" : {
        "lastName" : "Doe",
        "modifier" : "admin",
        "firstName" : "John",
        // current state of identity
        "disabled" : false,
        "state" : "VALID",
        "email" : "john.doe@czechidm.eu",
        "originalModifierId" : "3eb704d3-c177-4ffa-b889-34926c8e05c2",
        "username" : "john_doe"
      },
      "_embedded" : {
        "entityId" : {
          "modifier" : "admin",
          "username" : "john_doe",
          "firstName" : "John",
          "lastName" : "Doe",
          "email" : "john.doe@czechidm.eu",
          "phone" : null,
          "titleBefore" : null,
          "titleAfter" : null,
          "description" : null,
          // previous state
          "disabled" : true,
          "state" : "DISABLED_MANUALLY",
          ... redacted ...
        }
      }
}
</code>
==== Identity disabled ====
**Request**
<code>
GET /idm/api/v1/audits/search/quick
?size=99999
&page=0
&sort=timestamp,desc
&type=eu.bcvsolutions.idm.core.model.entity.IdmIdentity
&changedAttributesList=disabled
&changedAttributesList=state
&withVersion=true
&modification=MOD
</code>

**Response**
<code>
{
      "id" : 330,
      "timestamp" : 1565606400341,
      "modifier" : "admin",
      "ownerCode" : "john_doe",
      ... redacted ...
      "entity" : {
        "lastName" : "Doe",
        "modifier" : "admin",
        "firstName" : "John",
        // current state of identity
        "disabled" : true,
        "state" : "DISABLED_MANUALLY",
        "email" : "john.doe@czechidm.eu",
        "originalModifierId" : "3eb704d3-c177-4ffa-b889-34926c8e05c2",
        "username" : "john_doe"
      },
      "_embedded" : {
        "entityId" : {
          "modifier" : "admin",
          "username" : "john_doe",
          "firstName" : "John",
          "lastName" : "Doe",
          "email" : "john.doe@czechidm.eu",
          "phone" : null,
          "titleBefore" : null,
          "titleAfter" : null,
          "description" : null,
          // previous state
          "disabled" : false,
          "state" : "VALID",
          ... redacted ...
        }
      }
}
</code>
==== Identity password changed ====
**Request**
<code>
GET /idm/api/v1/password-histories/search/quick
?size=99999
&page=0
&sort=created,desc
&changedAttributesList=validFrom
&face=BETWEEN
&from=2019-08-12T12%3A00%3A00.000Z
&till=2019-08-12T12%3A20%3A00.000Z
</code>

**Response**
<code>
{
      "created" : "2019-08-12T12:09:41.260Z",
      "creator" : "john_doe",
      ... redacted ...
      "_embedded" : {
        "identity" : {
          "username" : "john_doe",
          "email" : "john.doe@czechidm.eu",
          ... redacted ...
        }
      }
}
</code>
==== Privilege/role assigned to identity ====
**Request**
<code>
GET /idm/api/v1/audits/search/quick
?size=99999
&page=0
&sort=timestamp,desc
&type=eu.bcvsolutions.idm.core.model.entity.IdmIdentityRole
&face=BETWEEN
&from=2019-08-09T09%3A10%3A00.000Z
&till=2019-08-09T09%3A12%3A00.000Z
&changedAttributesList=role
&changedAttributesList=%20indentityContract
&modification=ADD
</code>

**Response**
<code>
{
      "id" : 450,
      "timestamp" : 1565709288850,
      "modifier" : "admin",
      "ownerCode" : "john_doe",
      "subOwnerCode" : "manager",
      ... redacted ...
      "_embedded" : {
        "entityId" : {
          ... redacted ...
          "_embedded" : {
            "identityContract" : {
               ... redacted ...
            },
            "role" : {
              "created" : "2019-08-09T09:10:37.264Z",
              "creator" : "[SYSTEM]",
              // name of the role
              "code" : "manager",
              ... redacted ...
          },
          "_eav" : [ ]
        },
        // identity the role was assigned to
        "ownerId" : {
          "creator" : "admin",
          "username" : "john_doe",
          "firstName" : "John",
          "lastName" : "Doe",
          "email" : "john.doe@czechidm.eu",
          ... redacted ...
        }
      }
}
</code>
==== Privilege/role revoked from identity ====
**Request**
<code>
GET /idm/api/v1/audits/search/quick
?size=99999
&page=0
&sort=timestamp,desc
&face=BETWEEN
&from=2019-08-12T12%3A25%3A00.000Z
&till=2019-08-12T12%3A32%3A00.000Z
&type=eu.bcvsolutions.idm.core.model.entity.IdmIdentityRole
&modification=DEL
&changedAttributesList=role&changedAttributesList=identityContract
</code>

**Response**
<code>
{
      "id" : 402,
      "timestamp" : 1565612905714,
      "modifier" : "admin",
      "ownerCode" : "john",
      "subOwnerCode" : "manager",
      ... redacted ...
      "_embedded" : {
        "subOwnerId" : {
          "code" : "manager",
          "baseCode" : "manager",
          // name of the role
          "name" : "manager",
          "roleType" : "TECHNICAL",
          ... redacted ...
        },
        // user the role was removed from
        "ownerId" : {
          "firstName" : "John",
          "lastName" : "Doe",
          "email" : "john.doe@bcvsolutions.eu",
          ... redacted ...
        }
      }
    } ]
  }
</code>
==== Role request approved ====
**Request**
<code>
GET /idm/api/v1/audits/search/quick
?size=99999
&page=0
&sort=timestamp,desc
&type=eu.bcvsolutions.idm.core.model.entity.IdmIdentityRole
&modification=ADD
&changedAttributesList=role
&changedAttributesList=identityContract
&face=TODAY
&from=2019-08-13T22%3A00%3A00.000Z
&till=2019-08-14T21%3A59%3A59.999Z
</code>

**Response**
<code>
{
      "id" : 540,
      "timestamp" : 1565770422521,
      "modifier" : "admin",
      "ownerCode" : "jane",
      "subOwnerCode" : "test|development",
      ... redacted ...
      "_embedded" : {
        "entityId" : {
          ... redacted ...
          "_embedded" : {
            ... redacted ...
            "identityContract" : {
              "_embedded" : {
                "identity" : {
                  "username" : "jane",
                  "firstName" : "Jane",
                  "lastName" : "Doe",
                  "email" : "jane.doe@bcvsolutions.eu",
                  ... redacted ...
                }
              },
              "_eav" : [ ]
            },
            "role" : {
              "creator" : "admin",
              "code" : "test|development",
              "baseCode" : "test",
              "environment" : "development",
              "name" : "test",
              "roleType" : "TECHNICAL",
              ... redacted ...
            }
          },
          "_eav" : [ ]
    } ]
}
</code>
==== Role request rejected ====
**Request**
<code>
GET /idm/api/v1/audits/search/quick
?size=99999
&page=0
&sort=timestamp,desc
&type=eu.bcvsolutions.idm.core.model.entity.IdmConceptRoleRequest
&modification=MOD
&changedAttributesList=state
&face=BETWEEN
&from=2019-08-13T15%3A40%3A00.000Z
&till=2019-08-13T15%3A50%3A00.000Z
</code>

**Response**
<code>
{
      "id" : 522,
      "modifier" : "admin",
      ... redacted ...
      "_embedded" : {
        "entityId" : {
          "state" : "DISAPPROVED",
          ... redacted ...
          "_embedded" : {
              ... redacted ...
              ,
              "_embedded" : {
                "identity" : {
                  "username" : "jane",
                  "firstName" : "Jane",
                  "lastName" : "Doe",
                  "email" : "jane.doe@bcvsolutions.eu",
                  ... redacted ...
                }
              },
              "_eav" : [ ]
            },
            "role" : {
              "creator" : "admin",
              "code" : "test|development",
              "baseCode" : "test",
              "environment" : "development",
              "name" : "test",
              "roleType" : "TECHNICAL",
              ... redacted ...
            }
          },
          "_eav" : [ ]
        }
      }
    }
</code>
==== New role created ====
**Request**
<code>
GET /idm/api/v1/audits/search/quick
?size=99999
&page=0
&sort=timestamp,desc
&type=eu.bcvsolutions.idm.core.model.entity.IdmRole
&face=BETWEEN
&from=2019-08-12T11%3A00%3A00.000Z
&till=2019-08-12T11%3A10%3A00.000Z
&modification=ADD
</code>

**Response**
<code>
{
      "id" : 528,
      "timestamp" : 1565769780568,
      // who created the role
      "modifier" : "admin",
      // role name in the form of NAME|environment
      "ownerCode" : "CTO|production",
      ... redacted ...
      "_embedded" : {
        "entityId" : {
          "creator" : "admin",
          "code" : "CTO|production",
          // implementation name of the role
          "baseCode" : "CTO",
          // deployment environment the role is intended for
          "environment" : "production",
          // user friendly name of the role
          "name" : "CTO",
          "roleType" : "TECHNICAL",
          "priority" : 2,
          ... redacted ...
        }
      }
}
</code>
==== Role modified ====
**Request**
<code>
GET /idm/api/v1/audits/search/quick
?size=99999
&page=0
&sort=timestamp,desc
&type=eu.bcvsolutions.idm.core.model.entity.IdmRole
&face=BETWEEN
&from=2019-08-12T11%3A00%3A00.000Z
&till=2019-08-12T11%3A10%3A00.000Z
&modification=MOD
</code>

**Response**
<code>
{
      "id" : 341,
      "entityId" : "2bc71f8f-3ba2-44d7-af90-c1155c1a1e35",
      "changedAttributes" : "name,code,baseCode",
      "modifier" : "admin",
      "ownerId" : null,
      "ownerCode" : "manager|test",
      ... redacted ...
}
</code>
==== Role deleted ====
**Request**
<code>
GET /idm/api/v1/audits/search/quick
?size=99999
&page=0
&sort=timestamp,desc
&type=eu.bcvsolutions.idm.core.model.entity.IdmRole
&face=BETWEEN
&from=2019-08-12T11%3A10%3A00.000Z
&till=2019-08-12T11%3A20%3A00.000Z
&modification=DEL
</code>

**Response**
<code>
{
      "id" : 342,
      "timestamp" : 1565608213844,
      "modifier" : "admin",
      "ownerCode" : "manager|test",
      ... redacted ...
}
</code>