How openstack/keystone works
Project type and purpose
• Project: OpenStack Keystone
• Type: Backend identity microservice (HTTP-based REST API)
• Purpose: Provide authentication, authorization, token issuance, multi-tenancy, federation, and service discovery for OpenStack components (commonly deployed behind HTTP servers, with pluggable backends such as SQL or LDAP).
File structure
• Top-level “keystone/” directory holds the application code, subdivided into:
– keystone/server/flask: WSGI application and middleware
– keystone/api: HTTP controllers for v2, v3, extensions (federation, OAuth, endpoint policy)
– keystone/auth, assignment, catalog, credential, identity, limit, policy, receipt, resource, revoke, token, trust, federation: Core modules implementing business logic and pluggable backends (in each area you see “backends/sql.py” or “backends/ldap”).
• keystone/common: Shared utilities (caching, context, policies, SQL migrations via Alembic).
• Configuration & deployment: etc/*.conf.sample, httpd/*.ini, devstack/ and playbooks/ for local development & CI.
• Documentation: doc/source (Sphinx), api-ref/source (OpenAPI, samples), releasenotes/, examples/pki.
README for insights
• Keystone exposes HTTP APIs (REST) for identity management
• Supports v2, v3, extensions (OAuth, federation, endpoint policy)
• Pluggable identity backends (SQL, LDAP), token providers (Fernet, JWS), authentication plugins.
• Deploys as WSGI app behind Apache/uWSGI.
Diagramming the architecture
a. Main components:
1. Clients:
– OpenStack services (Nova, Glance, etc.), CLI, python-keystoneclient, curl, federation IdP/SP
2. Front-end HTTP server:
– Apache or Nginx + uWSGI (httpd/keystone-uwsgi-*.ini)
3. WSGI Application:
– Flask‐based request pipeline (keystone/server/flask)
– Middleware layers: URL normalization, request logging, auth context injection
4. API Controllers:
– keystone/api/v2 and v3 controllers, extension modules (federation, OAuth, endpoint policy)
5. Core Managers:
– Auth manager, Assignment manager, Identity manager, Catalog manager, Token manager, Policy enforcer, Receipt provider, etc.
6. Pluggable Backends:
– SQL (via SQLAlchemy + Alembic migrations in keystone/common/sql)
– LDAP (keystone/identity/backends/ldap)
– Other providers (fernet tokens, JWS tokens, OAuth1, OAuth2, application credentials)
7. External Systems:
– LDAP servers, federation IdPs, PKI infrastructure, Memcached/Redis for caching
8. Data stores:
– Relational DB (MySQL/PostgreSQL), key repository storage, config files
b. Relationships & interactions:
– Clients → HTTP server (HTTPS) → WSGI pipeline → Router → Controller → Core Manager
– Core Manager → Pluggable Backend Driver → Data Store or External System
– Policy enforcer invoked in controllers before core managers
– Token issuance: core manager → token provider (fernet or JWS) → stores token metadata in DB
– Federation: controller delegates to federation core → federation drivers → external IdP
c. Architectural patterns & principles:
– Layered architecture (presentation/API → business logic/core managers → data access/backends)
– Pluggable drivers via configuration (SQL vs. LDAP, token providers, auth plugins)
– Middleware pipeline for cross-cutting concerns (logging, auth context)
– Use of standard HTTP REST with OpenAPI docs (api-ref)
– Sphinx for docs, Alembic for DB migrations, Flask+WSGI for server
d. Key technologies/frameworks:
– Python 3, Flask, WSGI, uWSGI, Apache/Nginx
– SQLAlchemy + Alembic, LDAP libraries
– Memcached/Redis for cache (via oslo.cache)
– OpenAPI/Sphinx for documentation
– Fernet/JWS for token cryptography, Python oslo.* libraries
Detail orientation
• Pluggable paths (token providers, auth plugins, identity backends, assignment backends).
• Alembic migration subsystem for DB versioning (keystone/common/sql/migrations).
• Documentation build pipeline (Sphinx, OpenAPI generator under api-ref).
• Configuration files (in etc/) feeding into the application on startup.