# openstack/keystone architecture

> Architecture diagram of the GitHub repository openstack/keystone, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openstack/keystone
- Repository: https://github.com/openstack/keystone

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    subgraph "Clients" 
        direction TB
        OS_Services["OpenStack Services (Nova, Glance, etc.)"]:::external
        CLI_SDK["CLI & python-keystoneclient"]:::external
        FED_IdP["Federation IdP/SP"]:::external
    end

    %% HTTP Server Layer
    subgraph "HTTP Server" 
        direction TB
        HTTP_Server["Apache/Nginx + uWSGI"]:::server
        WSGI_Server["WSGI Server Module"]:::server
    end

    %% WSGI Application
    subgraph "WSGI Application" 
        direction TB
        Flask_App["Flask WSGI App"]:::server
        Middleware["Middleware Pipeline"]:::server
        JSON_Parsing["JSON Body Parser"]:::server
        Common_Helpers["Flask Common Helpers"]:::server
    end

    %% API Controllers
    subgraph "API Controllers (keystone/api)" 
        direction TB
        API_v2["v2 Controllers"]:::api
        API_v3["v3 Controllers"]:::api
        API_Ext["Extensions (federation, OAuth, endpoint policy)"]:::api
        Shared_API["Shared API Utilities"]:::api
    end

    %% Core Managers
    subgraph "Core Business Logic" 
        direction TB
        Auth_Manager["Authentication Manager"]:::core
        Assignment_Manager["Assignment Manager"]:::core
        Identity_Manager["Identity Manager"]:::core
        Catalog_Manager["Catalog Manager"]:::core
        Credential_Manager["Credential Manager"]:::core
        Token_Manager["Token Manager"]:::core
        Policy_Enforcer["Policy Enforcer"]:::core
        Receipt_Provider["Receipt Provider"]:::core
        Trust_Manager["Trust Manager"]:::core
    end

    %% Pluggable Backends
    subgraph "Pluggable Backends" 
        direction TB
        SQL_Backends["SQL Backends"]:::backend
        LDAP_Backends["LDAP Backends"]:::backend
        Token_Providers["Token Providers (Fernet, JWS)"]:::backend
        OAuth1_Backend["OAuth1 Backend"]:::backend
        AppCred_Backend["Application Credential Backend"]:::backend
    end

    %% Data Stores & External Systems
    subgraph "Data Stores & External" 
        direction TB
        Relational_DB["Relational DB (MySQL/PostgreSQL)"]:::database
        Cache["Cache (Memcached/Redis)"]:::database
        LDAP_Server["External LDAP Server"]:::external
        External_IdP["External Identity Provider"]:::external
        PKI["PKI Infrastructure"]:::external
    end

    %% Configuration & Docs
    subgraph "Configuration & Docs"
        direction TB
        Config["Config Samples & HTTPD Manifests"]:::config
        Playbooks["Dev & CI Playbooks"]:::config
        APIDocs["OpenAPI Documentation"]:::config
        SphinxDocs["Sphinx Documentation"]:::config
        PKI_Examples["PKI Example Certificates"]:::config
    end

    %% Flows
    OS_Services -->|HTTPS| HTTP_Server
    CLI_SDK -->|HTTPS| HTTP_Server
    FED_IdP -->|SAML2| HTTP_Server

    HTTP_Server --> WSGI_Server
    WSGI_Server --> Flask_App
    Flask_App --> Middleware
    Middleware --> JSON_Parsing
    JSON_Parsing --> Common_Helpers
    Common_Helpers --> API_v2
    Common_Helpers --> API_v3
    Common_Helpers --> API_Ext
    API_v2 --> Auth_Manager
    API_v3 --> Auth_Manager
    API_Ext --> Auth_Manager

    Auth_Manager --> Assignment_Manager
    Auth_Manager --> Identity_Manager
    Identity_Manager --> Catalog_Manager
    Assignment_Manager --> Catalog_Manager
    Identity_Manager --> Credential_Manager
    Identity_Manager --> Trust_Manager
    Credential_Manager --> Token_Manager
    Token_Manager --> Receipt_Provider
    Receipt_Provider --> Policy_Enforcer

    %% Backends
    Auth_Manager -->|driver| LDAP_Backends
    Assignment_Manager -->|driver| SQL_Backends
    Identity_Manager -->|driver| SQL_Backends
    Catalog_Manager -->|driver| SQL_Backends
    Credential_Manager -->|driver| SQL_Backends
    Policy_Enforcer -->|driver| SQL_Backends
    Token_Manager -->|provider| Token_Providers
    Token_Manager -->|provider| OAuth1_Backend
    Trust_Manager -->|driver| AppCred_Backend

    %% Data stores
    SQL_Backends --> Relational_DB
    Token_Providers --> Relational_DB
    LDAP_Backends --> LDAP_Server
    Cache --> Common_Helpers
    External_IdP --> API_Ext
    PKI --> Token_Providers

    %% Config & Docs
    Config --> Flask_App
    Playbooks --> HTTP_Server
    APIDocs --> API_v2
    APIDocs --> API_v3
    SphinxDocs --> Config
    PKI_Examples --> PKI

    %% Click Events
    click Flask_App "https://github.com/openstack/keystone/blob/master/keystone/server/flask/application.py"
    click WSGI_Server "https://github.com/openstack/keystone/blob/master/keystone/server/wsgi.py"
    click Middleware "https://github.com/openstack/keystone/tree/master/keystone/server/flask/request_processing/middleware/"
    click JSON_Parsing "https://github.com/openstack/keystone/blob/master/keystone/server/flask/request_processing/json_body.py"
    click Common_Helpers "https://github.com/openstack/keystone/blob/master/keystone/server/flask/common.py"
    click API_v2 "https://github.com/openstack/keystone/tree/master/keystone/api/"
    click Shared_API "https://github.com/openstack/keystone/tree/master/keystone/api/_shared/"
    click Auth_Manager "https://github.com/openstack/keystone/blob/master/keystone/auth/core.py"
    click Assignment_Manager "https://github.com/openstack/keystone/blob/master/keystone/assignment/core.py"
    click Identity_Manager "https://github.com/openstack/keystone/blob/master/keystone/identity/core.py"
    click Catalog_Manager "https://github.com/openstack/keystone/blob/master/keystone/catalog/core.py"
    click Credential_Manager "https://github.com/openstack/keystone/blob/master/keystone/credential/core.py"
    click Token_Manager "https://github.com/openstack/keystone/blob/master/keystone/token/provider.py"
    click Token_Providers "https://github.com/openstack/keystone/blob/master/keystone/credential/providers/fernet/core.py"
    click Policy_Enforcer "https://github.com/openstack/keystone/blob/master/keystone/policy/core.py"
    click Receipt_Provider "https://github.com/openstack/keystone/blob/master/keystone/receipt/provider.py"
    click Trust_Manager "https://github.com/openstack/keystone/blob/master/keystone/trust/core.py"
    click SQL_Backends "https://github.com/openstack/keystone/blob/master/keystone/identity/backends/sql.py"
    click LDAP_Backends "https://github.com/openstack/keystone/tree/master/keystone/identity/backends/ldap/"
    click AppCred_Backend "https://github.com/openstack/keystone/blob/master/keystone/application_credential/backends/sql.py"
    click OAuth1_Backend "https://github.com/openstack/keystone/blob/master/keystone/oauth1/backends/sql.py"
    click Token_Providers "https://github.com/openstack/keystone/blob/master/keystone/token/providers/jws/core.py"
    click SQL_Backends "https://github.com/openstack/keystone/tree/master/keystone/common/sql/migrations/"
    click Config "https://github.com/openstack/keystone/tree/master/httpd/"
    click Playbooks "https://github.com/openstack/keystone/tree/master/devstack/"
    click APIDocs "https://github.com/openstack/keystone/tree/master/api-ref/source/"
    click SphinxDocs "https://github.com/openstack/keystone/tree/master/doc/source/"
    click PKI_Examples "https://github.com/openstack/keystone/tree/master/examples/pki/"

    %% Styles
    classDef external fill:#CCE5FF,stroke:#3399FF,color:#000;
    classDef server fill:#CCFFCC,stroke:#33CC33,color:#000;
    classDef api fill:#E6FFCC,stroke:#99CC33,color:#000;
    classDef core fill:#FFFFCC,stroke:#CCCC33,color:#000;
    classDef backend fill:#FFCCCC,stroke:#CC3333,color:#000;
    classDef database fill:#FFE6CC,stroke:#FF9933,color:#000;
    classDef config fill:#F2F2F2,stroke:#666666,color:#000;
```
