User guide

Basic usage

The ApiClient class is designed to be wrapped by code that implements a client library. You should override the __init__() or connect() methods to add additional required behavior.

Authentication is configured through the ApiClientFactory object and its with_xxx() methods. If no authentication is required, you can use the with_anonymous() method.

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

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.

Authentication methods by platform

Authentication method	Windows	Linux	Builder method
API Key	✔️	✔️	.with_anonymous() [1]
Basic	✔️	✔️	.with_credentials()
NTLM	✔️	❌	.with_credentials()
Kerberos	✔️	➕ [2]	.with_autologon()
OIDC	➕ [3]	➕ [3]	.with_oidc()

[1]

Set the appropriate header in api_session_configuration.

[2]

When installed as pip install ansys-openapi-common[linux-kerberos].

[3] (1,2)

When installed as pip install ansys-openapi-common[oidc].

Session configuration

You can set all options that are available in Python library requests through the client with the SessionConfiguration object. This enables you to configure custom SSL certificate validation, send client certificates if your API server requires them, and configure many other options.

For example, to send a client certificate with every request:

>>> from ansys.openapi.common import SessionConfiguration
>>> configuration = SessionConfiguration(
...    client_cert_path='./my-client-cert.pem',
...    client_cert_key='secret-key'
... )
>>> client.configuration = configuration

HTTPS certificates

The requests library uses the certifi package to verify TLS certificates instead of a local system certificate store. These means only TLS certificates signed by a public CA can be verified by requests in its default configuration. If you need to verify internally signed TLS certificates, there are two recommended approaches:

pip-system-certs

The pip-system-certs library patches the certificate loading mechanism for requests causing it to use your system certificate store. This is the simplest solution, but there are two potential limitations:

1. pip-system-certs does not support every platform that is supported by CPython, so it may not be supported on your platform.

2. The change to requests affects every package in your environment, including pip. Make sure you are using a virtual environment.

Note

If you are using OIDC authentication and your service provides an internally signed certificate you must use this option.

Custom certificate store

The SessionConfiguration object allows you to provide a path to a custom CA certificate. If provided, the custom CA certificate is used to verify the service’s TLS certificate instead of the certifi package.