Authentication#

The IBM watsonx.data intelligence SDK provides a unified authentication framework that supports multiple cloud environments. All SDK modules use the same authentication infrastructure, ensuring consistent behavior across different components.

Overview#

The authentication system consists of two main components:

AuthConfig: Type-safe configuration for authentication credentials
AuthProvider: Factory for creating environment-specific authenticators

Supported Environments#

The SDK supports four environment types:

Environment	Authenticator	Use Case
IBM_CLOUD	IAMAuthenticator	IBM Cloud standard deployments
AWS_CLOUD	MCSPV2Authenticator	AWS-hosted IBM services
GOV_CLOUD	GovCloudAuthenticator	Government cloud deployments
ON_PREM	CloudPakForDataAuthenticator	On-premises installations

Quick Start#

Basic authentication example:

from wxdi.common.auth import AuthConfig, AuthProvider, EnvironmentType

# Create configuration
config = AuthConfig(
    environment_type=EnvironmentType.IBM_CLOUD,
    api_key="your-api-key"
)

# Create provider and get token
provider = AuthProvider(config)
token = provider.get_token()

IBM Cloud Authentication#

For IBM Cloud deployments, use IAM authentication with an API key.

Configuration#

from wxdi.common.auth import AuthConfig, AuthProvider, EnvironmentType

config = AuthConfig(
    environment_type=EnvironmentType.IBM_CLOUD,
    api_key="your-ibm-cloud-api-key"
)

provider = AuthProvider(config)
token = provider.get_token()

Required Parameters:

environment_type: Must be EnvironmentType.IBM_CLOUD
api_key: Your IBM Cloud API key

Optional Parameters:

