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

Get started

Reverse-spec · Libraries

keystoneauth — Summary

Reverse-specification of 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

  • Scope: all non-test code of keystoneauth1 (about 20,000 lines, 92 files). The federation plugins (OIDC, SAML, ADFS, Kerberos) are described from their role.
  • References are file:line relative to the repository root. [inferred] marks a statement that was not followed to the end in the code.

Files of this specification

FileContent
01-library-api_stable-2026.2.mdbuilding blocks (Session, Adapter, plugins, discovery, catalog, loading), the 26 authentication plugins, request behaviour (headers, retries, redirects, re-authentication)
02-errors_stable-2026.2.mderror-body parsing, status-to-class mapping, connection, discovery and catalog errors, log masking
03-interactions_stable-2026.2.mdwhat is sent to Keystone, to the services and to the IdPs, and what is expected back
04-scenarios_stable-2026.2.md4 scenarios: discovery and call, re-authentication, MFA, application credential
05-async-processing_stable-2026.2.mdnone (in-process library); lazy renewal, rate limiting, discovery cache
06-change-history_stable-2026.2.md2 maintenance commits; 5.18.x is on master only
07-rewrite-pack_stable-2026.2.mdclient contract keystoneauth → Keystone and services, 9 scenarios recorded against Keystone stable/2026.2 (9/9)

Overview

keystoneauth is the HTTP and authentication library of OpenStack:

  • it obtains and renews tokens (password, token, application credential, MFA, federation, OAuth…);
  • it finds endpoints in the catalog and discovers versions and microversions;
  • it sends requests with the right headers, retries and redirects;
  • it turns errors into exceptions.

Every other client (openstackclient, osc-placement, openstacksdk, keystonemiddleware, the services) goes through it.

Key figures

26 authentication plugins (entry points); default retries 0 (statuses 429 and 503 when enabled); delay from 0.5 s to 60 s; 30 redirects at most; token renewal 120 s before expiry; 67 exception classes; 0 background processing.

Points of attention

  1. Version discovery goes before every endpoint of a service, unless the catalog URL already matches the requested version exactly: a service without a version document only works with the "version hack".
  2. Re-authentication on 401 happens only once per request: a service that answers 401 for another reason than an invalid token (bad configuration) causes a re-authentication, then fails.
  3. Microversions: the service type in OpenStack-API-Version is normalised (volume, shared-file-system), and the legacy headers are added for Nova and Ironic.
  4. Errors: only the first error of an API-SIG body is shown, and an unknown JSON body gives "Unrecognized schema in response body.".

Blind spots / [inferred]

  • The federation, OAuth and Kerberos plugins were not run (an external IdP or mTLS is needed).
  • The fixture, extras/betamax and hacking modules (test tools) were not analysed.

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