OpenKeel: the sovereign French Cloud solution of the inherent group, with a European reach Discover inherent

Get started

Reverse-spec · Libraries

keystoneauth — Library api

Library interface — keystoneauth — branch stable/2026.2

Branch stable/2026.2 @ 1cd5400202c6 (5.17.0 + 2 maintenance commits) — repository https://opendev.org/openstack/keystoneauth — analysed on 2026-10-28

keystoneauth (keystoneauth1) exposes no network service. It is the HTTP and authentication library shared by every OpenStack client and service: openstackclient, openstacksdk, keystonemiddleware, Nova (for Placement, Neutron, Cinder…), osc-placement. Its interface is a Python API and a set of authentication plugins. Its contract with the outside world is the requests it sends to Keystone and to the services (interactions, client contract).

1. Building blocks

BlockRoleSource
Sessionsends every request: headers, authentication, endpoint lookup, retries, redirects, logging, timingskeystoneauth1/session.py:302-1660
Adaptera Session bound to a service (service_type, interface, region_name, version, default_microversion, retries)keystoneauth1/adapter.py
auth plugins (BaseIdentityPlugin)get, cache and renew a token; give the endpoints of the catalog; drive version discoverykeystoneauth1/identity/base.py:34-570
discoverparse version documents, choose a version and a microversion, combine URLskeystoneauth1/discover.py
accessAccessInfoV2/V3 (token and catalog read from the Keystone response), ServiceCatalogkeystoneauth1/access/access.py, keystoneauth1/access/service_catalog.py
exceptionsHttpError hierarchy by status, connection and discovery errorskeystoneauth1/exceptions/
loadingbuild plugins, sessions and adapters from argparse options, oslo.config or a dictkeystoneauth1/loading/

2. Authentication plugins (entry points keystoneauth1.plugin, pyproject.toml:52-78)

Name (--os-auth-type)What it sends to Keystone
password, token (generic)first version discovery on auth_url, then the v3 (or v2) variant (keystoneauth1/identity/generic/base.py)
v3password, v3tokenPOST /v3/auth/tokens, method password (user by ID or by name + domain) or token
v3applicationcredentialmethod application_credential (ID + secret, or name + user)
v3totp, v3multifactortotp method, or several methods in a single request; reacts to MFA receipts
v3oidc* (5 variants), v3websso, v3samlpassword, v3adfspassword, v3fedkerbfederation: obtain an assertion or token from the IdP, then …/OS-FEDERATION/identity_providers/{idp}/protocols/{p}/auth, then rescoping
v3oauth1, v3oauth2clientcredential, v3oauth2mtlsclientcredentialOAuth1; OAuth2 client_credentials at /v3/OS-OAUTH2/token (secret or mTLS certificate)
v3kerberos, v3tokenlessauthKerberos (REMOTE_USER behind Apache); tokenless (client certificate + X-Project-* headers)
admin_token, none, http_basic, v2password, v2tokenfixed token; no authentication; HTTP Basic; Keystone v2 (obsolete)

Scope (keystoneauth1/identity/v3/base.py:186-227): exactly one of project (ID, or name + domain), domain, trust, system: {all: true} or "unscoped", otherwise AuthorizationFailure before any call.

3. Behaviours of Session.request (keystoneauth1/session.py:744-1162)

  1. URL: an absolute URL is used as is. A relative path needs an endpoint_filter, then get_endpoint() goes through the plugin: catalog, then version discovery.
  2. Headers:
    • User-Agent (keystoneauth1/<version> python-requests/…, plus the application);
    • X-Auth-Token from the plugin (get_auth_headers);
    • X-Openstack-Request-Id if a global_request_id is given;
    • microversion: OpenStack-API-Version: <service_type> <version>, plus the legacy headers X-OpenStack-Nova-API-Version / X-OpenStack-Ironic-API-Version. The service type is normalised: volume for Cinder, shared-file-system for Manila (keystoneauth1/session.py:683-742).
  3. Connection retries: connect_retries (default 0), exponential delay from 0.5 s, capped at 60 s (keystoneauth1/session.py:62-64, keystoneauth1/session.py:280-300).
  4. Status retries: status_code_retries (default 0) on retriable_status_codes, 429 and 503 by default.
  5. Redirects: handled by hand, up to 30 (_DEFAULT_REDIRECT_LIMIT), for 301/302/303/305/307/308. The method is kept, the params are dropped and the request ID is carried over (keystoneauth1/session.py:385-387, keystoneauth1/session.py:1246-1290).
  6. 401 after authentication: if allow_reauth, the plugin invalidates its token and the request is replayed once with a new token (keystoneauth1/session.py:1128-1136; verified by scenario 6 of the client contract).
  7. Status ≥ 400 with raise_exc (default): exceptions.from_response (see errors).

4. Token cache and renewal (keystoneauth1/identity/base.py:93-160)

The plugin keeps its AccessInfo. It re-authenticates when the token expires within **MIN_TOKEN_LIFE_SECONDS = 120 s**, or after invalidate(). Nothing is persisted to disk by default.

5. Endpoint selection (keystoneauth1/access/service_catalog.py:156-260, keystoneauth1/identity/base.py:166-335)

  1. Filter the catalog:
    • service_type, recognising the aliases of os-service-types (volumev3 ↔ block-storage…);
    • service_name and service_id when the catalog gives them;
    • region_name;
    • interface: public by default, or an ordered list of preferences, where publicURL, internalURL and adminURL are normalised.
  2. Then version discovery (EndpointData.get_versioned_data, keystoneauth1/discover.py:1205). It tries the candidate URLs in order (catalog URL, URL without the version, with project_id removed…; keystoneauth1/discover.py:1444-1520) and reads the first version document found.
    • Without a document: the catalog URL is used as is if the "version hack" is allowed, otherwise DiscoveryFailure.
    • Discovery is skipped when the catalog URL already matches the requested version exactly (_catalog_matches_exactly).
  3. endpoint_override short-circuits the catalog.

6. Configuration (loading)

  • CLI (keystoneauth1/loading/cli.py, keystoneauth1/loading/session.py): --os-auth-type (env OS_AUTH_TYPE or OS_AUTH_PLUGIN), the plugin's options (--os-auth-url, --os-username, --os-project-name…), --insecure, --os-cacert, --os-cert, --os-key, --timeout, --collect-timing, --tls-ciphers, --tls-min-version.
  • oslo.config (services): [<group>] auth_type, plugin options, cafile, certfile, keyfile, insecure, timeout… and for adapters service-type, service-name, valid-interfaces, region-name, endpoint-override, version, min-version, max-version, connect-retries, connect-retry-delay, status-code-retries, status-code-retry-delay, retriable-status-codes (keystoneauth1/loading/adapter.py).

Source: reverse-spec-keystoneauth/01-library-api_stable-2026.2.md. The _rewrite/ and _inventory/ files are not published on the site.