569 lines
20 KiB
ReStructuredText
569 lines
20 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.
|
|
|
|
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: https://docs.openstack.org/pycadf/latest
|
|
.. _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>``
|
|
|
|
.. 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>`
|
|
|
|
Additionally there may be extra keys present depending on the operation being
|
|
performed, these will be discussed below.
|
|
|
|
Reason
|
|
------
|
|
|
|
There is a specific ``reason`` object that will be present for the following
|
|
PCI-DSS related events:
|
|
|
|
.. list-table::
|
|
:widths: 45 10 45
|
|
:header-rows: 1
|
|
|
|
* - PCI-DSS Section
|
|
- reasonCode
|
|
- reasonType
|
|
* - 8.1.6 Limit repeated access attempts by locking out the user after more than X failed attempts.
|
|
- 401
|
|
- Maximum number of <number> login attempts exceeded.
|
|
* - 8.2.3 Passwords must meet the established criteria.
|
|
- 400
|
|
- Password does not meet expected requirements: <regex_description>
|
|
* - 8.2.4 Password must be changed every X days.
|
|
- 401
|
|
- Password for <user> expired and must be changed
|
|
* - 8.2.5 Do not let users reuse the last X passwords.
|
|
- 400
|
|
- Changed password cannot be identical to the last <number> passwords.
|
|
* - Other - Prevent passwords from being changed for a minimum of X days.
|
|
- 401
|
|
- Cannot change password before minimum age <number> days is met
|
|
|
|
The reason object will contain the following keys:
|
|
|
|
* ``reasonType``: Description of the PCI-DSS event
|
|
* ``reasonCode``: HTTP response code for the event
|
|
|
|
For more information, see
|
|
:ref:`security_compliance`
|
|
for configuring PCI-DSS in keystone.
|
|
|
|
Supported Events
|
|
----------------
|
|
|
|
The following table displays the compatibility between resource types and
|
|
operations.
|
|
|
|
.. list-table::
|
|
:widths: 6 8 8
|
|
:header-rows: 1
|
|
|
|
* - 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"
|
|
}
|
|
|
|
Example Notification - Expired Password
|
|
---------------------------------------
|
|
|
|
The following is an example of a notification that is sent when a user
|
|
attempts to authenticate but their password has expired.
|
|
|
|
In this example, the ``payload`` contains a ``reason`` portion which contains
|
|
both a ``reasonCode`` and ``reasonType``.
|
|
|
|
.. code-block:: javascript
|
|
|
|
{
|
|
"priority": "INFO",
|
|
"_unique_id": "222441bdc958423d8af6f28f9c558614",
|
|
"event_type": "identity.authenticate",
|
|
"timestamp": "2016-11-11 18:31:11.290821",
|
|
"publisher_id": "identity.host1234",
|
|
"payload": {
|
|
"typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
|
|
"initiator": {
|
|
"typeURI": "service/security/account/user",
|
|
"host": {
|
|
"address": "127.0.0.1"
|
|
},
|
|
"id": "73a19db6-e26b-5313-a6df-58d297fa652e"
|
|
},
|
|
"target": {
|
|
"typeURI": "service/security/account/user",
|
|
"id": "c23e6cb7-abe0-5e42-b7f7-4c4104ea77b0"
|
|
},
|
|
"observer": {
|
|
"typeURI": "service/security",
|
|
"id": "9bdddeda6a0b451e9e0439646e532afd"
|
|
},
|
|
"eventType": "activity",
|
|
"eventTime": "2016-11-11T18:31:11.156356+0000",
|
|
"reason": {
|
|
"reasonCode": 401,
|
|
"reasonType": "The password is expired and needs to be reset for user: ed1ab0b40f284fb48fea9e25d0d157fc"
|
|
},
|
|
"action": "authenticate",
|
|
"outcome": "failure",
|
|
"id": "78cd795f-5850-532f-9ab1-5adb04e30c0f"
|
|
},
|
|
"message_id": "9a97e9d0-fef1-4852-8e82-bb693358bc46"
|
|
}
|
|
|
|
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.
|
|
|
|
.. list-table::
|
|
:widths: 6 8
|
|
:header-rows: 1
|
|
|
|
* - 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.
|
|
|
|
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`_.
|
|
|
|
By default, messages for the following authentication events are suppressed
|
|
since they are too noisy: ``identity.authenticate.success``,
|
|
``identity.authenticate.pending`` and ``identity.authenticate.failed``.
|
|
|
|
.. _Telemetry Measurements: https://docs.openstack.org/ceilometer/latest/admin/telemetry-measurements.html#openstack-identity
|