Add support for AWS named profiles in settings.py

This update introduces the ability to use AWS named profiles via the `AWS_IAM_PROFILE` setting. Additionally, documentation and tests have been updated to reflect the new functionality and ensure proper configuration and behavior. The version is incremented to 1.3.0 to reflect this enhancement.

Author: StevenMapes

CHANGELOG.md

@@ -1,4 +1,8 @@
-# 1.2`0 - 12th May 2025
+# 1.3.0 - 26th May 2025
+- Added in support for AWS Profiles
+- Updated the documentation to include examples of how to configure settings.py
+
+# 1.2.1 - 12th May 2025
 - 1.2.0 was built using an older version so the package had the wrong name, it's been yanked, so use 1.2.1 instead
 
 # 1.2.0 - 12th May 2025 - yanked

README.md

@@ -51,6 +51,37 @@ pip install django-aws-api-gateway-websockets
 ## settings.py
 Add ```django_aws_api_gateway_websockets``` into ```INSTALLED_APPS``` 
 
+### Decide on AWS Credential Setup
+This package supports differing ways to connect to AWS, depending on the option you require depends on which settings
+you will need to define.
+
+#### Using the IAM role of the instance
+If you are running this package on an EC2 Instance that has an IAM profile then you only need to specifc the region to
+connect to by setting the ```AWS_REGION_NAME``` in ```settings.py```.
+
+E.G. ```AWS_REGION_NAME="eu-west-1"``` will mean this package will connect to the Ireland region using the IAM profile
+of the machine
+
+#### Named Profiles (AWS_IAM_PROFILE) 
+You can use a named profile by setting ```AWS_IAM_PROFILE``` to the name of the profile on your computer.
+
+E.G ```AWS_IAM_PROFILE="example"```. As the profile contains the region you do not need to set anything else.
+
+**NOTE:** If you are using ```Django-Storages``` you may already have set the value against ```AWS_S3_SESSION_PROFILE```
+
+#### Using AWS IAM Access Key and Secret
+Alternatively you can specify the exact  ACCESS_KEY, SECRET_ACCESS_KEY and REGION_NAME you wish to use by setting the
+three following ```settings.py``` values.
+
+```
+AWS_ACCESS_KEY_ID="My-Key-Here"
+AWS_SECRET_ACCESS_KEY="My-Secret-Key-Here"
+AWS_REGION_NAME="region-to-use"
+```
+
+The order above is the recommended order to use. As with all custom Django settings it's advisable to store the real
+values in either a secrets manager or environmental values. I tend to use https://pypi.org/project/python-decouple/
+
 ### IMPORTANT
 If your site is **not** already running cross-origin you will need to update some settings and flush the sessions to ensure the primary domain and subdomain will work.
 

django_aws_api_gateway_websockets/models.py

@@ -9,17 +9,25 @@
 def get_boto3_client(service: str = "apigatewayv2", **kwargs):
     """Returns the boto3 client to use.
 
-    :param str servivce: apigatewayv2 | apigatewaymanagementapi
+    When running within AWS, if you are using an IAM Role with the service, E.G. on an EC2 instance, you need to
+    set AWS_REGION_NAME within settings.py
 
-    If you are using an IAM Role then you just need to set AWS_REGION_NAME within settings.py otherwise you need to
-    set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY as well with the correct values
+    Otherwise you can either use a named profile using settings.AWS_IAM_PROFILE or you can set the credentials
+    using both AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
+
+    :param str service: apigatewayv2 | apigatewaymanagementapi
     """
-    if (
+    if hasattr(settings, "AWS_IAM_PROFILE") and settings.AWS_IAM_PROFILE:
+        # Used a named profile where credentials are stored within .aws folder
+        session = boto3.Session(profile_name=settings.AWS_IAM_PROFILE)
+        client = session.client(service)
+    elif (
         hasattr(settings, "AWS_ACCESS_KEY_ID")
         and settings.AWS_ACCESS_KEY_ID
         and hasattr(settings, "AWS_SECRET_ACCESS_KEY")
         and settings.AWS_SECRET_ACCESS_KEY
     ):
+        # Use specific access and secret keys
         if not hasattr(settings, "AWS_REGION_NAME") or not settings.AWS_REGION_NAME:
             raise RuntimeError("AWS_REGION_NAME must be set within settings.py")
 
@@ -31,6 +39,7 @@ def get_boto3_client(service: str = "apigatewayv2", **kwargs):
             **kwargs,
         )
     else:
+        # Use the IAM Role of the machine
         if not hasattr(settings, "AWS_REGION_NAME") or not settings.AWS_REGION_NAME:
             raise RuntimeError("AWS_REGION_NAME must be set within settings.py")
         client = boto3.client(service, region_name=settings.AWS_REGION_NAME, **kwargs)

pyproject.toml

@@ -9,7 +9,7 @@ skip = [
 
 [project]
 name = "django-aws-api-gateway-websockets"
-version = "1.2.1"
+version = "1.3.0"
 authors = [
   { name="Steven Mapes", email="steve@stevenmapes.com" },
 ]

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = django-aws-api-gateway-websockets
-version = 1.2.1
+version = 1.3.0
 description = Created to allow Django projects to be used as a HTTP backend for AWS API Gateway websockets
 long_description = file: README.md
 long_description_content_type = text/markdown

tests/test_models.py

@@ -14,30 +14,42 @@
 
 
 class GetBoto3ClientTestCase(SimpleTestCase):
+
     @override_settings(
-        AWS_IAM_PROFILE="FakeIAMProfile",
+        AWS_IAM_PROFILE=None,
         AWS_ACCESS_KEY_ID=None,
         AWS_SECRET_ACCESS_KEY=None,
-        AWS_REGION_NAME=None,
+        AWS_REGION_NAME="",
     )
     @patch("django_aws_api_gateway_websockets.models.boto3")
-    def test_exception_raised_if_no_credentials_other_than_aws_iam_profile(
-        self, mock_boto3
-    ):
-        """Named profiles are not supported yet by this package. In theory they may be the preferred method for
-         local and non-AWS hosted deployments.
-
-         todo - I will add support in later
+    def test_region_is_required_to_use_machine_iam(self, mock_boto3):
+        """Test what happens when there are not enough credentials
 
         :param MagicMock mock_boto3:
         :return:
         """
-        with self.assertRaises(RuntimeError) as e:
+        with self.assertRaises(RuntimeError) as re:
             get_boto3_client("s3")
+            self.assertEqual("AWS_REGION_NAME must be set within settings.py", str(re))
 
-        self.assertEqual(
-            str(e.exception), "AWS_REGION_NAME must be set within settings.py"
-        )
+    @override_settings(
+        AWS_IAM_PROFILE="FakeIAMProfile",
+        AWS_ACCESS_KEY_ID=None,
+        AWS_SECRET_ACCESS_KEY=None,
+        AWS_REGION_NAME=None,
+    )
+    @patch("django_aws_api_gateway_websockets.models.boto3")
+    def test_boto3_connection_support_named_profiles(self, mock_boto3):
+        """Named profiles are supported via the settings.py variable AWS_IAM_PROFILE.
+
+        :param MagicMock mock_boto3:
+        :return:
+        """
+        service = "s3"
+        res = get_boto3_client(service)
+        mock_boto3.Session.assert_called_with(profile_name=settings.AWS_IAM_PROFILE)
+        mock_boto3.Session.return_value.client.assert_called_with(service)
+        self.assertEqual(res, mock_boto3.Session.return_value.client.return_value)
 
     @override_settings(
         AWS_ACCESS_KEY_ID=None,