Authentication API

Authentication API#

The authentication module provides a unified framework for authenticating with multiple cloud environments.

Configuration#

AuthConfig#

class wxdi.common.auth.auth_config.AuthConfig(environment_type: EnvironmentType, url: str | None = None, api_key: str | None = None, username: str | None = None, password: str | None = None, account_id: str | None = None, disable_ssl_verification: bool = True)#

Bases: object

Configuration for cloud environment authentication.

This class holds the configuration details needed to authenticate with different cloud environments. It provides comprehensive validation and automatic configuration based on environment type.

environment_type#

The type of environment (IBM_CLOUD, AWS_CLOUD, etc.)

url#

The authentication or API endpoint URL (optional, uses default if not provided)

api_key#

API key for authentication (optional)

username#

Username for authentication (optional)

password#

Password for authentication (optional)

account_id#

Account ID for AWS environment (optional, required for AWS_CLOUD)

disable_ssl_verification#

Whether to disable SSL verification (default: True)

Raises:

  • TypeError – If environment_type is not an EnvironmentType instance

  • ValueError – If required fields are missing for the specified environment type

Parameters:

  • environment_type (EnvironmentType)

  • url (str | None)

  • api_key (str | None)

  • username (str | None)

  • password (str | None)

  • account_id (str | None)

  • disable_ssl_verification (bool)

EnvironmentType#

class wxdi.common.auth.auth_config.EnvironmentType(*values)#

Bases: Enum

Enumeration of supported cloud environment types.

IBM_CLOUD#

IBM Cloud standard environment

AWS_CLOUD#

Amazon Web Services cloud environment

GOV_CLOUD#

Government cloud environment

ON_PREM#

On-premises installation

Authentication Provider#

AuthProvider#

class wxdi.common.auth.auth_provider.AuthProvider(config: AuthConfig)#

Bases: object

Authentication provider for different cloud environments.

This class implements a factory pattern to create and manage authenticators for various cloud environments. It provides a unified interface for token generation across different authentication mechanisms.

Authenticator mapping:

  • IBM_CLOUD: IAMAuthenticator (IBM Cloud IAM)

  • AWS_CLOUD: MCSPV2Authenticator (Multi-Cloud Service Platform V2)

  • ON_PREM: CloudPakForDataAuthenticator (Cloud Pak for Data)

  • GOV_CLOUD: GovCloudAuthenticator (Government Cloud custom implementation)

config#

The authentication configuration

authenticator#

The created authenticator instance

Example

>>> config = AuthConfig(
...     environment_type=EnvironmentType.IBM_CLOUD,
...     api_key="your-api-key"
... )
>>> provider = AuthProvider(config)
>>> token = provider.get_token()

Initialize the AuthProvider with an environment configuration.

Parameters:

config (AuthConfig) – AuthConfig instance with authentication details

Raises:

ValueError – If authenticator creation fails due to invalid configuration

get_token()#

Generate and return an authentication token.

This method validates the authenticator and retrieves a token from the token manager. The token is automatically refreshed if expired.

Returns:

The authentication token

Return type:

str

Raises:

  • ValueError – If the authenticator doesn’t have a token_manager

  • Exception – If token generation fails

Government Cloud Authenticator#

GovCloudAuthenticator#

class wxdi.common.auth.gov_cloud_authenticator.GovCloudAuthenticator(apikey: str, url: str, *, disable_ssl_verification: bool = False, headers: dict[str, str] | None = None, proxies: dict[str, str] | None = None)#

Bases: IAMRequestBasedAuthenticator

Government Cloud Authenticator.

This authenticator extends IAMRequestBasedAuthenticator and uses a custom token manager to handle Government Cloud specific authentication flows.

The authenticator manages the complete token lifecycle: - Token acquisition from Government Cloud endpoints - Automatic token refresh when expired - Token expiration handling - SSL verification control

token_manager#

The Government Cloud token manager instance

apikey#

The API key for authentication

url#

The token endpoint URL

Note

headers, proxies, and disable_ssl_verification are managed by the token_manager and can be accessed via token_manager.headers, token_manager.proxies, and token_manager.disable_ssl_verification respectively.

Example

>>> authenticator = GovCloudAuthenticator(
...     apikey="your-api-key",
...     url="https://dai.ibmforusgov.com/api/rest/mcsp/apikeys/token"
... )
>>> authenticator.validate()
>>> token = authenticator.token_manager.get_token()

Initialize the Government Cloud authenticator.

Parameters:

  • apikey (str) – Your API key for Government Cloud

  • url (str) – The token endpoint URL

  • disable_ssl_verification (bool, default: False) – Whether to disable SSL verification (default: False)

  • headers (dict[str, str] | None, default: None) – Optional headers to include in token requests

  • proxies (dict[str, str] | None, default: None) – Optional proxy configuration

Raises:

ValueError – If apikey or url is not provided

validate()#

Validate the authenticator configuration.

This method ensures that all required fields are properly set before attempting authentication.

Raises:

ValueError – If apikey or url is not specified

Return type:

None

set_headers(headers: dict[str, str])#

Set headers to be included in token requests.

Parameters:

headers (dict[str, str]) – Dictionary of headers to include

Return type:

None

set_proxies(proxies: dict[str, str])#

Set proxy configuration for token requests.

Parameters:

proxies (dict[str, str]) – Dictionary of proxy configuration

Return type:

None

set_disable_ssl_verification(status: bool = False)#

Set whether to disable SSL verification.

Parameters:

status (bool, default: False) – True to disable SSL verification, False to enable (default: False)

Return type:

None

GovCloudTokenManager#

class wxdi.common.auth.gov_cloud_token_manager.GovCloudTokenManager(apikey: str, url: str, *, disable_ssl_verification: bool = False, headers: dict[str, str] | None = None, proxies: dict[str, str] | None = None)#

Bases: JWTTokenManager

Government Cloud Token Manager.

This token manager extends JWTTokenManager to handle custom token request formats for Government Cloud authentication. It manages the complete token lifecycle including acquisition, storage, and expiration.

apikey#

The API key for authentication

headers#

Optional headers to include in requests

proxies#

Optional proxy configuration

Example

>>> manager = GovCloudTokenManager(
...     apikey="your-api-key",
...     url="https://dai.ibmforusgov.com/api/rest/mcsp/apikeys/token"
... )
>>> token = manager.get_token()

Initialize the Government Cloud token manager.

Parameters:

  • apikey (str) – The API key for authentication

  • url (str) – The token endpoint URL

  • disable_ssl_verification (bool, default: False) – Whether to disable SSL verification

  • headers (dict[str, str] | None, default: None) – Optional headers to include in requests

  • proxies (dict[str, str] | None, default: None) – Optional proxy configuration

request_token()#

Request a new token from the Government Cloud endpoint.

This method makes a POST request to the token endpoint with the API key and returns the token response. Uses form-urlencoded content type for compatibility with Government Cloud endpoints.

Returns:

The token response from the endpoint containing token and expiration info

Return type:

dict

Raises:

Exception – If the token request fails

Note

Follows the IAMTokenManager pattern by returning dict for _save_token_info().

Usage Examples#

See Authentication Guide for detailed usage examples.