# keystoneauth1.plugin module

class keystoneauth1.plugin.BaseAuthPlugin

  Bases: `object`

  The basic structure of an authentication plugin.

  Note

  See Authentication Plugins for a description of plugins provided by this library.

  __annotations_cache__ = {'_discovery_cache': 'dict[str, discover.Discover]'}
  __dict__ = mappingproxy({'__module__': 'keystoneauth1.plugin', '__firstlineno__': 43, '__doc__': 'The basic structure of an authentication plugin.\n\n.. note::\n See :doc:`/authentication-plugins` for a description of plugins\n provided by this library.\n\n', '__init__': <function BaseAuthPlugin.__init__>, 'get_token': <function BaseAuthPlugin.get_token>, 'get_auth_ref': <function BaseAuthPlugin.get_auth_ref>, 'get_headers': <function BaseAuthPlugin.get_headers>, 'get_endpoint_data': <function BaseAuthPlugin.get_endpoint_data>, 'get_api_major_version': <function BaseAuthPlugin.get_api_major_version>, 'get_all_version_data': <function BaseAuthPlugin.get_all_version_data>, 'get_endpoint': <function BaseAuthPlugin.get_endpoint>, 'get_connection_params': <function BaseAuthPlugin.get_connection_params>, 'invalidate': <function BaseAuthPlugin.invalidate>, 'get_user_id': <function BaseAuthPlugin.get_user_id>, 'get_project_id': <function BaseAuthPlugin.get_project_id>, 'get_sp_auth_url': <function BaseAuthPlugin.get_sp_auth_url>, 'get_sp_url': <function BaseAuthPlugin.get_sp_url>, 'get_cache_id': <function BaseAuthPlugin.get_cache_id>, 'get_auth_state': <function BaseAuthPlugin.get_auth_state>, 'set_auth_state': <function BaseAuthPlugin.set_auth_state>, '__static_attributes__': ('_discovery_cache',), '__dict__': <attribute '__dict__' of 'BaseAuthPlugin' objects>, '__weakref__': <attribute '__weakref__' of 'BaseAuthPlugin' objects>, '__annotations_cache__': {'_discovery_cache': 'dict[str, discover.Discover]'}})
  __doc__ = 'The basic structure of an authentication plugin.\n\n.. note::\n See :doc:`/authentication-plugins` for a description of plugins\n provided by this library.\n\n'
  __firstlineno__ = 43
  __init__() → None
  __module__ = 'keystoneauth1.plugin'
  __static_attributes__ = ('_discovery_cache',)
  __weakref__

    list of weak references to the object

  _discovery_cache: dict[str, Discover]
  get_all_version_data(session: ks_session.Session, interface: str | list[str] | None = 'public', region_name: str | None = None, service_type: str | None = None) → dict[str, dict[str, dict[str, list[VersionData]]]]

    Get version data for all services in the catalog.

    Parameters:

      - session (keystoneauth1.session.Session) – A session object that can be used for communication.

      - interface – Type of endpoint to get version data for. Can be a single value or a list of values. A value of None indicates that all interfaces should be queried. (optional, defaults to public)

      - region_name (string) – Region of endpoints to get version data for. A valueof None indicates that all regions should be queried. (optional, defaults to None)

      - service_type (string) – Limit the version data to a single service. (optional, defaults to None)

    Returns:

      A dictionary keyed by region_name with values containing dictionaries keyed by interface with values being a list of `VersionData`.

  get_api_major_version(session: ks_session.Session, *, endpoint_override: str | None = None, **kwargs: Any) → tuple[int | float, ...] | None

    Get the major API version from the endpoint.

    Parameters:

      - session (keystoneauth1.session.Session) – A session object that can be used for communication.

      - endpoint_override (str) – URL to use for version discovery.

      - kwargs – Ignored.

    Raises:

      keystoneauth1.exceptions.http.HttpError – An error from an invalid HTTP response.

    Returns:

      Valid EndpointData or None if not available.

    Return type:

      keystoneauth1.discover.EndpointData or None

  get_auth_ref(session: ks_session.Session) → access.AccessInfo | None

    Return the authentication reference of an auth plugin.

    Parameters:

      session (keystoneauth1.session.session) – A session object to be used for communication

    Returns:

      An access info object if supported.

    Return type:

      keystoneauth1.access.AccessInfo or None

  get_auth_state() → object

    Retrieve the current authentication state for the plugin.

    Retrieve any internal state that represents the authenticated plugin.

    This should not fetch any new data if it is not present.

    Raises:

      NotImplementedError – if the plugin does not support this feature.

    Returns:

      raw python data (which can be JSON serialized) that can be moved into another plugin (of the same type) to have the same authenticated state.

    Return type:

      object or None if unauthenticated.

  get_cache_id() → str | None

    Fetch an identifier that uniquely identifies the auth options.

    The returned identifier need not be decomposable or otherwise provide anyway to recreate the plugin. It should not contain sensitive data in plaintext.

    This string MUST change if any of the parameters that are used to uniquely identity this plugin change.

    If get_cache_id returns a str value suggesting that caching is supported then get_auth_cache and set_auth_cache must also be implemented.

    Returns:

      A unique string for the set of options

    Return type:

      str or None if this is unsupported or unavailable.

  get_connection_params(session: ks_session.Session) → ConnectionParams

    Return any additional connection parameters required for the plugin.

    Parameters:

      session (keystoneauth1.session.Session) – The session object that the auth_plugin belongs to.

    Returns:

      Parameters that are passed to the requests library. Only the `cert` and `verify` parameters may be returned.

    Return type:

      dict

  get_endpoint(session: ks_session.Session, **kwargs: Any) → str | None

    Return an endpoint for the client.

    There are no required keyword arguments to `get_endpoint` as a plugin implementation should use best effort with the information available to determine the endpoint. However there are certain standard options that will be generated by the clients and should be used by plugins:

    - `service_type`: what sort of service is required.

    - `service_name`: the name of the service in the catalog.

    - `interface`: what visibility the endpoint should have.

    - `region_name`: the region the endpoint exists in.

    Parameters:

      - session (keystoneauth1.session.Session) – The session object that the auth_plugin belongs to.

      - kwargs – Ignored.

    Returns:

      The base URL that will be used to talk to the required service or None if not available.

    Return type:

      string

  get_endpoint_data(session: ks_session.Session, *, endpoint_override: str | None = None, discover_versions: bool = True, **kwargs: Any) → EndpointData | None

    Return a valid endpoint data for a service.

    Parameters:

      - session (keystoneauth1.session.Session) – A session object that can be used for communication.

      - endpoint_override (str) – URL to use for version discovery.

      - discover_versions (bool) – Whether to get version metadata from the version discovery document even if it major api version info can be inferred from the url. (optional, defaults to True)

      - kwargs – Ignored.

    Raises:

      keystoneauth1.exceptions.http.HttpError – An error from an invalid HTTP response.

    Returns:

      Valid EndpointData or None if not available.

    Return type:

      keystoneauth1.discover.EndpointData or None

  get_headers(session: ks_session.Session) → dict[str, str] | None

    Fetch authentication headers for message.

    This is a more generalized replacement of the older get_token to allow plugins to specify different or additional authentication headers to the OpenStack standard ‘X-Auth-Token’ header.

    How the authentication headers are obtained is up to the plugin. If the headers are still valid they may be re-used, retrieved from cache or the plugin may invoke an authentication request against a server.

    The default implementation of get_headers calls the get_token method to enable older style plugins to continue functioning unchanged. Subclasses should feel free to completely override this function to provide the headers that they want.

    Returning None will indicate that no token was able to be retrieved and that authorization was a failure. Adding no authentication data can be achieved by returning an empty dictionary.

    Parameters:

      session (keystoneauth1.session.Session) – The session object that the auth_plugin belongs to.

    Returns:

      Headers that are set to authenticate a message or None for failure. Note that when checking this value that the empty dict is a valid, non-failure response.

    Return type:

      dict

  get_project_id(session: ks_session.Session) → str | None

    Return the project id that we are authenticated to.

    Wherever possible the project id should be inferred from the token however there are certain URLs and other places that require access to the currently authenticated project id.

    Parameters:

      session (keystoneauth1.session.Session) – A session object so the plugin can make HTTP calls.

    Returns:

      A project identifier or None if one is not available.

    Return type:

      str

  get_sp_auth_url(session: ks_session.Session, sp_id: str) → str | None

    Return auth_url from the Service Provider object.

    This url is used for obtaining unscoped federated token from remote cloud.

    Parameters:

      sp_id (string) – ID of the Service Provider to be queried.

    Returns:

      A Service Provider auth_url or None if one is not available.

    Return type:

      str

  get_sp_url(session: ks_session.Session, sp_id: str) → str | None

    Return sp_url from the Service Provider object.

    This url is used for passing SAML2 assertion to the remote cloud.

    Parameters:

      sp_id (str) – ID of the Service Provider to be queried.

    Returns:

      A Service Provider sp_url or None if one is not available.

    Return type:

      str

  get_token(session: ks_session.Session) → str | None

    Obtain a token.

    How the token is obtained is up to the plugin. If it is still valid it may be re-used, retrieved from cache or invoke an authentication request against a server.

    Returning None will indicate that no token was able to be retrieved.

    This function is misplaced as it should only be required for auth plugins that use the ‘X-Auth-Token’ header. However due to the way plugins evolved this method is required and often called to trigger an authentication request on a new plugin.

    When implementing a new plugin it is advised that you implement this method, however if you don’t require the ‘X-Auth-Token’ header override the get_headers method instead.

    Parameters:

      session (keystoneauth1.session.Session) – A session object so the plugin can make HTTP calls.

    Returns:

      A token to use.

    Return type:

      string

  get_user_id(session: ks_session.Session) → str | None

    Return a unique user identifier of the plugin.

    Wherever possible the user id should be inferred from the token however there are certain URLs and other places that require access to the currently authenticated user id.

    Parameters:

      session (keystoneauth1.session.Session) – A session object so the plugin can make HTTP calls.

    Returns:

      A user identifier or None if one is not available.

    Return type:

      str

  invalidate() → bool

    Invalidate the current authentication data.

    This should result in fetching a new token on next call.

    A plugin may be invalidated if an Unauthorized HTTP response is returned to indicate that the token may have been revoked or is otherwise now invalid.

    Returns:

      True if there was something that the plugin did to invalidate. This means that it makes sense to try again. If nothing happens returns False to indicate give up.

    Return type:

      bool

  set_auth_state(data: str) → None

    Install existing authentication state for a plugin.

    Take the output of get_auth_state and install that authentication state into the current authentication plugin.

    Raises:

      NotImplementedError – if the plugin does not support this feature.

