Authentication¶

Environmental Intelligence: Geospatial APIs SDK (ibmpairs): A Python module to wrap the core functionality of the Geospatial APIs component.

SPDX-License-Identifier: BSD-3-Clause

class authentication.Basic(host: str = None, username: str = None, password: str = None, password_file: str = 'auth/basic.txt', legacy: bool = None, version: int = None)¶

An object to represent basic credentials and recovery from a file.

Parameters:

host (str) – IBM PAIRS host
username (str) – IBM PAIRS username
password (str) – IBM PAIRS password
password_file (str) – IBM PAIRS password file, defaults to auth/basic.txt
legacy (bool) – IBM EIS GA Legacy Environment selector override
version (int) – IBM EIS GA api version (default: 3)

Raises:

Exception – if username and password are not present

from_dict()¶

Create a Basic authentication object from a dictionary.

Parameters:: authentication_dict (Any) – A dictionary that contains the keys of a Basic object.
Return type:: ibmpairs.authentication.Basic
Raises:: Exception – if not a dictionary.

from_json()¶

Create an Basic object from json (dictonary or str).

Parameters:: basic_dict (Any) – A json dictionary that contains the keys of an Basic or a string representation of a json dictionary.
Return type:: ibmpairs.authentication.Basic
Raises:: Exception – if not a dictionary or a string.

get_credentials_from_file(username, password_file, host)¶

Gets username and password credentials from a file, calls get_password_from_file.

Parameters:

username (str) – The username string.
password_file (str) – The password_file string.
host (str) – The host string.

Returns:

Username and password.

Return type:

tuple

Raises:

Exception – if password file does not exist, if password was not found.

set_credentials_from_file(username, password_file, host)¶

Set credentials attributes from a file, calls get_password_from_file.

Parameters:

username (str) – The username string.
password_file (str) – The password_file string.
host (str) – The host string.

Raises:

Exception – if password file does not exist, if password was not found

to_dict()¶

Create a dictionary from the objects structure.

Return type:: dict

to_json()¶

Create a string representation of a json dictionary from the objects structure.

Return type:: string

class authentication.OAuth2(host: str = None, username: str = None, api_key: str = None, api_key_file: str = 'auth/oauth2.txt', client_id: str = None, endpoint: str = None, jwt_token: str = None, iam_endpoint: str = 'iam.cloud.ibm.com', org_id: str = None, tenant_id: str = None, legacy: bool = None, version: int = None)¶

An object to represent OAuth2 credentials and recovery from a file.

Parameters:

host (str) – IBM PAIRS host
username (str) – IBM PAIRS username
api_key (str) – IBM PAIRS API key
api_key_file (str) – IBM PAIRS API key file, defaults to auth/oauth2.txt
client_id (str) – A client id for the authentication system, defaults to ‘ibm-pairs’ if legacy.
endpoint (str) – The authentication endpoint.
jwt_token (str) – A jwt token for authentication.
iam_endpoint (str) – IBM Cloud IAM Endpoint
org_id (str) – IBM EIS GA API Connect Org Id
tenant_id (str) – IBM EIS GA API Connect Tenant Id
legacy (bool) – IBM EIS GA Legacy Environment selector override
version (int) – IBM EIS GA api version (default: 3)

Returns:

None

Return type:

None

Raises:

Exception – if an api key cannot be acquired from the information provided

api_connect_get_auth_token(api_key=None, client_id=None, endpoint=None, verify=True, iam_endpoint=None, org_id=None, tenant_id=None)¶

The method submits a request to the authentication system and obtains a response.

Parameters:

api_key (str) – An api key for the authentication system.
client_id (str) – A client id for the authentication system.
endpoint (str) – The authentication endpoint.
verify (boolean) – Verify ssl.
iam_endpoint (str) – IBM Cloud IAM Endpoint
org_id (str) – IBM EIS GA API Connect Org Id
tenant_id (str) – IBM EIS GA API Connect Tenant Id

