Cassandra SigV4 Auth Plugin

4.0.2 verified Mon Apr 27 auth: no python

Implements a SigV4 authentication plugin for the open-source DataStax Python Driver for Apache Cassandra, enabling connections to Amazon Keyspaces or other Cassandra clusters that require IAM-based authentication. Current version 4.0.2, release cadence is intermittent.

pip install cassandra-sigv4

Common errors

error cassandra.cluster.NoHostAvailable: ('Unable to connect to any servers', {'<host>:9142': ConnectionException('Failed to connect')}) ↓

cause SSL context not enabled or incorrect port. Amazon Keyspaces requires SSL on port 9142.

fix

Set ssl_context=True and port=9142 in Cluster constructor.

error AttributeError: module 'cassandra_sigv4' has no attribute 'SigV4AuthProvider' ↓

cause Import path changed in version 4.0.0. The class moved to a submodule.

fix

Use 'from cassandra_sigv4.auth import SigV4AuthProvider' instead of 'from cassandra_sigv4 import SigV4AuthProvider'.

error TypeError: __init__() missing 1 required keyword-only argument: 'boto_session' ↓

cause SigV4AuthProvider requires boto_session or other parameters (like credentials) in newer versions.

fix

Pass a boto3.Session object: SigV4AuthProvider(boto_session=boto3.Session())

error boto3.exceptions.NoRegionError: You must specify a region. ↓

cause No AWS region configured. The plugin needs a region from environment, boto session, or hostname.

fix

Set AWS_DEFAULT_REGION environment variable, or create boto3 session with region_name='us-east-1'.

Warnings

gotcha The auth_provider must be passed to the Cluster constructor, not set via session or after connection. ↓

fix Set auth_provider in Cluster(...) call, not after.

breaking In version 4.0.0, the import path changed. The class SigV4AuthProvider is no longer importable from the top-level package; use from cassandra_sigv4.auth import SigV4AuthProvider. ↓

fix Update imports to from cassandra_sigv4.auth import SigV4AuthProvider.

gotcha The plugin requires Python 2.7 or 3.x (requires_python >=2.7, <4). It has been tested primarily with Python 3.6+. Older Python 2.7 usage may have compatibility issues with newer versions of cassandra-driver. ↓

fix Use Python 3.6+ and ensure cassandra-driver version is compatible.

gotcha The region must be set either via boto3 session, environment variable AWS_DEFAULT_REGION, or the keyspace endpoint hostname. Missing region will cause authentication failure. ↓

fix Set AWS_DEFAULT_REGION or pass a boto3 session with explicit region.

Imports

SigV4AuthProvider
wrong
```
from cassandra_sigv4 import SigV4AuthProvider
```
correct
```
from cassandra_sigv4.auth import SigV4AuthProvider
```
In older versions the symbol was at package level, but since 4.0.0 it moved to a submodule. The old import will raise ImportError.
boto3
```
import boto3
```

Quickstart

Connects to Amazon Keyspaces using SigV4 authentication. Ensure AWS credentials are available via environment, IAM role, or boto3 session.

import boto3
from cassandra.cluster import Cluster
from cassandra_sigv4.auth import SigV4AuthProvider

# AWS credentials (region is required; credentials from env or boto3 session)
boto_session = boto3.Session()
auth_provider = SigV4AuthProvider(boto_session=boto_session)

cluster = Cluster(
    ['cassandra.<region>.amazonaws.com'],
    port=9142,
    ssl_context=True,
    auth_provider=auth_provider
)
session = cluster.connect()
row = session.execute('SELECT keyspace_name FROM system_schema.keyspaces').one()
print(row)  # Expected: first keyspace
session.shutdown()
cluster.shutdown()