class keystoneauth1.plugin.ConnectionParams

  Bases: `TypedDict`

  __annotations_cache__ = {'cert': typing.NotRequired[str | tuple[str, str] | None], 'verify': typing.NotRequired[bool | str | None]}
  __dict__ = mappingproxy({'__module__': 'keystoneauth1.plugin', '__firstlineno__': 36, '__static_attributes__': (), '__orig_bases__': (<function TypedDict>,), '__dict__': <attribute '__dict__' of 'ConnectionParams' objects>, '__weakref__': <attribute '__weakref__' of 'ConnectionParams' objects>, '__doc__': None, '__required_keys__': frozenset(), '__optional_keys__': frozenset({'verify', 'cert'}), '__readonly_keys__': frozenset(), '__mutable_keys__': frozenset({'verify', 'cert'}), '__total__': True, '__annotations_cache__': {'cert': typing.NotRequired[str | tuple[str, str] | None], 'verify': typing.NotRequired[bool | str | None]}})
  __doc__ = None
  __firstlineno__ = 36
  __module__ = 'keystoneauth1.plugin'
  __mutable_keys__ = frozenset({'cert', 'verify'})
  __optional_keys__ = frozenset({'cert', 'verify'})
  __orig_bases__ = (<function TypedDict>,)
  __readonly_keys__ = frozenset({})
  __required_keys__ = frozenset({})
  __static_attributes__ = ()
  __total__ = True
  __weakref__

    list of weak references to the object

  cert: NotRequired[str | tuple[str, str] | None]
  verify: NotRequired[bool | str | None]

