user_role: update role to take a list instead of string

changelogs/changelog.yaml

@@ -573,3 +573,7 @@ releases:
     fragments:
     - 314-ansible-2-19-compatibility.yml
     release_date: '2025-05-03'
+  2.6.2:
+    changes:
+      minor_changes:
+      - Added ability for user_role module to take a list of roles. Optionally can also remove unlisted roles.

galaxy.yml

@@ -2,7 +2,7 @@
 
 namespace: lowlydba
 name: sqlserver
-version: 2.6.1
+version: 2.6.2
 readme: README.md
 authors:
   - John McCall (github.com/lowlydba)

plugins/modules/user_role.ps1

@@ -15,17 +15,19 @@ $spec = @{
     options = @{
         database = @{type = 'str'; required = $true }
         username = @{type = 'str'; required = $true }
-        role = @{type = 'str'; required = $true }
+        roles = @{type = 'list'; elements = 'str'; required = $true; aliases = 'role' }
         state = @{type = 'str'; required = $false; default = 'present'; choices = @('present', 'absent') }
+        remove_unlisted = @{type = 'bool'; required = $false; default = 'false' }
     }
 }
 
 $module = [Ansible.Basic.AnsibleModule]::Create($args, $spec, @(Get-LowlyDbaSqlServerAuthSpec))
 $sqlInstance, $sqlCredential = Get-SqlCredential -Module $module
 $username = $module.Params.username
 $database = $module.Params.database
-$role = $module.Params.role
+$roles = $module.Params.roles
 $state = $module.Params.state
+$remove_unlisted = $module.Params.remove_unlisted
 $checkMode = $module.CheckMode
 
 $module.Result.changed = $false
@@ -37,78 +39,126 @@ $getUserSplat = @{
     User = $username
     EnableException = $true
 }