url: Custom authentication URL (defaults to https://iam.cloud.ibm.com/identity/token)
disable_ssl_verification: SSL verification control (default: True)

Obtaining an API Key#

Log in to IBM Cloud: https://cloud.ibm.com
Navigate to Manage → Access (IAM) → API keys
Click Create an IBM Cloud API key
Provide a name and description
Copy the API key (it won’t be shown again)

AWS Cloud Authentication#

For AWS-hosted IBM services, use MCSP V2 authentication.

Configuration#

from wxdi.common.auth import AuthConfig, AuthProvider, EnvironmentType

config = AuthConfig(
    environment_type=EnvironmentType.AWS_CLOUD,
    api_key="your-aws-api-key",
    account_id="your-aws-account-id"
)

provider = AuthProvider(config)
token = provider.get_token()

Required Parameters:

environment_type: Must be EnvironmentType.AWS_CLOUD
api_key: Your AWS API key
account_id: Your AWS account ID

Optional Parameters:

url: Custom authentication URL (defaults to https://account-iam.platform.saas.ibm.com)
disable_ssl_verification: SSL verification control (default: True)

Government Cloud Authentication#

For government cloud deployments with specialized security requirements.

Configuration#

from wxdi.common.auth import AuthConfig, AuthProvider, EnvironmentType

config = AuthConfig(
    environment_type=EnvironmentType.GOV_CLOUD,
    api_key="your-gov-cloud-api-key"
)

provider = AuthProvider(config)
token = provider.get_token()

Required Parameters:

environment_type: Must be EnvironmentType.GOV_CLOUD
api_key: Your Government Cloud API key

Optional Parameters:

url: Custom authentication URL (defaults to https://dai.ibmforusgov.com/api/rest/mcsp/apikeys/token)
disable_ssl_verification: SSL verification control (default: True)

On-Premises Authentication#

For on-premises Cloud Pak for Data installations.

Authentication with API Key#

from wxdi.common.auth import AuthConfig, AuthProvider, EnvironmentType

config = AuthConfig(
    environment_type=EnvironmentType.ON_PREM,
    url="https://your-cp4d-instance.example.com",
    username="your-username",
    api_key="your-cp4d-api-key"
)

provider = AuthProvider(config)
token = provider.get_token()

Authentication with Username/Password#

from wxdi.common.auth import AuthConfig, AuthProvider, EnvironmentType

config = AuthConfig(
    environment_type=EnvironmentType.ON_PREM,
    url="https://your-cp4d-instance.example.com",
    username="your-username",
    password="your-password"
)

provider = AuthProvider(config)
token = provider.get_token()

Required Parameters:

environment_type: Must be EnvironmentType.ON_PREM
url: Your Cloud Pak for Data instance URL
username: Your username
api_key OR password: One of these is required

Optional Parameters:

disable_ssl_verification: SSL verification control (default: True)

Note

The authentication path /icp4d-api/v1/authorize is automatically appended to the URL if not present.

Configuration Reference#

AuthConfig Class#

class AuthConfig#

Type-safe configuration for authentication.

Parameters:

environment_type (EnvironmentType) – The cloud environment type
url (Optional[str]) – Authentication endpoint URL (optional for most environments)
api_key (Optional[str]) – API key for authentication
username (Optional[str]) – Username (required for ON_PREM)
password (Optional[str]) – Password (alternative to api_key for ON_PREM)
account_id (Optional[str]) – Account ID (required for AWS_CLOUD)
disable_ssl_verification (bool) – Disable SSL verification

Validation:

The configuration is validated automatically on creation:

Environment type must be valid
Required fields must be present for each environment
URLs are normalized (trailing slashes removed)
Default URLs are applied when not specified

EnvironmentType Enum#

class EnvironmentType#

Enumeration of supported cloud environments.

IBM_CLOUD#: IBM Cloud standard environment

AWS_CLOUD#: Amazon Web Services cloud environment

GOV_CLOUD#: Government cloud environment

ON_PREM#: On-premises installation

AuthProvider Class#

class AuthProvider#

Factory for creating environment-specific authenticators.

Parameters:: config (AuthConfig) – Authentication configuration

get_token() → str#

Generate and return an authentication token.

Returns:

Authentication token

Return type:

str

Raises:

ValueError – If authenticator is invalid
Exception – If token generation fails

Advanced Usage#

Custom URLs for Non-Production#

For staging, development, or testing environments:

config = AuthConfig(
    environment_type=EnvironmentType.IBM_CLOUD,
    url="https://staging-iam.example.com/identity/token",
    api_key="your-api-key"
)

SSL Verification Control#

Enable SSL verification for production environments:

config = AuthConfig(
    environment_type=EnvironmentType.ON_PREM,
    url="https://your-cp4d-instance.example.com",
    username="your-username",
    api_key="your-api-key",
    disable_ssl_verification=False  # Enable SSL verification
)

Token Refresh#

Tokens are automatically refreshed when expired:

provider = AuthProvider(config)

# First call - generates new token
token1 = provider.get_token()

# Subsequent calls - reuses token if not expired
token2 = provider.get_token()

# After expiration - automatically refreshes
token3 = provider.get_token()

Error Handling#

Configuration Errors#

Handle configuration validation errors:

from wxdi.common.auth import AuthConfig, EnvironmentType

try:
    config = AuthConfig(
        environment_type=EnvironmentType.IBM_CLOUD
        # Missing api_key
    )
except ValueError as e:
    print(f"Configuration error: {e}")
    # Output: API key must be provided for ibm_cloud environment type

Authentication Errors#

Handle token generation errors:

from wxdi.common.auth import AuthProvider

try:
    provider = AuthProvider(config)
    token = provider.get_token()
except Exception as e:
    print(f"Authentication failed: {e}")
    # Handle error (retry, log, etc.)

Best Practices#

Secure Credentials

Never hardcode credentials in source code:

import os

config = AuthConfig(
    environment_type=EnvironmentType.IBM_CLOUD,
    api_key=os.environ.get("IBM_CLOUD_API_KEY")
)

Reuse AuthProvider

Create one AuthProvider instance and reuse it:

# Good - reuse provider
provider = AuthProvider(config)
token1 = provider.get_token()
token2 = provider.get_token()

# Avoid - creating multiple providers
token1 = AuthProvider(config).get_token()
token2 = AuthProvider(config).get_token()

Enable SSL in Production

Always enable SSL verification for production:

config = AuthConfig(
    environment_type=EnvironmentType.ON_PREM,
    url="https://production.example.com",
    username="user",
    api_key="key",
    disable_ssl_verification=False  # Production setting
)

Handle Errors Gracefully

Implement retry logic for transient failures:

import time

def get_token_with_retry(provider, max_retries=3):
    for attempt in range(max_retries):
        try:
            return provider.get_token()
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # Exponential backoff

Using Authentication with SDK Modules#

DQ Validator REST API Integration#

Use authentication with data quality providers:

from wxdi.common.auth import AuthConfig, AuthProvider, EnvironmentType
from wxdi.dq_validator.provider import ProviderConfig, GlossaryProvider

# Set up authentication
auth_config = AuthConfig(
    environment_type=EnvironmentType.IBM_CLOUD,
    api_key="your-api-key"
)
auth_provider = AuthProvider(auth_config)
token = auth_provider.get_token()

# Use with provider
provider_config = ProviderConfig(
    base_url="https://api.dataplatform.cloud.ibm.com",
    auth_token=token
)
glossary_provider = GlossaryProvider(provider_config)

Future Modules#

All future SDK modules will use the same authentication infrastructure:

# Authentication works the same for all modules
auth_provider = AuthProvider(config)
token = auth_provider.get_token()

# Use with any SDK module
# module_client = SomeModule(token=token)

Troubleshooting#

Common Issues#

Issue: “API key must be provided”

Ensure you’re passing the api_key parameter
Check that the API key is not empty or None

Issue: “URL must be specified for ON_PREM”

ON_PREM environment requires explicit URL
Provide the full URL to your Cloud Pak for Data instance

Issue: “Account ID must be provided for AWS_CLOUD”

AWS_CLOUD requires both api_key and account_id
Obtain account ID from your AWS administrator

Issue: SSL certificate verification failed

For development: Set disable_ssl_verification=True
For production: Ensure valid SSL certificates are installed

Next Steps#

Learn about DQ Validator module
Explore API Reference for detailed documentation
Check FAQ for common questions

Authentication

Section Contents

Authentication#

Overview#

Supported Environments#

Quick Start#

IBM Cloud Authentication#

Configuration#

Obtaining an API Key#

AWS Cloud Authentication#

Configuration#

Government Cloud Authentication#

Configuration#

On-Premises Authentication#

Authentication with API Key#

Authentication with Username/Password#

Configuration Reference#

AuthConfig Class#

EnvironmentType Enum#

AuthProvider Class#

Advanced Usage#

Custom URLs for Non-Production#

SSL Verification Control#

Token Refresh#

Error Handling#

Configuration Errors#

Authentication Errors#

Best Practices#

Using Authentication with SDK Modules#

DQ Validator REST API Integration#

Future Modules#

Troubleshooting#

Common Issues#

Next Steps#