440 lines
17 KiB
ReStructuredText
440 lines
17 KiB
ReStructuredText
|
|
..
|
|
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/telemetry-measurements.html#openstack-identity
|