-$getRoleSplat = @{
-    SqlInstance = $sqlInstance
-    SqlCredential = $sqlCredential
-    Database = $database
-    Role = $role
-    EnableException = $true
+
+$outputProps = @{}
+
+# Verify user and role(s) exist, DBATools currently fails silently
+$existingUser = Get-DbaDbUser @getUserSplat
+if ($null -eq $existingUser) {
+    $module.FailJson("User [$username] does not exist in database [$database].")
 }
+
+$roles | ForEach-Object {
+    $thisRole = $_
+    $getRoleSplat = @{
+        SqlInstance = $sqlInstance
+        SqlCredential = $sqlCredential
+        Database = $database
+        Role = $thisrole
+        EnableException = $true
+    }
+    $existingRole = Get-DbaDbRole @getRoleSplat
+    if ($null -eq $existingRole) {
+        $module.FailJson("Role [$thisRole] does not exist in database [$database].")
+    }
+}
+
+# Get role members of all roles we care about to compare against later
 $getRoleMemberSplat = @{
     SqlInstance = $sqlInstance
     SqlCredential = $sqlCredential
     Database = $database
-    Role = $role
     IncludeSystemUser = $true
     EnableException = $true
 }
-
-# Verify user and role exist, DBATools currently fails silently
-$existingUser = Get-DbaDbUser @getUserSplat
-if ($null -eq $existingUser) {
-    $module.FailJson("User [$username] does not exist in database [$database].")
-}
-$existingRole = Get-DbaDbRole @getRoleSplat
-if ($null -eq $existingRole) {
-    $module.FailJson("Role [$role] does not exist in database [$database].")
-}
-
-# Get role members
-$existingRoleMembers = Get-DbaDbRoleMember @getRoleMemberSplat
+$existingRoleMembership = Get-DbaDbRoleMember @getRoleMemberSplat | Where-Object {$_.UserName -eq $username} | Select -ExpandProperty role | Sort-Object
 
 if ($state -eq "absent") {
-    if ($existingRoleMembers.username -contains $username) {
-        try {
-            $removeRoleMemberSplat = @{
-                SqlInstance = $sqlInstance
-                SqlCredential = $sqlCredential
-                User = $username
-                Database = $database
-                Role = $role
-                EnableException = $true
-                WhatIf = $checkMode
-                Confirm = $false
+    $roles | ForEach-Object {
+        $thisRole = $_
+        if ( $existingRoleMembership -contains $thisRole ) {
+            try {
+                $removeRoleMemberSplat = @{
+                    SqlInstance = $sqlInstance
+                    SqlCredential = $sqlCredential
+                    User = $username
+                    Database = $database
+                    Role = $thisRole
+                    EnableException = $true
+                    WhatIf = $checkMode
+                    Confirm = $false
+                }
+                Remove-DbaDbRoleMember @removeRoleMemberSplat
+                $module.Result.changed = $true
+            }
+            catch {
+                $module.FailJson("Removing user [$username] from database role [$thisRole] failed: $($_.Exception.Message)", $_)
             }
-            $output = Remove-DbaDbRoleMember @removeRoleMemberSplat
-            $module.Result.changed = $true
-        }
-        catch {
-            $module.FailJson("Removing user [$username] from database role [$role] failed: $($_.Exception.Message)", $_)
         }
     }
 }
 elseif ($state -eq "present") {
     # Add user to role
-    if ($existingRoleMembers.username -notcontains $username) {
-        try {
-            $addRoleMemberSplat = @{
-                SqlInstance = $sqlInstance
-                SqlCredential = $sqlCredential
-                User = $username
-                Database = $database
-                Role = $role
-                EnableException = $true
-                WhatIf = $checkMode
-                Confirm = $false
+    $roles | ForEach-Object {
+        $thisRole = $_
+        if ($existingRoleMembership -notcontains $thisRole) {
+            try {
+                $addRoleMemberSplat = @{
+                    SqlInstance = $sqlInstance
+                    SqlCredential = $sqlCredential
+                    User = $username
+                    Database = $database
+                    Role = $thisRole
+                    EnableException = $true
+                    WhatIf = $checkMode
+                    Confirm = $false
+                }
+                Add-DbaDbRoleMember @addRoleMemberSplat
+                $module.Result.changed = $true
+            }
+            catch {
+                $module.FailJson("Adding user [$username] to database role [$thisRole] failed: $($_.Exception.Message)", $_)
             }
-            $output = Add-DbaDbRoleMember @addRoleMemberSplat
-            $module.Result.changed = $true
         }
-        catch {
-            $module.FailJson("Adding user [$username] to database role [$role] failed: $($_.Exception.Message)", $_)
+    }
+}
+if ($state -eq "present" -and $remove_unlisted -eq $true) {
+    #remove users from roles that weren't listed (if we got the remove_unlisted option set to true)
+    $existingRoleMembership | ForEach-Object {
+        $thisRole = $_
+        if ($roles -notcontains $thisRole) {
+            try {
+                $removeRoleMemberSplat = @{
+                    SqlInstance = $sqlInstance
+                    SqlCredential = $sqlCredential
+                    User = $username
+                    Database = $database
+                    Role = $thisRole
+                    EnableException = $true
+                    WhatIf = $checkMode
+                    Confirm = $false
+                }
+                Remove-DbaDbRoleMember @removeRoleMemberSplat
+                $module.Result.changed = $true
+            }
+            catch {
+                $module.FailJson("Removing user [$username] from extra unlisted database role [$thisRole] failed: $($_.Exception.Message)", $_)
+            }
         }
     }
 }
+
+try {
+    #after changing any roles above, see what our new membership is and report it back
+    $newRoleMembership = Get-DbaDbRoleMember @getRoleMemberSplat | Where-Object {$_.UserName -eq $username} | Select -ExpandProperty role | Sort-Object
+}
+catch {
+    $module.FailJson("Failure getting new role membership: $($_.Exception.Message)", $_)
+}
+$outputProps.newRoleMembership = [array]$newRoleMembership
+$outputProps.oldRoleMembership = [array]$existingRoleMembership
+$output = New-Object -TypeName PSCustomObject -Property $outputProps
+
 try {
     if ($null -ne $output) {
         $resultData = ConvertTo-SerializableObject -InputObject $output

plugins/modules/user_role.py

@@ -22,11 +22,18 @@
       - Name of the user.
     type: str
     required: true
-  role:
+  roles:
     description:
       - The database role for the user to be modified.
-    type: str
+    type: list
     required: true
+  remove_unlisted:
+    description:
+      - When set to true, will remove any other roles that aren't listed in roles.
+    type: boolean
+    required: false
+    default: false
+    version_added: 2.6.2
 author: "John McCall (@lowlydba)"
 requirements:
   - L(dbatools,https://www.powershellgallery.com/packages/dbatools/) PowerShell module
@@ -45,6 +52,15 @@
     database: InternProject1
     role: db_owner
 
+- name: Add a user to a list of db roles
+  lowlydba.sqlserver.user_role:
+    sql_instance: sql-01.myco.io
+    username: TheIntern
+    database: InternProject1
+    role:
+      - db_datareader
+      - db_datawriter
+
 - name: Remove a user from a fixed db role
   lowlydba.sqlserver.login:
     sql_instance: sql-01.myco.io
@@ -60,6 +76,18 @@
     database: InternProject1
     role: db_intern
     state: absent
+
+- name: Specify a list of roles that user should be in and remove all others
+  lowlydba.sqlserver.login:
+    sql_instance: sql-01.myco.io
+    username: TheIntern
+    database: InternProject1
+    role:
+      - db_datareader
+      - db_datawriter
+    state: present
+    remove_unlisted: true
+
 '''
 
 RETURN = r'''

sqlserver

@@ -0,0 +1 @@
+/home/cameron/ansible-collections-dev/lowlydba/sqlserver

tests/integration/targets/user_role/tasks/main.yml

@@ -72,6 +72,7 @@
     - assert:
         that:
           - result is changed
+          - result.data.newRoleMembership == ["db_owner"]
 
     - name: Add user to non-existent database role
       lowlydba.sqlserver.user_role:
@@ -102,13 +103,48 @@
         that:
           - result is not changed
 
+    - name: Add user to list of database roles
+      lowlydba.sqlserver.user_role:
+        role:
+          - db_datareader
+          - db_datawriter
+      register: result
+    - assert:
+        that:
+          - result is changed
+          - result.data.newRoleMembership == ["db_datareader", "db_datawriter", "db_owner"]
+
+    - name: Add user to list of database roles again
+      lowlydba.sqlserver.user_role:
+        role:
+          - db_datareader
+          - db_datawriter
+      register: result
+    - assert:
+        that:
+          - result is not changed
+
+    - name: Add user to list of database roles, and remove unlisted roles
+      lowlydba.sqlserver.user_role:
+        role:
+          - db_datareader
+          - db_datawriter
+        remove_unlisted: true
+      register: result
+    - assert:
+        that:
+          - result is changed
+          - result.data.newRoleMembership == ["db_datareader", "db_datawriter"]
+
     - name: Remove user from database role
       lowlydba.sqlserver.user_role:
         state: "absent"
+        role: db_datawriter
       register: result
     - assert:
         that:
           - result is changed
+          - result.data.newRoleMembership == ["db_datareader"]
 
   always:
     - name: Drop user