diff options
author | gordon chung <gord@live.ca> | 2014-10-22 16:05:48 -0400 |
---|---|---|
committer | gordon chung <gord@live.ca> | 2014-12-15 16:44:29 -0500 |
commit | bd07f84ed80b7345a18f2ef1d816047347b3e948 (patch) | |
tree | 5ce49075fdd3fa41d50d08784eb125c8106de2d4 /doc/source | |
parent | 791948cf07cca23b225915c32821dde3a10ce1e7 (diff) | |
download | keystonemiddleware-bd07f84ed80b7345a18f2ef1d816047347b3e948.tar.gz |
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
Diffstat (limited to 'doc/source')
-rw-r--r-- | doc/source/audit.rst | 81 | ||||
-rw-r--r-- | doc/source/images/audit.png | bin | 0 -> 48742 bytes | |||
-rw-r--r-- | doc/source/index.rst | 6 |
3 files changed, 85 insertions, 2 deletions
diff --git a/doc/source/audit.rst b/doc/source/audit.rst new file mode 100644 index 0000000..4d87905 --- /dev/null +++ b/doc/source/audit.rst @@ -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 diff --git a/doc/source/images/audit.png b/doc/source/images/audit.png Binary files differnew file mode 100644 index 0000000..5c2b130 --- /dev/null +++ b/doc/source/images/audit.png diff --git a/doc/source/index.rst b/doc/source/index.rst index 4bf6098..a7d2be8 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 ============ |