api_connect_refresh_auth_token(verify=True)¶: The method performs a new api_connect_get_auth_token.

eis_get_auth_token(api_key=None, client_id=None, endpoint=None, verify=True, iam_endpoint=None, org_id=None, tenant_id=None)¶

The method submits a request to the authentication system and obtains a response.

Parameters:

api_key (str) – An api key for the authentication system (in this case a non-legacy EIS key).
client_id (str) – A client id for the authentication system.
endpoint (str) – The authentication endpoint.
verify (boolean) – Verify ssl.
iam_endpoint (str) – IBM Cloud IAM Endpoint
org_id (str) – IBM EIS GA API Connect Org Id
tenant_id (str) – IBM EIS GA API Connect Tenant Id

eis_refresh_auth_token(verify=True)¶: The method performs a new eis_get_auth_token.

from_dict()¶

Create a OAuth2 authentication object from a dictionary.

Parameters:: authentication_dict (Any) – A dictionary that contains the keys of a OAuth2 object.
Return type:: ibmpairs.authentication.OAuth2
Raises:: Exception – if not a dictionary.

from_json()¶

Create an OAuth2 object from json (dictonary or str).

Parameters:: oauth2_dict (Any) – A json dictionary that contains the keys of a OAuth2 or a string representation of a json dictionary.
Return type:: ibmpairs.authentication.OAuth2
Raises:: Exception – if not a dictionary or a string.

phoenix_get_auth_token(api_key=None, client_id=None, endpoint=None, verify=True)¶

The method submits a request to the authentication system and obtains a response.

Parameters:

api_key (str) – An api key for the authentication system.
client_id (str) – A client id for the authentication system.
endpoint (str) – The authentication endpoint.

phoenix_refresh_auth_token(verify=True)¶: The method submits a request to the authentication system for a refreshed token, gets a response and updates the internal self._oauth2_return and self._jwt_token objects.

set_credentials_from_file(username, api_key_file, host)¶

The method sets the username, api_key_file, host and a resulting api_key.

Parameters:

username (str) – A username for the user.
api_key_file (str) – An file which stores the api key.
host (str) – The host to execute requests against.

to_dict()¶

Create a dictionary from the objects structure.

Return type:: dict

to_json()¶

Create a string representation of a json dictionary from the objects structure.

Return type:: string

class authentication.OAuth2Return(access_token: str = None, expires_in: int = None, token_type: str = None, refresh_token: str = None, scope: str = None, error: str = None, expiration: int = None, ims_user_id: int = None)¶

An object to represent the return provided by a Phoenix OAuth2 call.

Parameters:

access_token (str) – An access_token (JWT)
expires_in (int) – An expiration time (seconds)
token_type (str) – The token type
refresh_token (str) – A refresh token
scope (str) – The scope of the token
error (str) – An error message
expiration (int) – The expiration timestamp (UNIX)
ims_user_id (int) – IMS User Id

Raises:

Exception – if username and password are not present

from_dict()¶

Create an OAuth2Return object from a dictionary.

Parameters:: oauth2_return_dict (Any) – A dictionary that contains the keys of an OAuth2Return object.
Return type:: ibmpairs.authentication.OAuth2Return
Raises:: Exception – if not a dictionary.

from_json()¶

Create a OAuth2Return object from json (dictonary or str).

Parameters:: oauth2_return_dict (Any) – A json dictionary that contains the keys of a OAuth2Return or a string representation of a json dictionary.
Return type:: ibmpairs.authentication.OAuth2Return
Raises:: Exception – if not a dictionary or a string.

to_dict()¶

Create a dictionary from the objects structure.

Return type:: dict

to_json()¶

Create a string representation of a json dictionary from the objects structure.

Return type:: string

authentication.basic_from_dict(basic_dictionary: dict)¶

The function converts a dictionary of Basic to a Basic object.

