Merge pull request #9 from coreweave/scim-shadow

feat: Add shadow map support to SCIM source and update documentation

Author: git-it127

examples/nsscache-scim.conf

@@ -9,7 +9,7 @@ source = scim
 cache = files
 
 # NSS maps to be cached
-maps = passwd, group, sshkey
+maps = passwd, group, shadow, sshkey
 
 # Directory where cache files will be stored
 files_dir = /tmp/nsscache
@@ -75,6 +75,19 @@ scim_override_home_directory = /mnt/home/%%u
 scim_path_username = urn:example:params:scim:schemas:extension:User/userName
 scim_path_ssh_keys = urn:example:params:scim:schemas:extension:User/sshKeys
 
+[shadow]
+
+scim_path_username = urn:example:params:scim:schemas:extension:User/userName
+
+# Optional shadow field defaults (all default to empty string if not specified)
+# scim_shadow_default_lstchg =       # Last password change (days since Jan 1, 1970)
+# scim_shadow_default_min =          # Minimum password age (days)
+# scim_shadow_default_max = 99999    # Maximum password age (days)
+# scim_shadow_default_warn = 7       # Password warning period (days)
+# scim_shadow_default_inact =        # Password inactivity period (days)
+# scim_shadow_default_expire =       # Account expiration date (days since Jan 1, 1970)
+# scim_shadow_default_flag =         # Reserved field
+
 [group]
 
 scim_path_username = urn:example:params:scim:schemas:extension:User/userName

nss_cache/sources/scimsource.py

@@ -10,6 +10,7 @@
 from nss_cache import error
 from nss_cache.maps import group
 from nss_cache.maps import passwd
+from nss_cache.maps import shadow
 from nss_cache.maps import sshkey
 from nss_cache.sources import source
 from nss_cache.sources.httpsource import UpdateGetter as HttpUpdateGetter
@@ -161,6 +162,20 @@ def GetSshkeyMap(self, since=None):
         users_url = self._BuildUrlWithParameters(base_users_url, self.conf.get('users_parameters', ''))
         return SshkeyUpdateGetter(self.conf).GetUpdates(self, users_url, since)
 
+    def GetShadowMap(self, since=None):
+        """Return the shadow map from this source.
+
+        Args:
+          since: Get data only changed since this timestamp (inclusive) or None
+          for all data.
+
+        Returns:
+          instance of shadow.ShadowMap
+        """
+        base_users_url = f"{self.conf['base_url']}/{self.conf['users_endpoint']}"
+        users_url = self._BuildUrlWithParameters(base_users_url, self.conf.get('users_parameters', ''))
+        return ShadowUpdateGetter(self.conf).GetUpdates(self, users_url, since)
+
 class UpdateGetter(HttpUpdateGetter):
     """SCIM-specific update getter that extends HTTP functionality."""
 
@@ -689,3 +704,56 @@ def _ExtractGroupMembers(self, group_data):
                     members.append(member)
 
         return members
