ubccr · jpwhite4 · Feb 6, 2025
diff --git a/bin/xdmod-admin b/bin/xdmod-admin
@@ -13,6 +13,7 @@ require_once __DIR__ . '/../configuration/linker.php';
 use CCR\DB;
 use CCR\DB\MySQLHelper;
 use CCR\Log;
+use Models\Services\Acls;
 
 // TODO
 // Tasks:
@@ -35,7 +36,7 @@ try {
  */
 function main()
 {
-    global $argv, $logger;
+    global $argv, $logger, $force;
 
     $opts = array(
         array('h', 'help'),
@@ -49,6 +50,8 @@ function main()
         array('',  'jobs'),
         array('l', 'list'),
         array('t', 'truncate'),
+        array('', 'users'),
+        array('', 'load:'),
      );
 
     $shortOptions = implode(
@@ -68,6 +71,7 @@ function main()
 
     $entity = null;
     $action = null;
+    $params = null;
 
     $logLevel = -1;
 
@@ -131,6 +135,21 @@ function main()
                 }
                 $action = 'truncate';
                 break;
+            case 'users':
+                if ($entity !== null) {
+                    fwrite(STDERR, "Only one entity type may be specified\n");
+                    exit(1);
+                }
+                $entity = 'users';
+                break;
+            case 'load':
+                if ($action !== null) {
+                    fwrite(STDERR, "Only one action may be specified\n");
+                    exit(1);
+                }
+                $action = 'load';
+                $params = $value;
+                break;
             default:
                 fwrite(STDERR, "Unexpected option '$key'\n");
                 exit(1);
@@ -189,6 +208,17 @@ function main()
                     break;
             }
             break;
+        case 'users':
+            switch ($action) {
+                case 'load':
+                    loadUsers($params);
+                    break;
+                default:
+                    $logger->crit("Cannot perform '$action' on '$entity'");
+                    exit(1);
+                    break;
+            }
+            break;
         default:
             $logger->crit("Unknown entity type '$entity'");
             exit(1);
@@ -218,6 +248,131 @@ function listResources()
     }
 }
 
+/**
+ * Generate mapping between the display string of an ACL with the corresponding
+ * internal identifier.
+ */
+function getAclMap()
+{
+    $acls = Acls::getAcls();
+    $aclMap = array();
+    foreach ($acls as $acl) {
+        $aclMap[$acl->getDisplay()] = $acl->getName();
+    }
+    return $aclMap;
+}
+
+/**
+ * Add SSO user accounts
+ */
+function addSSOUsers(array $data)
+{
+    global $logger;
+
+    $load_count = 0;
+
+    foreach($data as $user) {
+        $xdmodUserId = \XDUser::userExistsWithUsername($user['username']);
+        if ($xdmodUserId !== INVALID) {
+            $logger->warning("Skipping user '${user['username']}' - account already exists");
+            continue;
+        }
+
+        $newUser = new \XDUser(
+            $user['username'],
+            null,
+            $user['email'],
+            $user['first_name'],
+            '',
+            $user['last_name'],
+            $user['acls'],
+            '',
+            1,
+            -1,
+            array()
+        );
+        $newUser->setUserType(SSO_USER_TYPE);
+        $newUser->saveUser();
+        $load_count += 1;
+    }
+
+    return $load_count;
+}
+
+/**
+ * Load XDMoD user information from a file
+ */
+function parseUserList(string $filename)
+{
+    global $logger;
+
+    $aclMap = getAclMap();
+
+    $userdata = array();
+
+    $fh = fopen($filename, 'r');
+    if ($fh === false) {
+        $logger->crit("Failed to open file '$filename'");
+        exit(1);
+    }
+
+    $logger->debug("Reading CSV data from '$filename'");
+
+    $lineno = 0;
+    while ($row = fgetcsv($fh)) {
+        $lineno += 1;
+
+        // Skip blank lines.
+        if (count($row) == 1 && $row[0] === null) {
+            continue;
+        }
+        if (count($row) != 5) {
+            $logger->error("Invalid CSV data on line $lineno in file '$filename'");
+            exit(1);
+        }
+
+        $requestedAcls = explode(';', $row[4]);
+
+        $userAcls = array_map(function ($aclDisplay) use ($aclMap) {
+            return $aclMap[$aclDisplay];
+        }, $requestedAcls);
+
+        $userdata[] = array(
+            'username' => $row[0],
+            'first_name' => $row[1],
+            'last_name' => $row[2],
+            'email' => $row[3],
+            'acls' => $userAcls
+        );
+    }
+
+    if (!fclose($fh)) {
+        $logger->crit("Failed to close file '$filename'");
+        exit(1);
+    }
+
+    return $userdata;
+}
+
+/**
+ * Load users from a file
+ */
+function loadUsers(string $filename)
+{
+    global $logger, $force;
+
+    $users = parseUserList($filename);
+    $ucount = count($users);
+
+    if (!$force && !confirm("Load $ucount users from '$filename'?")) {
+        return;
+    }
+
+    $nloaded = addSSOUsers($users);
+
+    $logger->debug("Loaded $nloaded users from '$filename'.");
+}
+
 /**
  * Truncate all the job tables.
  */