Parameters:: basic_dict (dict) – A dictionary that contains the keys of a Basic.
Return type:: ibmpairs.authentication.Basic
Raises:: Exception – if not a dict.

authentication.basic_from_json(basic_json: Any)¶

The function converts a dictionary or json string of Basic to a Basic object.

Parameters:: basic_json (Any) – A dictionary or json string that contains the keys of a Basic.
Return type:: ibmpairs.authentication.Basic
Raises:: Exception – if not a dict or a str.

authentication.basic_to_dict(basic: Basic)¶

The function converts an object of Basic to a dict.

Parameters:: basic (ibmpairs.authentication.Basic) – A Basic object.
Return type:: dict

authentication.basic_to_json(basic: Basic)¶

The function converts an object of Basic to a json string.

Parameters:: basic (ibmpairs.authentication.Basic) – A Basic object.
Return type:: str

authentication.get_password_from_file(server, user, passFile=None)¶

Tries to obtain the PAIRS API password for a given user on a given server.

Parameters:

server (str) – PAIRS API server name, e.g. ‘pairs.res.ibm.com’
user (str) – user name for which to obtain the corresponding password
passFile (str) – path to file with password, it is expected to have the format <server>:<user>:<password>, colons in passwords need to be escaped

Returns:

corresponding password if available, None otherwise note: if either user or server is None, no password searched for, and None is returned

Return type:

str

Raises:

Exception – if password file does not exist if password was not found

authentication.oauth2_from_dict(oauth2_dictionary: dict)¶

The function converts a dictionary of OAuth2 to a OAuth2 object.

Parameters:: oauth2_dict (dict) – A dictionary that contains the keys of a OAuth2.
Return type:: ibmpairs.authentication.OAuth2
Raises:: Exception – if not a dict.

authentication.oauth2_from_json(oauth2_json: Any)¶

The function converts a dictionary or json string of OAuth2 to a OAuth2 object.

Parameters:: oauth2_json (Any) – A dictionary or json string that contains the keys of a OAuth2.
Return type:: ibmpairs.authentication.OAuth2
Raises:: Exception – if not a dict or a str.

authentication.oauth2_return_from_dict(oauth2_return_dictionary: dict)¶

The function converts a dictionary of OAuth2Return to a OAuth2Return object.

Parameters:: oauth2_return_dict (dict) – A dictionary that contains the keys of a OAuth2Return.
Return type:: ibmpairs.authentication.OAuth2Return
Raises:: Exception – if not a dict.

authentication.oauth2_return_from_json(oauth2_return_json: Any)¶

The function converts a dictionary or json string of OAuth2Return to a OAuth2Return object.

Parameters:: oauth2_return_json (Any) – A dictionary or json string that contains the keys of a OAuth2Return.
Return type:: ibmpairs.authentication.OAuth2Return
Raises:: Exception – if not a dict or a str.

authentication.oauth2_return_to_dict(oauth2_return: OAuth2Return)¶

The function converts an object of OAuth2Return to a dict.

Parameters:: oauth2_return (ibmpairs.authentication.OAuth2Return) – A OAuth2Return object.
Return type:: dict

authentication.oauth2_return_to_json(oauth2_return: OAuth2Return)¶

The function converts an object of OAuth2Return to a json string.

Parameters:: oauth2_return (ibmpairs.authentication.OAuth2Return) – A OAuth2Return object.
Return type:: str

authentication.oauth2_to_dict(oauth2: OAuth2)¶

The function converts an object of OAuth2 to a dict.

Parameters:: oauth2 (ibmpairs.authentication.OAuth2) – A OAuth2 object.
Return type:: dict

authentication.oauth2_to_json(oauth2: OAuth2)¶

The function converts an object of OAuth2 to a json string.

Parameters:: oauth2 (ibmpairs.authentication.OAuth2) – A OAuth2 object.
Return type:: str