+
+
+class ShadowUpdateGetter(UpdateGetter):
+    """Get Shadow updates from the SCIM Source."""
+
+    def __init__(self, conf):
+        """Initialize with configuration."""
+        super().__init__()
+        self.conf = conf
+
+    def GetParser(self):
+        """Returns a MapParser to parse SCIM shadow cache."""
+        return ScimShadowMapParser(self.source)
+
+    def CreateMap(self):
+        """Returns a new ShadowMap instance to have ShadowMapEntries added to it."""
+        return shadow.ShadowMap()
+
+
+class ScimShadowMapParser(ScimMapParser):
+    """A MapParser for SCIM shadow map data."""
+
+    def _ReadEntry(self, user_data):
+        """Return a ShadowMapEntry from a SCIM user resource."""
+        username_path = self._GetMapConfig("scim_path_username", "userName")
+        
+        # Extract username using the configured path
+        username = self._ExtractFromPath(user_data, username_path)
+        if not username:
+            # Fallback to default userName field
+            username = user_data.get("userName")
+        
+        if not username:
+            self.log.warning("Could not extract username from SCIM user object")
+            return None
+        
+        shadow_ent = shadow.ShadowMapEntry()
+        shadow_ent.name = username
+        
+        # Set shadow password to * since SCIM doesn't provide password data
+        # This indicates authentication is handled elsewhere
+        shadow_ent.passwd = "*"
+        
+        # Set other shadow fields using configurable defaults
+        shadow_ent.lstchg = self._GetMapConfig("scim_shadow_default_lstchg", "")  # Last password change
+        shadow_ent.min = self._GetMapConfig("scim_shadow_default_min", "")     # Minimum password age
+        shadow_ent.max = self._GetMapConfig("scim_shadow_default_max", "")     # Maximum password age  
+        shadow_ent.warn = self._GetMapConfig("scim_shadow_default_warn", "")   # Password warning period
+        shadow_ent.inact = self._GetMapConfig("scim_shadow_default_inact", "") # Password inactivity period
+        shadow_ent.expire = self._GetMapConfig("scim_shadow_default_expire", "") # Account expiration date
+        shadow_ent.flag = self._GetMapConfig("scim_shadow_default_flag", "")   # Reserved field
+
+        return shadow_ent

nss_cache/sources/scimsource_test.py

@@ -9,6 +9,7 @@
 from nss_cache import error
 from nss_cache.maps import group
 from nss_cache.maps import passwd
+from nss_cache.maps import shadow
 from nss_cache.maps import sshkey
 
 from nss_cache.sources import scimsource
@@ -446,6 +447,24 @@ def testCreateMapMissingRequiredConfig(self):
         self.assertIn("scim_path_ssh_keys configuration is required", str(cm.exception))
 
 
+class TestScimShadowUpdateGetter(unittest.TestCase):
+    def setUp(self):
+        super(TestScimShadowUpdateGetter, self).setUp()
+        self.config = {"path_username": "userName"}
+        self.updater = scimsource.ShadowUpdateGetter(self.config)
+
+    def testGetParser(self):
+        """Test that GetParser returns correct parser type."""
+        self.updater.source = mock.Mock()
+        parser = self.updater.GetParser()
+        self.assertTrue(isinstance(parser, scimsource.ScimShadowMapParser))
+
+    def testCreateMap(self):
+        """Test that CreateMap returns ShadowMap."""
+        shadow_map = self.updater.CreateMap()
+        self.assertTrue(isinstance(shadow_map, shadow.ShadowMap))
+
+
 class TestScimMapParser(unittest.TestCase):
     def setUp(self):
         super(TestScimMapParser, self).setUp()
@@ -779,5 +798,98 @@ def testReadEntryWithMissingMembers(self):
         self.assertEqual(entry.members, [])
 
 
