diff --git a/doc/source/event_notifications.rst b/doc/source/event_notifications.rst index 7204365cfd..740986b1d2 100644 --- a/doc/source/event_notifications.rst +++ b/doc/source/event_notifications.rst @@ -19,59 +19,86 @@ Keystone Event Notifications ============================ Keystone provides notifications about usage data so that 3rd party applications -can use the data for billing, monitoring, or quota purposes. This document -describes the current inclusions and exclusions for Keystone usage -notifications. +can use the data for billing, monitoring, or quota purposes. This document +describes the current inclusions and exclusions for Keystone notifications. -Notifications for Create/Update/Delete Events -============================================= +Keystone currently supports two notification formats: a Basic Notification, +and a Cloud Auditing Data Federation (`CADF`_) Notification. +The supported operations between the two types of notification formats are +documented below. -A notification is sent when a resource is successfully ``created``, -``updated``, or ``deleted``. The following resource types (where a -```` is always a singular noun) produce notifications. For -resource types that are immutable, like trusts, notifications are only sent -on creation and deletion of that resource. Resource types that should be -immutable from a Keystone perspective will not support update operations: +Common Notification Structure +============================== -- ``group`` -- ``project`` (i.e. "tenant") -- ``role`` -- ``user`` -- ``trust`` (immutable resource - no ``updated`` notification) -- ``region`` -- ``endpoint`` -- ``service`` -- ``policy`` - -The following message template is used to form a message when an operation on a -resource completes successfully: +Notifications generated by Keystone are generated in JSON format. An external +application can format them into ATOM format and publish them as a feed. +Currently, all notifications are immediate, meaning they are generated when a +specific event happens. Notifications all adhere to a specific top level +format: .. code-block:: javascript { - "event_type": "identity..", - "message_id": "", - "payload": { - "resource_info": "" - }, + "event_type": "identity..", + "message_id": "", + "payload": {}, "priority": "INFO", "publisher_id": "identity.", "timestamp": "" } -Notifications for create, update and delete events are all similar to each -other, where either ``created``, ``updated`` or ``deleted`` is inserted as the -```` in the above notification's ``event_type``. +Where ```` is a Keystone resource, such as user or project, and +```` is a Keystone operation, such as created, deleted. + +The key differences between the two notification formats (Basic and CADF), lie +within the ``payload`` portion of the notification. The ``priority`` of the notification being sent is not configurable through the Keystone configuration file. This value is defaulted to INFO for all notifications sent in Keystone's case. -If the operation fails, the notification won't be sent, and no special error -notification will be sent. Information about the error is handled through -normal exception paths. +Basic Notifications +=================== -Notification Example +All basic notifications contain a limited amount of information, specifically, +just the resource type, operation, and resource id. + +The ``payload`` portion of a Basic Notification is a single key-value pair. + +.. code-block:: javascript + + { + "resource_info": + } + +Where ```` is the unique identifier assigned to the +``resource_type`` that is undergoing the ````. + +Supported Events +---------------- + +The following table displays the compatibility between resource types and +operations. + +======================== ================================= +resource type supported operations +======================== ================================= +group create, update, delete +project create, update, delete +role create, update, delete +domain create, update, delete +user create, update, delete +trust create, delete +region create, update, delete +endpoint create, update, delete +service create, update, delete +policy create, update, delete +======================== ================================= + +Note, ``trusts`` are an immutable resource, they do not support ``update`` +operations. + +Example Notification -------------------- This is an example of a notification sent for a newly created user: @@ -89,37 +116,153 @@ This is an example of a notification sent for a newly created user: "timestamp": "2013-08-29 19:03:45.960280" } -Recommendations for consumers ------------------------------ - -One of the most important notifications that Keystone emits is for project -deletions (``event_type`` = ``identity.project.deleted``). This event should -indicate to the rest of OpenStack that all resources (such as virtual machines) -associated with the project should be deleted. - -Projects can also have update events (``event_type`` = -``identity.project.updated``), wherein the project has been disabled. Keystone -ensures this has an immediate impact on the accessibility of the project's -resources by revoking tokens with authorization on the project, but should -**not** have a direct impact on the projects resources (in other words, virtual -machines should **not** be deleted). +If the operation fails, the notification won't be sent, and no special error +notification will be sent. Information about the error is handled through +normal exception paths. Auditing with CADF ================== -Keystone has begun to add audit notification support for authentication and -for authorization events using the `DMTF Cloud Auditing Data Federation (CADF) -Open Standard. `_ +Keystone uses the `PyCADF`_ library to emit CADF notifications, these events +adhere to the DMTF `CADF`_ specification. This standard provides auditing +capabilities for compliance with security, operational, and business processes +and supports normalized and categorized event data for federation and +aggregation. -Note that the CADF format is used in place of the traditional notification -format mentioned above. +.. _PyCADF: http://docs.openstack.org/developer/pycadf +.. _CADF: http://www.dmtf.org/standards/cadf -This standard provides auditing capabilities for compliance with security, -operational, and business processes and supports normalized and categorized -event data for federation and aggregation. +CADF notifications include additional context data around the ``resource``, +the ``action`` and the ``initiator``. -The following CADF example illustrates a Keystone event record whereby the -user has failed to authenticate: +CADF notifications may be emitted by changing the ``notification_format`` to +``cadf`` in the configuration file. + +The ``payload`` portion of a CADF Notification is a CADF ``event``, which +is represented as a JSON dictionary. For example: + +.. code-block:: javascript + + { + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", + "initiator": { + "typeURI": "service/security/account/user", + "host": { + "agent": "curl/7.22.0(x86_64-pc-linux-gnu)", + "address": "127.0.0.1" + }, + "id": "" + }, + "target": { + "typeURI": "", + "id": "openstack:1c2fc591-facb-4479-a327-520dade1ea15" + }, + "observer": { + "typeURI": "service/security", + "id": "openstack:3d4a50a9-2b59-438b-bf19-c231f9c7625a" + }, + "eventType": "activity", + "eventTime": "2014-02-14T01:20:47.932842+00:00", + "action": "", + "outcome": "success", + "id": "openstack:f5352d7b-bee6-4c22-8213-450e7b646e9f", + } + +Where the following are defined: + +* ````: ID of the user that performed the operation +* ````: CADF specific target URI, (i.e.: data/security/project) +* ````: The action being performed, typically: + ````. ```` + +Additionally there may be extra keys present depending on the operation being +performed, these will be discussed below. + +Note, the ``eventType`` property of the CADF payload is different from the +``event_type`` property of a notifications. The former (``eventType``) is a +CADF keyword which designates the type of event that is being measured, this +can be: `activity`, `monitor` or `control`. Whereas the latter +(``event_type``) is described in previous sections as: +`identity..` + +Supported Events +---------------- + +The following table displays the compatibility between resource types and +operations. + +====================== ============================= ============================= +resource type supported operations typeURI +====================== ============================= ============================= +group create, update, delete data/security/group +project create, update, delete data/security/project +role create, update, delete data/security/role +domain create, update, delete data/security/domain +user create, update, delete data/security/account/user +trust create, delete data/security/trust +region create, update, delete data/security/region +endpoint create, update, delete data/security/endpoint +service create, update, delete data/security/service +policy create, update, delete data/security/policy +role assignment add, remove data/security/account/user +None authenticate data/security/account/user +====================== ============================= ============================= + +Example Notification - Project Create +------------------------------------- + +The following is an example of a notification that is sent when a project is +created. This example can be applied for any ``create``, ``update`` or +``delete`` event that is seen in the table above. The ```` and +``typeURI`` fields will be change. + +The difference to note is the inclusion of the ``resource_info`` field which +contains the ```` that is undergoing the operation. Thus creating +a common element between the CADF and Basic notification formats. + +.. code-block:: javascript + + { + "event_type": "identity.project.created", + "message_id": "0156ee79-b35f-4cef-ac37-d4a85f231c69", + "payload": { + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", + "initiator": { + "typeURI": "service/security/account/user", + "host": { + "agent": "curl/7.22.0(x86_64-pc-linux-gnu)", + "address": "127.0.0.1" + }, + "id": "c9f76d3c31e142af9291de2935bde98a" + }, + "target": { + "typeURI": "data/security/project", + "id": "openstack:1c2fc591-facb-4479-a327-520dade1ea15" + }, + "observer": { + "typeURI": "service/security", + "id": "openstack:3d4a50a9-2b59-438b-bf19-c231f9c7625a" + }, + "eventType": "activity", + "eventTime": "2014-02-14T01:20:47.932842+00:00", + "action": "created.project", + "outcome": "success", + "id": "openstack:f5352d7b-bee6-4c22-8213-450e7b646e9f", + "resource_info": "671da331c47d4e29bb6ea1d270154ec3" + } + "priority": "INFO", + "publisher_id": "identity.host1234", + "timestamp": "2013-08-29 19:03:45.960280" + } + +Example Notification - Authentication +------------------------------------- + +The following is an example of a notification that is sent when a user +authenticates with Keystone. + +Note that this notification will be emitted if a user successfully +authenticates, and when a user fails to authenticate. .. code-block:: javascript @@ -134,8 +277,7 @@ user has failed to authenticate: "agent": "curl/7.22.0(x86_64-pc-linux-gnu)", "address": "127.0.0.1" }, - "id": "openstack:5ee22124-6f41-4d23-a9f7-862c13a53a66", - "name": "joeuser" + "id": "c9f76d3c31e142af9291de2935bde98a" }, "target": { "typeURI": "service/security/account/user", @@ -148,7 +290,7 @@ user has failed to authenticate: "eventType": "activity", "eventTime": "2014-02-14T01:20:47.932842+00:00", "action": "authenticate", - "outcome": "failure", + "outcome": "success", "id": "openstack:f5352d7b-bee6-4c22-8213-450e7b646e9f" }, "priority": "INFO", @@ -156,8 +298,69 @@ user has failed to authenticate: "timestamp": "2014-02-14T01:20:47.932842" } -The following CADF example illustrates a Keystone event record whereby the -user has assigned a role to a group on a specific project: +Example Notification - Federated Authentication +----------------------------------------------- + +The following is an example of a notification that is sent when a user +authenticates with Keystone via Federation. + +This example is similar to the one seen above, however the ``initiator`` +portion of the ``payload`` contains a new ``credential`` section. + +.. code-block:: javascript + + { + "event_type": "identity.authenticate", + "message_id": "1371a590-d5fd-448f-b3bb-a14dead6f4cb", + "payload": { + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", + "initiator": { + "credential": { + "type": "http://docs.oasis-open.org/security/saml/v2.0", + "token": "671da331c47d4e29bb6ea1d270154ec3", + "identity_provider": "ACME", + "user": "c9f76d3c31e142af9291de2935bde98a", + "groups": [ + "developers" + ] + }, + "typeURI": "service/security/account/user", + "host": { + "agent": "curl/7.22.0(x86_64-pc-linux-gnu)", + "address": "127.0.0.1" + }, + "id": "c9f76d3c31e142af9291de2935bde98a" + }, + "target": { + "typeURI": "service/security/account/user", + "id": "openstack:1c2fc591-facb-4479-a327-520dade1ea15" + }, + "observer": { + "typeURI": "service/security", + "id": "openstack:3d4a50a9-2b59-438b-bf19-c231f9c7625a" + }, + "eventType": "activity", + "eventTime": "2014-02-14T01:20:47.932842+00:00", + "action": "authenticate", + "outcome": "success", + "id": "openstack:f5352d7b-bee6-4c22-8213-450e7b646e9f" + }, + "priority": "INFO", + "publisher_id": "identity.host1234", + "timestamp": "2014-02-14T01:20:47.932842" + } + +Example Notification - Role Assignment +-------------------------------------- + +The following is an example of a notification that is sent when a role is +granted or revoked to a project or domain, for a user or group. + +It is important to note that this type of notification has many new keys +that convey the necessary information. Expect the following in the ``payload``: +``role``, ``inherited_to_project``, ``project`` or ``domain``, ``user`` or +``group``. With the exception of ``inherited_to_project``, each will represent +the unique identifier of the resource type. .. code-block:: javascript @@ -172,8 +375,7 @@ user has assigned a role to a group on a specific project: "agent": "curl/7.22.0(x86_64-pc-linux-gnu)", "address": "127.0.0.1" }, - "id": "openstack:f6eac6ad-ef02-4469-a40f-c1c9151d3813", - "name": "7bdae1f0c3754e9f8af3794016b88093" + "id": "c9f76d3c31e142af9291de2935bde98a" }, "target": { "typeURI": "service/security/account/user", @@ -197,3 +399,18 @@ user has assigned a role to a group on a specific project: "publisher_id": "identity.host1234", "timestamp": "2014-08-20T01:20:47.932842" } + +Recommendations for consumers +============================= + +One of the most important notifications that Keystone emits is for project +deletions (``event_type`` = ``identity.project.deleted``). This event should +indicate to the rest of OpenStack that all resources (such as virtual machines) +associated with the project should be deleted. + +Projects can also have update events (``event_type`` = +``identity.project.updated``), wherein the project has been disabled. Keystone +ensures this has an immediate impact on the accessibility of the project's +resources by revoking tokens with authorization on the project, but should +**not** have a direct impact on the projects resources (in other words, virtual +machines should **not** be deleted).