diff options
Diffstat (limited to 'keystone-moon/doc/source/event_notifications.rst')
| -rw-r--r-- | keystone-moon/doc/source/event_notifications.rst | 416 |
1 files changed, 416 insertions, 0 deletions
diff --git a/keystone-moon/doc/source/event_notifications.rst b/keystone-moon/doc/source/event_notifications.rst new file mode 100644 index 00000000..740986b1 --- /dev/null +++ b/keystone-moon/doc/source/event_notifications.rst @@ -0,0 +1,416 @@ + +.. + Copyright 2013 IBM Corp. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +============================ +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 notifications. + +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. + +Common Notification Structure +============================== + +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.<resource_type>.<operation>", + "message_id": "<message_id>", + "payload": {}, + "priority": "INFO", + "publisher_id": "identity.<hostname>", + "timestamp": "<timestamp>" + } + +Where ``<resource_type>`` is a Keystone resource, such as user or project, and +``<operation>`` 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. + +Basic Notifications +=================== + +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": <resource_id> + } + +Where ``<resource_id>`` is the unique identifier assigned to the +``resource_type`` that is undergoing the ``<operation>``. + +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: + +.. code-block:: javascript + + { + "event_type": "identity.user.created", + "message_id": "0156ee79-b35f-4cef-ac37-d4a85f231c69", + "payload": { + "resource_info": "671da331c47d4e29bb6ea1d270154ec3" + }, + "priority": "INFO", + "publisher_id": "identity.host1234", + "timestamp": "2013-08-29 19:03:45.960280" + } + +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 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. + +.. _PyCADF: http://docs.openstack.org/developer/pycadf +.. _CADF: http://www.dmtf.org/standards/cadf + +CADF notifications include additional context data around the ``resource``, +the ``action`` and the ``initiator``. + +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": "<initiator_id>" + }, + "target": { + "typeURI": "<target_uri>", + "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": "<action>", + "outcome": "success", + "id": "openstack:f5352d7b-bee6-4c22-8213-450e7b646e9f", + } + +Where the following are defined: + +* ``<initiator_id>``: ID of the user that performed the operation +* ``<target_uri>``: CADF specific target URI, (i.e.: data/security/project) +* ``<action>``: The action being performed, typically: + ``<operation>``. ``<resource_type>`` + +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.<resource_type>.<operation>` + +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 ``<action>`` and +``typeURI`` fields will be change. + +The difference to note is the inclusion of the ``resource_info`` field which +contains the ``<resource_id>`` 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 + + { + "event_type": "identity.authenticate", + "message_id": "1371a590-d5fd-448f-b3bb-a14dead6f4cb", + "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": "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 - 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 + + { + "event_type": "identity.created.role_assignment", + "message_id": "a5901371-d5fd-b3bb-448f-a14dead6f4cb", + "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": "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-08-20T01:20:47.932842+00:00", + "role": "0e6b990380154a2599ce6b6e91548a68", + "project": "24bdcff1aab8474895dbaac509793de1", + "inherited_to_projects": false, + "group": "c1e22dc67cbd469ea0e33bf428fe597a", + "action": "created.role_assignment", + "outcome": "success", + "id": "openstack:f5352d7b-bee6-4c22-8213-450e7b646e9f" + }, + "priority": "INFO", + "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). |