class keystoneauth1.plugin.FixedEndpointPlugin(endpoint: str | None = None)

  Bases: `BaseAuthPlugin`

  A base class for plugins that have one fixed endpoint.

  __annotate_func__ = None
  __annotations_cache__ = {}
  __doc__ = 'A base class for plugins that have one fixed endpoint.'
  __firstlineno__ = 413
  __init__(endpoint: str | None = None)
  __module__ = 'keystoneauth1.plugin'
  __static_attributes__ = ('endpoint',)
  get_endpoint(session: ks_session.Session, endpoint_override: str | None = None, **kwargs: Any) → str | None

    Return the supplied endpoint.

    Using this plugin the same endpoint is returned regardless of the parameters passed to the plugin. endpoint_override overrides the endpoint specified when constructing the plugin.

  get_endpoint_data(session: ks_session.Session, *, endpoint_override: str | None = None, discover_versions: bool = True, **kwargs: Any) → EndpointData | None

    Return a valid endpoint data for a the service.

    Parameters:

      - session (keystoneauth1.session.Session) – A session object that can be used for communication.

      - endpoint_override (str) – URL to use for version discovery.

      - discover_versions (bool) – Whether to get version metadata from the version discovery document even if it major api version info can be inferred from the url. (optional, defaults to True)

      - kwargs – Ignored.

    Raises:

      keystoneauth1.exceptions.http.HttpError – An error from an invalid HTTP response.

    Returns:

      Valid EndpointData or None if not available.

    Return type:

      keystoneauth1.discover.EndpointData or None

this page last updated: 2026-07-14 15:48:40

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug