Metadata-Version: 2.1
Name: ansys-openapi-common
Version: 1.2.2
Summary: Provides a helper to create sessions for use with Ansys OpenAPI clients.
Home-page: https://github.com/pyansys/openapi-common
License: MIT
Keywords: Ansys,OpenAPI
Author: ANSYS, Inc.
Maintainer: PyAnsys Maintainers
Maintainer-email: pyansys.maintainers@ansys.com
Requires-Python: >=3.7,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Provides-Extra: linux-kerberos
Provides-Extra: oidc
Requires-Dist: importlib_metadata (>=1.0) ; python_version < "3.8"
Requires-Dist: keyring (>=22,<24) ; extra == "oidc"
Requires-Dist: pyparsing (>=3.0.8,<4.0.0)
Requires-Dist: python-dateutil (>=2.6.1,<3.0.0)
Requires-Dist: requests (>=2.26,<3.0)
Requires-Dist: requests-kerberos (>=0.13,<0.14) ; (sys_platform == "linux") and (extra == "linux-kerberos")
Requires-Dist: requests-negotiate-sspi (>=0.5.2,<0.6.0) ; sys_platform == "win32"
Requires-Dist: requests-ntlm (>=1.1.0,<2.0.0)
Requires-Dist: requests_auth (>=6.0,<7.0) ; extra == "oidc"
Requires-Dist: typing-extensions (>=4.1,<5.0) ; python_version < "3.8"
Project-URL: Documentation, https://openapi.docs.pyansys.com
Project-URL: Repository, https://github.com/pyansys/openapi-common
Description-Content-Type: text/x-rst

Overview
--------

OpenAPI-Common is intended for use with the custom code generation
template in the `PyAnsys project <https://github.com/pyansys>`_. 
It provides the source code for an authentication-aware
client for OpenAPI client libraries.

OpenAPI-Common supports authentication with Basic, Negotiate, NTLM,
and OpenID Connect. Most features of the underlying requests session
are exposed for use. Some basic configuration is also provided by default.

Installation
------------

Install the ``openapi-common`` repository with this code:

.. code::

   pip install ansys-openapi-common

Alternatively, clone and install the repository with this code:

.. code::

   git clone https://github.com/pyansys/openapi-common
   cd openapi-common
   pip install .


Usage
-----

The API client class is intended to be wrapped by code that implements a client library.
You should override the ``__init__()`` or ``connect()`` method to add any
additional behavior that might be required.

Authentication is configured through the ``ApiClientFactory`` object and its ``with_xxx()``
methods. If no authentication is required, you can use the ``with_anonymous()`` method.
You can provide additional configuration with the ``SessionConfiguration`` object.

.. code:: python

   >>> from ansys.openapi.common import ApiClientFactory
   >>> session = ApiClientFactory('https://my-api.com/v1.svc')
   ...           .with_autologon()
   ...           .connect()
   <ApiClient url: https://my-api.com/v1.svc>


Authentication schemes
----------------------

OpenAPI-Common supports API servers configured with no authentication, API keys,
client certificates, and basic authentication schemes. 

Windows users can also use Windows Integrated Authentication to connect to Kerberos-enabled
APIs with their Windows credentials and to NTLM where it is supported.

Linux users can make use of Kerberos authentication via the ``[linux-kerberos]`` extra. This
requires a working installation of either MIT Kerberos or Heimdal, as well as some
platform-specific build steps. An additional requirement is a correctly configured ``krb5.keytab``
file on your system.

Windows and Linux users can authenticate with OIDC-enabled APIs by using the ``[oidc]`` extra.
Currently only the Authorization Code authentication flow is supported.

.. list-table:: Authentication methods by platform
   :header-rows: 1

   * - Authentication method
     - Windows
     - Linux
     - Builder method
     - Additional settings
   * - API Key
     - ✔️
     - ✔️
     - ``.with_anonymous()``
     - Set the appropriate header in ``api_session_configuration``
   * - Client Certificate
     - ✔️
     - ✔️
     - Any
     - Provide ``client_cert_path`` and optionally ``client_cert_key`` in ``api_session_configuration``
   * - Basic
     - ✔️
     - ✔️
     - ``.with_credentials()``
     -
   * - NTLM
     - ✔️
     - ❌
     - ``.with_credentials()``
     -
   * - Kerberos
     - ✔️
     - ➕ with ``[linux-kerberos]`` extra
     - ``.with_autologon()``
     -
   * - OIDC
     - ➕ with ``[oidc]`` extra
     - ➕ with ``[oidc]`` extra
     - ``.with_oidc()``
     -

Platform-specific Kerberos configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Kerberos authentication should be supported wherever the MIT or Heimdal Kerberos client
can be installed. OpenAPI-Common has been tested on the platforms that follow.
If you manage to use it on another platform, consider contributing installation steps for
your platform by making a pull request.

Ubuntu 20.04
============

Ubuntu requires the ``gssapi`` Python module to be built from source. This requires the
Kerberos headers, Python headers for the version of Python that you are using, and a
supported compiler. (GCC works well.)

You should then be able to install this module with the ``[linux-kerberos]`` extra.

.. code-block:: bash

   sudo apt install build-essentials python3.8-dev libkrb5-dev
   pip install ansys-openapi-common[linux-kerberos]


Once the installation completes, ensure that your ``krb5.conf`` file is set up correctly
for your Kerberos configuration and that you have a valid ``keytab`` file, which is
normally in ``/etc/krb5.keytab``.

License
-------
OpenAPI-Common is provided under the terms of the MIT license. You can find
the license text in the LICENSE file at the root of the repository.