+class TestScimShadowMapParser(unittest.TestCase):
+    def setUp(self):
+        super(TestScimShadowMapParser, self).setUp()
+        self.config = {"path_username": "userName"}
+        source = mock.Mock()
+        source.conf = self.config
+        self.parser = scimsource.ScimShadowMapParser(source)
+
+    def testReadEntryValidUser(self):
+        """Test _ReadEntry with valid user data."""
+        user_data = {
+            "userName": "testuser",
+            "id": "1001"
+        }
+        
+        entry = self.parser._ReadEntry(user_data)
+        
+        self.assertIsNotNone(entry)
+        self.assertEqual(entry.name, "testuser")
+        self.assertEqual(entry.passwd, "*")
+        # All other shadow fields should be empty strings
+        self.assertEqual(entry.lstchg, "")
+        self.assertEqual(entry.min, "")
+        self.assertEqual(entry.max, "")
+        self.assertEqual(entry.warn, "")
+        self.assertEqual(entry.inact, "")
+        self.assertEqual(entry.expire, "")
+        self.assertEqual(entry.flag, "")
+
+    def testReadEntryMissingUsername(self):
+        """Test _ReadEntry with missing username field."""
+        user_data = {
+            "id": "1002"
+        }
+        
+        entry = self.parser._ReadEntry(user_data)
+        
+        self.assertIsNone(entry)
+
+    def testReadEntryWithCustomUsernamePath(self):
+        """Test _ReadEntry with custom username path."""
+        custom_config = {"path_username": "urn:scim:schemas:extension:User/userName"}
+        source = mock.Mock()
+        source.conf = custom_config
+        parser = scimsource.ScimShadowMapParser(source)
+        
+        user_data = {
+            "urn:scim:schemas:extension:User": {
+                "userName": "customuser"
+            },
+            "id": "1003"
+        }
+        
+        entry = parser._ReadEntry(user_data)
+        
+        self.assertIsNotNone(entry)
+        self.assertEqual(entry.name, "customuser")
+        self.assertEqual(entry.passwd, "*")
+
+    def testReadEntryWithCustomShadowDefaults(self):
+        """Test _ReadEntry with custom shadow field defaults."""
+        custom_config = {
+            "shadow_default_lstchg": "19000",
+            "shadow_default_min": "0", 
+            "shadow_default_max": "99999",
+            "shadow_default_warn": "7",
+            "shadow_default_inact": "30",
+            "shadow_default_expire": "20000",
+            "shadow_default_flag": "0"
+        }
+        source = mock.Mock()
+        source.conf = custom_config
+        parser = scimsource.ScimShadowMapParser(source)
+        
+        user_data = {
+            "userName": "testuser",
+            "id": "1001"
+        }
+        
+        entry = parser._ReadEntry(user_data)
+        
+        self.assertIsNotNone(entry)
+        self.assertEqual(entry.name, "testuser")
+        self.assertEqual(entry.passwd, "*")
+        # Verify custom shadow field defaults are used
+        self.assertEqual(entry.lstchg, "19000")
+        self.assertEqual(entry.min, "0")
+        self.assertEqual(entry.max, "99999")
+        self.assertEqual(entry.warn, "7")
+        self.assertEqual(entry.inact, "30")
+        self.assertEqual(entry.expire, "20000")
+        self.assertEqual(entry.flag, "0")
+
 if __name__ == "__main__":
     unittest.main()

nsscache.conf.5

@@ -407,7 +407,7 @@ scim_path_home_directory configuration and SCIM response data.
 
 The following path configuration options allow customization of how data is
 extracted from SCIM responses. These can be set per-map in
-[passwd], [group], or [sshkey] sections:
+[passwd], [group], [shadow], or [sshkey] sections:
 
 .TP
 .B scim_path_username
@@ -438,6 +438,47 @@ uses the scim_default_shell value.
 Path within SCIM user resources to extract SSH public keys. Should point to
 an array of SSH key strings or a single SSH key string.
 
+.PP
+The shadow map uses user data from the SCIM users endpoint and creates
+shadow(5) format entries. It only requires scim_path_username configuration
+in the [shadow] section, as other shadow fields (password aging, etc.) are
+not typically available from SCIM sources. All shadow entries are created
+in the format: username:*::::::: where '*' indicates that authentication
+is handled elsewhere (not via local password files).
+
+The following optional configuration parameters can be set in the [shadow]
+section to provide default values for shadow fields:
+
+.TP
+.B scim_shadow_default_lstchg
+Default value for the last password change field (days since Jan 1, 1970).
+Defaults to empty string.
+
+.TP
+.B scim_shadow_default_min
+Default value for the minimum password age field (days). Defaults to empty string.
+
+.TP
+.B scim_shadow_default_max
+Default value for the maximum password age field (days). Defaults to empty string.
+
+.TP
+.B scim_shadow_default_warn
+Default value for the password warning period field (days). Defaults to empty string.
+
+.TP
+.B scim_shadow_default_inact
+Default value for the password inactivity period field (days). Defaults to empty string.
+
+.TP
+.B scim_shadow_default_expire
+Default value for the account expiration date field (days since Jan 1, 1970).
+Defaults to empty string.
+
+.TP
+.B scim_shadow_default_flag
+Default value for the reserved flag field. Defaults to empty string.
+
 .SH files CACHE OPTIONS
 These options configure the behaviour of the
 .I files