Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,11 @@
Changelog
=========

Unreleased
-------------------
- Added support for connecting as the database user mapped to the caller's IAM identity (e.g. `IAMR:<role>` users) on provisioned clusters: when IAM authentication is used without `db_user`, the driver now calls `GetClusterCredentialsWithIAM` instead of failing. [#255](https://github.com/aws/amazon-redshift-python-driver/issues/255)


v2.2.0 (2026-10-09)
-------------------
- Behavior change: Changed the default value of sslmode from verify-ca to verify-full. In addition to validating the certificate chain, the driver now checks that the server certificate matches the host name it connected to. If sslmode is not set and the host name doesn't match, the driver logs a warning and still connects, so existing connections keep working while you migrate. If sslmode=verify-full is set explicitly, a mismatch still fails the connection. A future release will fail the connection on a mismatch in both cases.
Expand Down
21 changes: 21 additions & 0 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -225,6 +225,27 @@ Alternatively, IAM credentials can be supplied directly to ``connect(...)`` usin
region="us-east-2"
)

Example connecting as the database user mapped to your IAM identity (IAM role / ``IAMR:`` users)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When ``db_user`` is provided, the driver calls ``GetClusterCredentials`` and connects as ``IAM:<db_user>``.
To connect as the database user that maps to the calling IAM identity instead (``IAM:<user>`` for an IAM user,
``IAMR:<role>`` for an assumed IAM role, e.g. a user created with ``CREATE USER "IAMR:my_role" PASSWORD DISABLE;``),
omit ``db_user``. The driver then calls ``GetClusterCredentialsWithIAM`` (requires ``boto3>=1.24.5``).
Setting ``group_federation=True`` has the same effect.

.. code-block:: python

import redshift_connector

# Connects as "IAMR:my_role" when the profile assumes the IAM role "my_role"
conn = redshift_connector.connect(
iam=True,
database='dev',
cluster_identifier='examplecluster',
profile='my_role_profile',
region='us-east-2'
)

