Session¶
-
class igwn_auth_utils.Session(token=
None
, token_audience=None
, token_scope=None
, token_issuer=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:
if
force_noauth=True
is given, no auth is configured;for SciTokens:
if a bearer token is provided via the
token
keyword argument, then use that, orlook for a bearer token by passing the
token_audience
andtoken_scope
keyword parameters toigwn_auth_utils.find_scitokens()
;
for X.509 credentials:
if an X.509 credential path is provided via the
cert
keyword argument, then use that, orlook for an X.509 credential using
igwn_auth_utils.find_x509_credential()
for basic auth (username/password):
if
auth
keyword is provided, then use that, orread 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 theurl
keyword argument;
if none of the above yield a credential, and
fail_if_noauth=True
was provided, raise aValueError
.
Steps 2 and 3 are all tried independently, with all valid credentials (one per type) configured for the session. Only when SciTokens are disabled (
token=False
), will step 4 will be tried to configure basic username/password auth. 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
- token_audience=
None
¶ The value(s) of the audience (
aud
) claim to pass toigwn_auth_utils.find_scitoken()
when discovering available tokens.- token_scope=
None
¶ The value(s) of the
scope
to pass toigwn_auth_utils.find_scitoken()
when discovering available tokens.- token_issuer=
None
¶ The value of the issuer (
iss
) claim to pass toigwn_auth_utils.find_scitoken()
when discovering available tokens.- cert=
None
¶ X.509 credential input, one of
path to a PEM-format certificate file,
a
(cert, key)
tuple
,False
: disable using X.509 completelyTrue
: discover a valid cert viaigwn_auth_utils.find_x509_credentials()
and error if something goes wrongNone
: try and discover a valid cert, but try something else if that fails
- auth=
None
¶ (username, password)
tuple
or other authentication/authorization object to attach to aRequest
. By default a newHTTPSciTokenAuth
handler will be attached to configureAuthorization
headers for each 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 viasafe_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.- raise_for_status :
bool
, optional If
True
(default), automatically callraise_for_status()
after receiving any response.
- token=
- Raises:¶
IgwnAuthError – If
cert=True
ortoken=True
is given and the relevant credential was not actually discovered, or iffail_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")