[AAP-55305] Short circuiting claims processing if user is a super user (ansible#863)

## Description
<!-- Mandatory: Provide a clear, concise description of the changes and
their purpose -->
- What is being changed?
When running migrate service data gateway is put into a state that
prevents querying the gateway for user/object info. During JWT
authentication if the claims hash in the token doesn't match the claims
hash in the service a call from the service to the gateway to get the
claims (which then fails). With this patch, if a user has is_super_user
we will just completely skip processing the claims data which will
prevent this scenario and optimize authenticator for superusers in
general.

- Why is this change needed?
See above.

- How does this change address the issue?
Short circuits the claims processing if user is superuser.

## Type of Change
<!-- Mandatory: Check one or more boxes that apply -->
- [X] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to not work as expected)
- [ ] Documentation update
- [ ] Test update
- [ ] Refactoring (no functional changes)
- [ ] Development environment change
- [ ] Configuration change

## Self-Review Checklist
<!-- These items help ensure quality - they complement our automated CI
checks -->
- [X] I have performed a self-review of my code
- [X] I have added relevant comments to complex code sections
- [X] I have updated documentation where needed
- [X] I have considered the security impact of these changes
- [X] I have considered performance implications
- [X] I have thought about error handling and edge cases
- [X] I have tested the changes in my local environment

## Testing Instructions
<!-- Optional for test-only changes. Mandatory for all other changes -->
<!-- Must be detailed enough for reviewers to reproduce -->
### Prerequisites
<!-- List any specific setup required -->

### Steps to Test
1. 
2. 
3. 

### Expected Results
<!-- Describe what should happen after following the steps -->

## Additional Context
<!-- Optional but helpful information -->

### Required Actions
<!-- Check if changes require work in other areas -->
<!-- Remove section if no external actions needed -->
- [ ] Requires documentation updates
  <!-- API docs, feature docs, deployment guides -->
- [ ] Requires downstream repository changes
  <!-- Specify repos: django-ansible-base, eda-server, etc. -->
- [ ] Requires infrastructure/deployment changes
  <!-- CI/CD, installer updates, new services -->
- [ ] Requires coordination with other teams
  <!-- UI team, platform services, infrastructure -->
- [ ] Blocked by PR/MR: #XXX
  <!-- Reference blocking PRs/MRs with brief context -->

### Screenshots/Logs
<!-- Add if relevant to demonstrate the changes -->

---------

Co-authored-by: Seth Foster <[email protected]>
Co-authored-by: Claude <[email protected]>

Author: 3 people

ansible_base/jwt_consumer/common/auth.py

@@ -23,6 +23,23 @@
 logger = logging.getLogger("ansible_base.jwt_consumer.common.auth")
 
 
+class GatewayLockedException(Exception):
+    """
+    Exception raised when the gateway is locked (returns 423 status).
+    This typically happens when migrations are in progress.
+    """
+
+    pass
+
+
+class InvalidGatewayResponseException(Exception):
+    """
+    Exception raised when the gateway response is not 200 or 423
+    """
+
+    pass
+
+
 # These fields are used to both map the user as well as to validate the JWT token
 default_mapped_user_fields = [
     "username",
@@ -272,9 +289,8 @@ def process_rbac_permissions(self):
 
         # Claims hash mismatch - fetch from gateway
         logger.info(f"Claims hash mismatch for user {user_ansible_id}. JWT: {jwt_claims_hash}, Local: {local_claims_hash}. Fetching from gateway.")
-        gateway_claims = self._fetch_jwt_claims_from_gateway(user_ansible_id)
-
-        if gateway_claims:
+        try:
+            gateway_claims = self._fetch_jwt_claims_from_gateway(user_ansible_id)
             # Extract claims structure from gateway response
             objects = gateway_claims.get('objects', {})
             object_roles = gateway_claims.get('object_roles', {})
@@ -285,32 +301,34 @@ def process_rbac_permissions(self):
 
             # Update cache with the new hash
             self.cache.cache_claims_hash(user_ansible_id, jwt_claims_hash)
-        else:
+        except GatewayLockedException:
+            if self.token.get('user_data', {}).get("is_superuser", False) is False:
+                self.log_and_raise(
+                    _("User %(user_ansible_id)s is not a superuser and gateway is locked, denying access!"), {"user_ansible_id": user_ansible_id}
+                )
+        except Exception as e:
             self.log_and_raise(
-                _("Unable to validate user permissions - gateway claims fetch failed for user %(user_ansible_id)s"), {"user_ansible_id": user_ansible_id}
+                _("Unable to validate user permissions - gateway claims fetch or processing failed for user %(user_ansible_id)s: %(e)s"),
+                {"user_ansible_id": user_ansible_id, "e": e},
             )
 
     def _fetch_jwt_claims_from_gateway(self, user_ansible_id: str) -> Optional[dict]:
         """
         Fetch JWT claims from the gateway endpoint using resource server client
         """
-        try:
-            # Use the resource server client to make the request
-            client = get_resource_server_client(service_path="api/gateway/v1")
-
-            logger.debug(f"Fetching claims from gateway for user {user_ansible_id}")
-            response = client._make_request("GET", f"jwt_claims/{user_ansible_id}/")
+        # Use the resource server client to make the request
+        client = get_resource_server_client(service_path="api/gateway/v1")
 
-            if response.status_code == 200:
-                claims_data = response.json()
-                return claims_data
-            else:
-                logger.error(f"Gateway request failed with status {response.status_code}")
-                return None
+        logger.debug(f"Fetching claims from gateway for user {user_ansible_id}")
+        response = client._make_request("GET", f"jwt_claims/{user_ansible_id}/")
 
-        except Exception as e:
-            logger.error(f"Error fetching claims from gateway: {e}")
-            return None
+        if response.status_code == 200:
+            claims_data = response.json()
+            return claims_data
+        elif response.status_code == 423:
+            raise GatewayLockedException("Gateway is locked")
+        else:
+            raise InvalidGatewayResponseException(f"Gateway request failed with status {response.status_code}")
 
 
 class JWTAuthentication(BaseAuthentication):

test_app/tests/jwt_consumer/common/test_auth.py

@@ -537,6 +537,60 @@ def test_process_rbac_permissions_cache_scenarios(
             else:
                 mock_apply.assert_not_called()
 
+    @pytest.mark.django_db
+    @pytest.mark.parametrize(
+        "is_superuser_value,should_allow",
+        [
+            (True, True),  # Superuser should be allowed when gateway is locked
+            (False, False),  # Non-superuser should be denied when gateway is locked
+        ],
+    )
+    def test_process_rbac_permissions_gateway_locked(self, admin_user, is_superuser_value, should_allow):
+        """Test process_rbac_permissions handles GatewayLockedException based on superuser status"""
+        from ansible_base.jwt_consumer.common.auth import GatewayLockedException
+
+        authentication = JWTCommonAuth()
+        authentication.user = admin_user
+        authentication.token = {"sub": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "claims_hash": "a1b2c3d4", "user_data": {"is_superuser": is_superuser_value}}
+
+        with (
+            mock.patch.object(authentication.cache, 'get_cached_claims_hash') as mock_get_cache,
+            mock.patch.object(authentication, '_fetch_jwt_claims_from_gateway') as mock_gateway,
+        ):
+            # Setup mocks - cache miss to trigger gateway call
+            mock_get_cache.return_value = None
+            mock_gateway.side_effect = GatewayLockedException("Gateway is locked")
+
+            if should_allow:
+                # Superuser should be allowed - no exception raised
+                authentication.process_rbac_permissions()
+            else:
+                # Non-superuser should be denied
+                with pytest.raises(Exception) as exc_info:
+                    authentication.process_rbac_permissions()
+                assert "not a superuser and gateway is locked" in str(exc_info.value)
+
+    @pytest.mark.django_db
+    def test_process_rbac_permissions_gateway_fetch_exception(self, admin_user):
+        """Test process_rbac_permissions handles generic exceptions from gateway fetch"""
+        authentication = JWTCommonAuth()
+        authentication.user = admin_user
+        authentication.token = {"sub": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "claims_hash": "a1b2c3d4", "user_data": {"is_superuser": False}}
+
+        with (
+            mock.patch.object(authentication.cache, 'get_cached_claims_hash') as mock_get_cache,
+            mock.patch.object(authentication, '_fetch_jwt_claims_from_gateway') as mock_gateway,
+        ):
+            # Setup mocks - cache miss to trigger gateway call
+            mock_get_cache.return_value = None
+            mock_gateway.side_effect = Exception("Network error")
+
+            # Should raise an exception with the error details
+            with pytest.raises(Exception) as exc_info:
+                authentication.process_rbac_permissions()
+            assert "unable to validate user permissions" in str(exc_info.value).lower()
+            assert "network error" in str(exc_info.value).lower()
+
     @pytest.mark.django_db
     def test_process_rbac_permissions_missing_token_data(self):
         """Test process_rbac_permissions with missing required token data"""
@@ -758,6 +812,7 @@ def test__fetch_jwt_claims_from_gateway_success(self):
     def test__fetch_jwt_claims_from_gateway_non_200(self):
         authentication = JWTCommonAuth()
         user_ansible_id = '12345678-1234-5678-9abc-123456789012'
+        from ansible_base.jwt_consumer.common.auth import InvalidGatewayResponseException
 
         with mock.patch('ansible_base.jwt_consumer.common.auth.get_resource_server_client') as mock_get_client:
             mock_client = mock.Mock()
@@ -766,18 +821,38 @@ def test__fetch_jwt_claims_from_gateway_non_200(self):
             mock_client._make_request.return_value = mock_response
             mock_get_client.return_value = mock_client
 
-            result = authentication._fetch_jwt_claims_from_gateway(user_ansible_id)
-
-            assert result is None
+            # Should raise InvalidGatewayResponseException for non-200/423 status codes
+            with pytest.raises(InvalidGatewayResponseException) as exc_info:
+                authentication._fetch_jwt_claims_from_gateway(user_ansible_id)
+            assert "gateway request failed with status 404" in str(exc_info.value).lower()
             mock_get_client.assert_called_once_with(service_path='api/gateway/v1')
             mock_client._make_request.assert_called_once_with('GET', f'jwt_claims/{user_ansible_id}/')
 
-    def test__fetch_jwt_claims_from_gateway_exception(self):
+    def test__fetch_jwt_claims_from_gateway_423_locked(self):
         authentication = JWTCommonAuth()
         user_ansible_id = '12345678-1234-5678-9abc-123456789012'
+        from ansible_base.jwt_consumer.common.auth import GatewayLockedException
 
-        with mock.patch('ansible_base.jwt_consumer.common.auth.get_resource_server_client', side_effect=Exception('boom')) as mock_get_client:
-            result = authentication._fetch_jwt_claims_from_gateway(user_ansible_id)
+        with mock.patch('ansible_base.jwt_consumer.common.auth.get_resource_server_client') as mock_get_client:
+            mock_client = mock.Mock()
+            mock_response = mock.Mock()
+            mock_response.status_code = 423
+            mock_client._make_request.return_value = mock_response
+            mock_get_client.return_value = mock_client
 
-            assert result is None
+            # Should raise GatewayLockedException for 423 status
+            with pytest.raises(GatewayLockedException) as exc_info:
+                authentication._fetch_jwt_claims_from_gateway(user_ansible_id)
+            assert "gateway is locked" in str(exc_info.value).lower()
             mock_get_client.assert_called_once_with(service_path='api/gateway/v1')
+            mock_client._make_request.assert_called_once_with('GET', f'jwt_claims/{user_ansible_id}/')
+
+    def test__fetch_jwt_claims_from_gateway_exception(self):
+        authentication = JWTCommonAuth()
+        user_ansible_id = '12345678-1234-5678-9abc-123456789012'
+
+        with mock.patch('ansible_base.jwt_consumer.common.auth.get_resource_server_client', side_effect=Exception('boom')):
+            # Should re-raise the exception
+            with pytest.raises(Exception) as exc_info:
+                authentication._fetch_jwt_claims_from_gateway(user_ansible_id)
+            assert "boom" in str(exc_info.value)