Example using IdpTokenAuthPlugin with Default Credentials
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When using Identity Center (IdC) authentication, the ``IdpTokenAuthPlugin`` can automatically resolve
Expand Down
19 changes: 18 additions & 1 deletion redshift_connector/iam_helper.py
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,19 @@ def get_cluster_credentials_api_type(
if not info._is_serverless:
_logger.debug("Redshift provisioned")
if not info.group_federation:
if (
(info.db_user is None or info.db_user == "")
and provider_type != IamHelper.IAMAuthenticationType.PLUGIN
and IamHelper.GetClusterCredentialsAPIType.can_support_v2(provider_type)
):
# No db_user was provided, so GetClusterCredentials (V1) cannot be used. Fall back to
# GetClusterCredentialsWithIAM (V2), which derives the database user from the calling
# IAM identity: "IAM:<user>" for an IAM user, "IAMR:<role>" for an assumed IAM role.
_logger.debug(
"Provisioned cluster, no db_user provided: GetClusterCredentialsAPIType.IAM_V2 "
"(database user derived from IAM identity)"
)
return IamHelper.GetClusterCredentialsAPIType.IAM_V2
_logger.debug("Provisioned cluster GetClusterCredentialsAPIType.IAM_V1")
return IamHelper.GetClusterCredentialsAPIType.IAM_V1
elif IamHelper.GetClusterCredentialsAPIType.can_support_v2(provider_type):
Expand Down Expand Up @@ -506,7 +519,11 @@ def set_cluster_credentials(

else:
if info.db_user is None or info.db_user == "":
raise InterfaceError("Connection parameter db_user must be specified when using IAM authentication")
raise InterfaceError(
"Connection parameter db_user must be specified when using IAM authentication. "
"To connect as the database user mapped to your IAM identity (e.g. an IAMR:<role> user), "
"set group_federation=True (requires boto3 >= 1.24.5)."
)
# https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/redshift/client/get_cluster_credentials.html
request_params = {
"DbUser": info.db_user,
Expand Down
79 changes: 79 additions & 0 deletions test/unit/test_iam_helper.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@

import pytest # type: ignore
from dateutil.tz import tzutc
from packaging.version import Version
from pytest_mock import mocker # type: ignore

from redshift_connector import InterfaceError, ProgrammingError, RedshiftProperty
Expand Down Expand Up @@ -872,6 +873,84 @@ def test_get_cluster_credentials_api_type_will_use_correct_api(conn_params, prov
IamHelper.get_cluster_credentials_api_type(info, provider)


@pytest.mark.parametrize(
"conn_params, provider, exp_result",
(
# db_user provided -> keep legacy GetClusterCredentials (IAM:<db_user>)
(
{"db_user": "awsuser"},
IamHelper.IAMAuthenticationType.PROFILE,
IamHelper.GetClusterCredentialsAPIType.IAM_V1,
),
(
{"db_user": "awsuser"},
IamHelper.IAMAuthenticationType.IAM_KEYS,
IamHelper.GetClusterCredentialsAPIType.IAM_V1,
),
# no db_user -> GetClusterCredentialsWithIAM, user derived from IAM identity (IAM:<user> / IAMR:<role>)
({}, IamHelper.IAMAuthenticationType.PROFILE, IamHelper.GetClusterCredentialsAPIType.IAM_V2),
({"db_user": ""}, IamHelper.IAMAuthenticationType.PROFILE, IamHelper.GetClusterCredentialsAPIType.IAM_V2),
({}, IamHelper.IAMAuthenticationType.IAM_KEYS, IamHelper.GetClusterCredentialsAPIType.IAM_V2),
({}, IamHelper.IAMAuthenticationType.IAM_KEYS_WITH_SESSION, IamHelper.GetClusterCredentialsAPIType.IAM_V2),
# plugins keep the legacy behavior
({}, IamHelper.IAMAuthenticationType.PLUGIN, IamHelper.GetClusterCredentialsAPIType.IAM_V1),
# serverless is unaffected
(
{"is_serverless": True},
IamHelper.IAMAuthenticationType.PROFILE,
IamHelper.GetClusterCredentialsAPIType.SERVERLESS_V1,
),
),
)
def test_get_cluster_credentials_api_type_without_db_user_uses_iam_identity(conn_params, provider, exp_result) -> None:
info = RedshiftProperty()
for k, v in conn_params.items():
info.put(k, v)
assert IamHelper.get_cluster_credentials_api_type(info, provider) == exp_result


@pytest.mark.parametrize("boto3_version", ("1.17.110", "1.24.4"))
def test_get_cluster_credentials_api_type_without_db_user_old_boto3_uses_v1(mocker, boto3_version) -> None:
mocker.patch(
"redshift_connector.idp_auth_helper.IdpAuthHelper.get_pkg_version", return_value=Version(boto3_version)
)
info = RedshiftProperty()
assert (
IamHelper.get_cluster_credentials_api_type(info, IamHelper.IAMAuthenticationType.PROFILE)
== IamHelper.GetClusterCredentialsAPIType.IAM_V1
)


@mock.patch("boto3.client.get_cluster_credentials_with_iam")
@mock.patch("boto3.client")
def test_set_cluster_credentials_iamr_user_without_db_user(mock_boto_client, mock_get_creds_with_iam, mocker) -> None:
mocker.patch(
"redshift_connector.iam_helper.IamHelper.get_authentication_type",
return_value=IamHelper.IAMAuthenticationType.PROFILE,
)
mock_cred_provider = MagicMock()
mock_cred_provider.get_cache_key.return_value = "mocked"
mock_cred_holder = MagicMock()
mock_cred_holder.has_associated_session = False
mock_cred_provider.get_credentials.return_value = mock_cred_holder

rp: RedshiftProperty = make_redshift_property()
rp.db_user = None
rp.iam_disable_cache = True
mock_boto_client.return_value.get_cluster_credentials_with_iam.return_value = {
"DbUser": "IAMR:my_role",
"DbPassword": "secret",
"Expiration": datetime.datetime(9999, 1, 1, tzinfo=tzutc()),
}

IamHelper.set_cluster_credentials(mock_cred_provider, rp)

mock_boto_client.return_value.get_cluster_credentials.assert_not_called()
mock_boto_client.return_value.get_cluster_credentials_with_iam.assert_called_once()
assert rp.user_name == "IAMR:my_role"
assert rp.password == "secret"


@pytest.mark.parametrize(
"boto3_version,connection_args",
(
Expand Down