diff options
Diffstat (limited to 'keystone-moon/doc/source/event_notifications.rst')
| -rw-r--r-- | keystone-moon/doc/source/event_notifications.rst | 439 |
1 files changed, 0 insertions, 439 deletions
diff --git a/keystone-moon/doc/source/event_notifications.rst b/keystone-moon/doc/source/event_notifications.rst deleted file mode 100644 index d9225c56..00000000 --- a/keystone-moon/doc/source/event_notifications.rst +++ /dev/null @@ -1,439 +0,0 @@ - -.. - 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.role_assignment.created", - "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). - -Opting out of certain notifications -=================================== - -There are many notifications that Keystone emits and some deployers may only -care about certain events. In Keystone there is a way to opt-out of certain -notifications. In ``/etc/keystone/keystone.conf`` you can set ``opt_out`` to -the event you wish to opt-out of. It is possible to opt-out of multiple events. - -Example: - -.. code-block:: ini - - [DEFAULT] - notification_opt_out = identity.user.created - notification_opt_out = identity.role_assignment.created - notification_opt_out = identity.authenticate.pending - -This will opt-out notifications for user creation, role assignment creation and -successful authentications. For a list of event types that can be used, refer -to: `Telemetry Measurements`_. - -.. _Telemetry Measurements: http://docs.openstack.org/admin-guide-cloud/telemetry-measurements.html#openstack-identity |