Session

class igwn_auth_utils.Session(token=None, token_audience=None, token_scope=None, cert=None, auth=None, url=None, force_noauth=False, fail_if_noauth=False, **kwargs)[source]

requests.Session class with default IGWN authorization handling

Discovery/configuration of authorisation/authentication methods is attempted in the following order:

  1. if force_noauth=True is given, no auth is configured;

  2. for SciTokens:

    1. if a bearer token is provided via the token keyword argument, then use that, or

    2. look for a bearer token by passing the token_audience and token_scope keyword parameters to igwn_auth_utils.find_scitokens();

  3. for X.509 credentials:

    1. if an X.509 credential path is provided via the cert keyword argument, then use that, or

    2. look for an X.509 credential using igwn_auth_utils.find_x509_credential()

  4. for basic auth (username/password):

    1. if auth keyword is provided, then use that, or

    2. read the netrc file located at ~/.netrc, or at the path stored in the $NETRC environment variable, and look for a username and password matching the hostname given in the url keyword argument;

  5. if none of the above yield a credential, and fail_if_noauth=True was provided, raise a ValueError.

Steps 2-4 are all tried independently, with all valid credentials (one per type) configured for the session. It is up to the request receiver to handle the multiple credential types and prioritise between them.

Parameters:
token=None

Bearer token (scitoken) input, one of

  • a bearer token (scitokens.SciToken),

  • a serialised token (str, bytes),

  • False: disable using tokens completely

  • True: discover a valid token via igwn_auth_utils.find_scitoken() and error if something goes wrong

  • None: try and discover a valid token, but try something else if that fails

token_audience=None

The value(s) of the audience (aud) claim to pass to igwn_auth_utils.find_scitoken() when discovering available tokens.

token_scope=None

The value(s) of the scope audience and scope to pass to igwn_auth_utils.find_scitoken() when discovering available tokens.

cert=None

X.509 credential input, one of

auth=None

(username, password) tuple or other authentication/authorization object to attach to a Request

url=None

the URL/host that will be queried within this session; this is used to set the default token_audience and to access credentials via safe_netrc.

force_noauth=False

Disable the use of any authorisation credentials (mainly for testing).

fail_if_noauth=False

Raise a IgwnAuthError if no authorisation credentials are presented or discovered.

Raises:

IgwnAuthError – If cert=True or token=True is given and the relevant credential was not actually discovered, or if fail_if_noauth=True is given and no authorisation token/credentials of any valid type are presented or discovered.

See also

requests.Session

for details of the standard options

igwn_auth_utils.find_scitoken

for details of the SciToken discovery

igwn_auth_utils.find_x509_credentials

for details of the X.509 credential discovery

Examples

To use the default authorisation discovery:

>>> from igwn_auth_utils.requests import Session
>>> with Session() as sess:
...     sess.get("https://science.example.com/api/important/data")

To explicitly pass a specific SciToken as the token:

>>> with Session(token=mytoken) as sess:
...     sess.get("https://science.example.com/api/important/data")

To explicitly require that a token is discovered, and disable any X.509 discovery:

>>> with Session(token=True, x509=False) as sess:
...     sess.get("https://science.example.com/api/important/data")

To use default authorisation discovery, but fail if no credentials are discovered:

>>> with Session(fail_if_noauth=True) as sess:
...     sess.get("https://science.example.com/api/important/data")

To disable all authorisation discovery:

>>> with Session(force_noauth=True) as sess:
...     sess.get("https://science.example.com/api/important/data")