Skip to content

Authentication Module

Overview

The authentication module provides OAuth2-based authentication functionality for the Strata Cloud Manager (SCM) API. It handles token management, including acquisition, validation, refresh, and JWT token operations, with robust error handling and retry mechanisms.

Core Components

OAuth2Client

The main class that handles OAuth2 authentication with Palo Alto Networks' services.

class OAuth2Client:
def __init__(self, auth_request: AuthRequestModel)

Configuration Constants

  • MAX_RETRIES: Maximum number of retry attempts (default: 3)
  • RETRY_BACKOFF: Backoff factor for retries (default: 0.3)
  • TOKEN_EXPIRY_BUFFER: Buffer time before token expiry in seconds (default: 300)

Attributes

  • auth_request: Authentication parameters container
  • session: Authenticated OAuth2 session
  • signing_key: Key used for JWT token verification

Authentication Flow

Session Creation

The client establishes an authenticated session using the following steps:

  1. Creates a BackendApplicationClient with the provided client ID
  2. Configures retry strategy for resilient connections
  3. Fetches initial OAuth2 token
  4. Sets up HTTP adapters with retry logic
auth_client = OAuth2Client(
AuthRequestModel(
client_id="your_client_id",
client_secret="your_client_secret",
token_url="https://auth.example.com/token",
scope="your_scope",
tsg_id="your_tsg_id"
)
)

Retry Strategy

The client implements a robust retry mechanism for handling transient failures:

  • Retries on status codes: 408, 429, 500, 502, 503, 504
  • Supports retries on both POST and GET methods
  • Uses exponential backoff
  • Configurable maximum retry attempts
retry_strategy = Retry(
total=3,
backoff_factor=0.3,
status_forcelist=[408, 429, 500, 502, 503, 504],
allowed_methods=["POST", "GET"]
)

Token Management

Token Validation

The client provides several methods for token validation and management:

Token Expiration Check

# Check if token will expire soonif auth_client.token_expires_soon:
auth_client.refresh_token()
# Check if token has already expiredif auth_client.is_expired:
auth_client.refresh_token()

Token Decoding

# Decode token to access payloadtry:
payload = auth_client.decode_token()
except ExpiredSignatureError:
# Handle expired token
auth_client.refresh_token()

Token Refresh

The client handles automatic token refresh with the following features:

  • Creates new session for refresh requests to avoid stale state
  • Implements retry logic for resilient token refresh
  • Updates signing key after successful refresh
  • Comprehensive error handling
try:
auth_client.refresh_token()
except APIError as e:
# Handle refresh failure
logger.error(f"Token refresh failed: {e}")

Error Handling

The module implements comprehensive error handling for various scenarios:

Network Errors

  • Connection errors
  • Timeout errors
  • Request exceptions

Authentication Errors

  • Token expiration
  • Invalid credentials
  • JWT decode errors
  • Signing key retrieval failures

HTTP Errors

  • Server errors (5xx)
  • Client errors (4xx)
  • Gateway timeouts

Example error handling:

try:
auth_client = OAuth2Client(auth_request)
except APIError as e:
if "Network error" in str(e):
# Handle network-related errors
logger.error(f"Network error: {e}")
elif "HTTP error" in str(e):
# Handle HTTP-related errors
logger.error(f"HTTP error: {e}")
else:
# Handle other API errors
logger.error(f"Authentication error: {e}")

Security Features

The client implements several security best practices:

  1. JWT Token Verification

    • Uses RS256 algorithm for token verification
    • Validates token audience
    • Verifies token signature using JWK

  2. SSL/TLS Security

    • Enforces SSL verification
    • Uses secure token endpoints

  3. Token Expiration Management

    • Implements buffer time before expiration
    • Automatic token refresh
    • Validates token expiration

Logging

The module includes comprehensive logging for troubleshooting:

  • Debug-level logs for token operations
  • Error-level logs for failures
  • Detailed error messages for exceptional cases
# Configure logginglogger = setup_logger(__name__)
# Logs will include:# - Token fetch operations# - Refresh attempts# - Error conditions# - Network issues

Dependencies

The module requires the following external libraries:

  • jwt: For JWT token operations
  • oauthlib: For OAuth2 implementation
  • requests: For HTTP operations
  • requests_oauthlib: For OAuth2 session management

Best Practices

  1. Token Management

    • Always check token expiration before making API calls
    • Implement proper error handling for token refresh
    • Use the token expiry buffer to prevent last-minute expiration

  2. Error Handling

    • Catch specific exceptions for different error scenarios
    • Implement proper logging for troubleshooting
    • Use retry mechanisms for transient failures

  3. Security

    • Store credentials securely
    • Use environment variables for sensitive information
    • Implement proper token validation