documentation for audit middleware

this moves (and edits) audit middleware documentation from pycadf
library to keystonemiddleware

pycadf doc: https://github.com/openstack/pycadf/blob/master/doc/source/middleware.rst

Implements: blueprint audit-middleware
Change-Id: I068f312d8927010fd209eab5c22910c4d1d343a1
This commit is contained in:
gordon chung 2014-10-22 16:05:48 -04:00
parent 791948cf07
commit bd07f84ed8
4 changed files with 92 additions and 3 deletions

81
doc/source/audit.rst Normal file
View File

@ -0,0 +1,81 @@
..
Copyright 2014 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.
.. _middleware:
=================
Audit middleware
=================
The Keystone middleware library provides an optional WSGI middleware filter
which allows the ability to audit API requests for each component of OpenStack.
The audit middleware filter utilises environment variables to build the CADF
event.
.. figure:: ./images/audit.png
:width: 100%
:align: center
:alt: Figure 1: Audit middleware in Nova pipeline
The figure above shows the middleware in Nova's pipeline.
Enabling audit middleware
=========================
To enable auditing, oslo.messaging_ should be installed. If not, the middleware
will log the audit event instead. Auditing can be enabled for a specific
project by editing the project's api-paste.ini file to include the following
filter definition:
::
[filter:audit]
paste.filter_factory = keystonemiddleware.audit:AuditMiddleware.factory
audit_map_file = /etc/nova/api_audit_map.conf
The filter should be included after Keystone middleware's auth_token middleware
so it can utilise environment variables set by auth_token. Below is an example
using Nova's WSGI pipeline::
[composite:openstack_compute_api_v2]
use = call:nova.api.auth:pipeline_factory
noauth = faultwrap sizelimit noauth ratelimit osapi_compute_app_v2
keystone = faultwrap sizelimit authtoken keystonecontext ratelimit audit osapi_compute_app_v2
keystone_nolimit = faultwrap sizelimit authtoken keystonecontext audit osapi_compute_app_v2
.. _oslo.messaging: http://www.github.com/openstack/oslo.messaging
Configure audit middleware
==========================
To properly audit api requests, the audit middleware requires an
api_audit_map.conf to be defined. The project's corresponding
api_audit_map.conf file is included in the `pyCADF library`_.
The location of the mapping file should be specified explicitly by adding the
path to the 'audit_map_file' option of the filter definition::
[filter:audit]
paste.filter_factory = keystonemiddleware.audit:AuditMiddleware.factory
audit_map_file = /etc/nova/api_audit_map.conf
Additional options can be set::
[filter:audit]
paste.filter_factory = pycadf.middleware.audit:AuditMiddleware.factory
audit_map_file = /etc/nova/api_audit_map.conf
service_name = test # opt to set HTTP_X_SERVICE_NAME environ variable
ignore_req_list = GET,POST # opt to ignore specific requests
.. _pyCADF library: https://github.com/openstack/pycadf/tree/master/etc/pycadf

BIN
doc/source/images/audit.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 48 KiB

View File

@ -1,9 +1,10 @@
Python Middleware for OpenStack Identity API (Keystone)
=======================================================
This is the middleware provided for integrating with the OpenStack
This is the middleware provided for integrating with the OpenStack
Identity API and handling authorization enforcement based upon the
data within the OpenStack Identity tokens.
data within the OpenStack Identity tokens. Also included is middleware that
provides the ability to create audit events based on API requests.
Contents:
@ -11,6 +12,7 @@ Contents:
:maxdepth: 1
middlewarearchitecture
audit
Contributing
============

View File

@ -53,7 +53,13 @@ def _log_and_ignore_error(fn):
class AuditMiddleware(object):
"""Create an audit event based on request/response."""
"""Create an audit event based on request/response.
The audit middleware takes in various configuration options such as the
ability to skip audit of certain requests. The full list of options can
be discovered here:
http://docs.openstack.org/developer/keystonemiddleware/audit.html
"""
@staticmethod
def _get_aliases(proj):