@@ -317,8 +472,9 @@ function displayHelpText()
 
 Perform administrative tasks.
 
-This command currently supports truncating all job data or listing the
-currently configured resources.
+This command currently supports truncating all job data, listing the
+currently configured resources and bulk loading XDMoD portal user accounts
+from file.
 
 Usage: xdmod-admin [-v]
 
@@ -344,18 +500,24 @@ Usage: xdmod-admin [-v]
     -j, --job, --jobs
         Perform action on jobs.
 
+    --users
+        Perform action on XDMoD portal user accounts.
+
     -t, --truncate
         Truncate data (only used for jobs).
 
     -l, --list
         List data (only used for resources).
 
+    --load FILENAME
+        Load information from file FILENAME (only used for users).
+
 Examples:
 
     xdmod-admin --jobs --truncate
 
     xdmod-admin --resources --list
 
+    xdmod-admin --users --load PATH/TO/USERS-CSV-FILE.csv
 EOF;
 }
-
diff --git a/docs/commands.md b/docs/commands.md
@@ -21,9 +21,39 @@ details.
 ### xdmod-admin
 
 The `xdmod-admin` command is used to perform various administrative
-tasks.  Currently supported tasks include listing all the resources
-configured in Open XDMoD and truncating all job data from the Open
-XDMoD databases.
+tasks.  Currently supported tasks are listed in the table below:
+
+| Task | Example command line | Description |
+| ---- | -------------------- | ----------- |
+| Delete Jobs Data | `xdmod-admin --truncate --jobs` | This command removes all data from the Jobs realm.  |
+| List configured resources | `xdmod-admin --list --resources` | This command lists all resources that are configured in the resources.json configuration file. |
+| Preconfigure SSO user accounts | `xdmod-admin --users --load PATH/TO/USERSFILE.csv` | Preconfigure user account settings for SSO users. |
+
+
+#### Preconfigure SSO user accounts
+
+XDMoD can be configured to use [Single Sign On Authentication](simpleSAMLphp.md) (SSO).
+When a user who has previously never used XDMoD logs in with SSO then a user account
+is automatically created for them. This automatically provisioned account is created
+with just the 'User' acl.
+
+If you want a user to be able to login with SSO and have higher permissions (such as
+Center Staff or Center Director), then they have to either (1) login via SSO once
+so the account is created and then an admin has to update their permissions in the
+admin dashboard or (2) use `xdmod-admin` to preconfigure the account _before they login for the first time_.
+
+To preconfigure SSO accounts use the `xdmod-admin --users --load FILENAME.csv` command
+toload the user settings from a csv file.
+The csv file must be a comma separated csv file in utf8 character set with the following five fields:
+
+- XDMoD Portal Username
+- First Name
+- Last Name
+- E-mail Address
+- Semi-colon separated list of ACLs (e.g. `User;Center Director`)
+
+The allowed values for ACLs can be viewed in the "User Management" dialog in the "Admin Dashboard"
+in the portal. The username must match exactly the `username` property from the SSO provider.
 
 ### xdmod-shredder