{"id":7341,"library":"keystonemiddleware","title":"Keystone Middleware","description":"Keystonemiddleware provides WSGI middleware components for OpenStack Identity (Keystone) integration. It enables services to authenticate requests against Keystone, handle tokens, and authorize access based on user roles and projects. The current stable version is 12.0.0, and it follows the OpenStack release cycle, typically releasing new versions with each OpenStack cycle, leading to several major releases per year.","status":"active","version":"12.0.0","language":"en","source_language":"en","source_url":"https://github.com/openstack/keystonemiddleware","tags":["OpenStack","Middleware","Authentication","WSGI","Keystone"],"install":[{"cmd":"pip install keystonemiddleware","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core library for interacting with Keystone for authentication.","package":"keystoneauth1","optional":false},{"reason":"Common dependency for OpenStack projects, used for configuration management.","package":"oslo.config","optional":false}],"imports":[{"note":"The primary middleware for authenticating requests with Keystone tokens.","symbol":"AuthToken","correct":"from keystonemiddleware.auth_token import AuthToken"},{"note":"Middleware for generating audit events.","symbol":"AuditMiddleware","correct":"from keystonemiddleware.audit import AuditMiddleware"},{"note":"Middleware for handling Cross-Origin Resource Sharing (CORS) requests.","symbol":"CORS","correct":"from keystonemiddleware.cors import CORS"}],"quickstart":{"code":"import os\nfrom wsgiref.simple_server import make_server\nfrom keystonemiddleware.auth_token import AuthToken\n\ndef simple_app(environ, start_response):\n    \"\"\"Simplest possible WSGI application\"\"\"\n    status = '200 OK'\n    headers = [('Content-type', 'text/plain; charset=utf-8')]\n    start_response(status, headers)\n    # AuthToken populates these if a valid token is provided\n    user_id = environ.get('HTTP_X_USER_ID', 'Unknown User ID')\n    project_id = environ.get('HTTP_X_PROJECT_ID', 'Unknown Project ID')\n    return [f\"Hello, user '{user_id}' from project '{project_id}' via keystonemiddleware!\\n\".encode('utf-8')]\n\n# Configuration for AuthToken (simplified, typically from paste.ini or configuration files)\n# IMPORTANT: Replace with your actual Keystone endpoint and user/project details.\n# For production, avoid 'insecure=True' and set 'memcached_servers'.\nauth_config = {\n    'auth_url': os.environ.get('OS_AUTH_URL', 'http://localhost:5000/v3'),\n    'username': os.environ.get('OS_USERNAME', 'admin'),\n    'password': os.environ.get('OS_PASSWORD', 'secret'),\n    'project_name': os.environ.get('OS_PROJECT_NAME', 'admin'),\n    'user_domain_name': os.environ.get('OS_USER_DOMAIN_NAME', 'Default'),\n    'project_domain_name': os.environ.get('OS_PROJECT_DOMAIN_NAME', 'Default'),\n    'memcached_servers': os.environ.get('MEMCACHED_SERVERS', '127.0.0.1:11211'), # Required for caching\n    'insecure': 'True' if os.environ.get('OS_INSECURE') else 'False', # Use only for testing/development\n    'delay_auth_decision': 'True' # Allows app to handle unauthenticated requests if needed\n}\n\n# Wrap the application with AuthToken middleware\napplication = AuthToken(simple_app, auth_config)\n\nif __name__ == '__main__':\n    httpd = make_server('', 8000, application)\n    print(\"Serving on port 8000...\")\n    print(\"Access with a valid X-Auth-Token header to see user info:\")\n    print(\"  curl -H \\\"X-Auth-Token: <your-keystone-token>\\\" http://localhost:8000/\")\n    print(\"Or with no token (if 'delay_auth_decision' is True):\")\n    print(\"  curl http://localhost:8000/\")\n    print(\"Ensure memcached is running if configured, e.g., 'sudo apt install memcached' and 'systemctl start memcached'.\")\n    print(\"Configure environment variables like OS_AUTH_URL, OS_USERNAME, OS_PASSWORD, etc. for actual Keystone integration.\")\n    httpd.serve_forever()","lang":"python","description":"This quickstart demonstrates how to wrap a simple WSGI application with the `AuthToken` middleware. It uses environment variables for configuration to make it runnable without hardcoding credentials. For `AuthToken` to function, a running Keystone instance and optionally Memcached (for token caching) are required. The example shows how to access user and project IDs populated by the middleware from the WSGI `environ`."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or newer. If you cannot upgrade Python, consider using an older `keystonemiddleware` version (e.g., 11.x for Python 3.9).","message":"Python 3.10 or higher is now required for keystonemiddleware 12.0.0. Older Python versions are no longer supported.","severity":"breaking","affected_versions":"12.0.0+"},{"fix":"Ensure `memcached_servers` is configured with the address(es) of your Memcached server(s) (e.g., `memcached_servers = 127.0.0.1:11211`) in your `AuthToken` configuration. Ensure Memcached is running and accessible.","message":"The `AuthToken` middleware now strictly requires `memcached_servers` to be configured for efficient token caching. If not set, token validation can be slow or fail under load.","severity":"gotcha","affected_versions":"12.0.0+"},{"fix":"Update your code to use `oslo_middleware.base.RequestBodySizeLimiter` for request body size limiting instead of `keystonemiddleware.multiformats`. Check the `oslo.middleware` documentation for usage details.","message":"The `keystonemiddleware.multiformats` module has been deprecated and its functionality has been moved to `oslo_middleware.base.RequestBodySizeLimiter`.","severity":"deprecated","affected_versions":"11.0.0+"},{"fix":"Double-check your Keystone configuration parameters, especially `auth_url` (Keystone endpoint URL, e.g., `http://<keystone-ip>:5000/v3`) and `www_authenticate_uri` (usually the same as `auth_url`). Ensure the service catalog type and name match your Keystone setup.","message":"Incorrect or missing `auth_url`, `www_authenticate_uri`, or service catalog type/name can lead to authentication failures or delays during discovery.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Add `memcached_servers = <ip>:<port>` to your AuthToken configuration. For example, `memcached_servers = 127.0.0.1:11211`.","cause":"The AuthToken middleware was initialized without specifying any Memcached servers, which is now a required configuration for token caching.","error":"AuthToken did not receive a value for 'memcached_servers'"},{"fix":"Verify that `auth_url` (e.g., `http://localhost:5000/v3`) is correct and that the Keystone service is running and network accessible from where your application is running. Check firewall rules or DNS issues.","cause":"Keystonemiddleware could not reach or properly discover the Keystone identity service based on the provided `auth_url` or `www_authenticate_uri`.","error":"raise DiscoveryException('Could not discover appropriate URL for identity service')"},{"fix":"Upgrade to Python 3.10+ as keystonemiddleware 12.0.0 requires it. If on an older version of `keystonemiddleware` and Python 3, ensure `oslo.config` is updated and config values are consistently handled as strings.","cause":"This error can occur in older Python 2 environments or with misconfigured `oslo.config` due to incompatible string handling when parsing configuration values.","error":"ValueError: Auth token is not an rstrip safe type (it's unicode)"}]}