ansys-openapi-common 1.1.1

Provides a helper to create sessions for use with Ansys OpenAPI clients.

Project Overview

The openapi-common repository provides the source code for authentication-aware client for OpenAPI client libraries.

The PyAnsys OpenAPI Common library is intended for use with the custom code generation template in the PyAnsys project. This library currently 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.

Installing the Source Repository

Install openapi-common with:

pip install ansys-openapi-common

Alternatively, clone and install with:

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. We suggest that you override the __init__() or connect() methods 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.

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

Supported Authentication Schemes

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

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 will require 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 we support only the Authorization Code authentication flow.

Authentication Methods by Platform

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. The OpenAPI Common library has been tested on the platforms listed below. 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 Python module gssapi 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.

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

The OpenAPI Common library 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.