IAMClient

1.2.6

IAMClient.psm1

function Add-ETHGroupMember {
    [CmdletBinding(SupportsShouldProcess = 1)]
    param (   
        [Parameter(Position = 0, Mandatory = 1, ValueFromPipeline = 1)]
        [string]$Identity,
        [string[]]$Members
    )

    BEGIN {
        # Check if client is initialized
        Test-IsIAMClientInitialized | Out-Null

        # Validate input arguments
        if (-not ($ExistingGroup = Get-ETHGroup -Identity $Identity)) {
            throw "Group $Identity was not found"
        }

        if ($Members.Count -le 0) {
            throw "No members specified"
        }

        $ToAddMembers = @($Members | Where-Object { $ExistingGroup.members -notcontains $_ })

        if ($ToAddMembers.Count -eq 0) {
            Write-Debug "No new members added to group $Identity"
            return
        }
    }

    PROCESS {
        if ($PSCmdlet.ShouldProcess($Identity)) {
            try {
                $result = Invoke-IAMMethod -Url "/groupmgr/group/$Identity/members/add" -Method Put -Body $ToAddMembers -Credentials $script:IAMCreds
            }
            catch {
                throw "Could not update group $Identity, Error: $_"
                return
            }
        }
    }

    END {
        Write-Debug "Added $($ToAddMembers.Count) Members to Group $Identity"
        return $result
    }
    
}


function Add-ETHMaillistMember {
    param (
        # List Name
        [Parameter(Position = 0, Mandatory = $true)]
        [string]$Identity,

        # Member to add or remove
        [Parameter(Position = 1, Mandatory = $true, ValueFromPipeline = $true)]
        [string[]]$Members
    )

    BEGIN {
        Test-IsIAMClientInitialized | Out-Null

        $Url = "/mailinglists/$Identity/members/add"
    }

    PROCESS {
        return (Invoke-IAMMethod -Url $Url -Body $Members -Method Put -Credentials $script:IAMCreds)
    }


}


function Add-ETHUserITService {
    param (
        # ETH user name
        [Parameter(Position = 0, Mandatory = 1)]
        [string]
        $Identity,

        # IT Service Name
        [Parameter(Position = 1, Mandatory = 1)]
        [string]
        $ITServiceName,

        # Body
        [Parameter(Position = 2)]
        [psobject]
        $Body
    )

    BEGIN {
        # Check if client is initialized
        Test-IsIAMClientInitialized | Out-Null

        if ($Body -eq $null) {
            $Body = @{ }
        }
    }

    PROCESS {
        return (Invoke-IAMMethod -Url "/usermgr/user/$Identity/service/$ITServiceName" -Method POST -Credentials $script:IAMCreds -Body $Body)
    }
}



function Add-ETHUserMailAlias {
<#
    .SYNOPSIS
        Adds a new e-mail alias (proxyAddress) to a user's mailbox
         
    .DESCRIPTION
        Adds a new e-mail alias (proxyAddress) to a user's mailbox, this works by changing the main
        e-mail to the new alias and then back to the existing.
 
        !! WARNING: The Cmdlet currently does not reset the main e-mail address again, because IAM does not work (bug as of 14.02.2020) !!
 
    .PARAMETER Identity
        The user to add the alias to
 
    .PARAMETER Alias
        The alias(es) to give to the user
 
    .EXAMPLE
        Add-ETHUserMailAlias -Identity aurels -Alias "aurels.new@ethz.ch","my_cool_email@micro.biol.ethz.ch"
     
    #>

    [CmdletBinding()]
    param (
        [Parameter(Position = 0, Mandatory = 1)]
        [string]$Identity,

        [Parameter(Position = 1, Mandatory = 1, ValueFromPipeline = 1)]
        [string[]]$Alias
    )


    BEGIN {
        # Check if client is initialized
        $null = Test-IsIAMClientInitialized

        $User = Get-ETHUser -Identity $Identity
        $SavedEmail = $User.mail
    }

    PROCESS {
        foreach ($_alias in $Alias) {
            if ($User.proxyAdresses -contains "smtp:$_alias"){
                # this alias already exists, nothing do to
                continue
            }
            $User.mail = $_alias

            $User = Set-ETHUser -Identity $Identity -User $User
        }  
    }

    END {
        $User.mail = $SavedEmail
        Set-ETHUser -Identity $Identity -User $User
    }
    
}


function Clear-ETHMaillistMember {
    param (
        # List Name
        [Parameter(Position = 0, Mandatory = $true)]
        [string]$Identity
    )

    BEGIN {
        Test-IsIAMClientInitialized | Out-Null

        $Url = "/mailinglists/$Identity/members"
    }

    PROCESS {
        return (Invoke-IAMMethod -Url $Url -Method Delete -Credentials $script:IAMCreds)
    }
}


Function Compare-ObjectProperties {
    Param(
        [PSObject]$ReferenceObject,
        [PSObject]$DifferenceObject 
    )
    $objprops = $ReferenceObject | Get-Member -MemberType Property, NoteProperty | Select-Object -expand  Name
    $objprops += $DifferenceObject | Get-Member -MemberType Property, NoteProperty | Select-Object -expand Name
    $objprops = $objprops | Sort-Object -Unique
    $diffs = @()
    foreach ($objprop in $objprops) {
        $diff = Compare-Object $ReferenceObject $DifferenceObject -Property $objprop
        if ($diff) {            
            $diffprops = @{
                PropertyName = $objprop
                RefValue     = ($diff | Where-Object { $_.SideIndicator -eq '<=' } | Foreach-Object $($objprop))
                DiffValue    = ($diff | Where-Object { $_.SideIndicator -eq '=>' } | Foreach-Object $($objprop))
            }
            $diffs += New-Object PSObject -Property $diffprops
        }        
    }
    if ($diffs) { return ($diffs | Select-Object PropertyName, RefValue, DiffValue) }     
}

Function Get-ObjectDiffs {
    param (
        [PSObject]$ReferenceObject,
        [PSObject]$DifferenceObject
    )

    $ChangedProps = @{ }

    Compare-ObjectProperties $ReferenceObject $DifferenceObject | ForEach-Object {
        $ChangedProps.Add($_.PropertyName, $_.DiffValue);
    }

    return $ChangedProps
}

function Compare-GroupMembers {

    param (
        [string[]]$ExistingMembers,
        [string[]]$NewMembers
    )

    BEGIN {
        $ToAddMembers = @()
        $ToRemoveMembers = @()
        $ToKeepMembers = @()
    }

    PROCESS {
        if ($ExistingMembers.Count -eq 0) {
            # No existing members -> add all
            $ToAddMembers = $NewMembers
        }
        elseif ($NewMembers.Count -eq 0) {
            # No new members -> remove all existing
            $ToRemoveMembers = $ExistingMembers
        }
        else {
            # everything fine, we can run compare-object
            $ComparisionResult = Compare-Object -ReferenceObject $ExistingMembers -DifferenceObject $Members -IncludeEqual

            $ToAddMembers = ($ComparisionResult | Where-Object SideIndicator -eq "=>").InputObject
            $ToRemoveMembers = ($ComparisionResult | Where-Object SideIndicator -eq "<=").InputObject
            $ToKeepMembers = ($ComparisionResult | Where-Object SideIndicator -eq "==").InputObject
        }
    
        return [PSCustomObject]@{
            ToAdd    = $ToAddMembers;
            ToRemove = $ToRemoveMembers;
            ToKeep   = $ToKeepMembers;
        }

    }
}


function Find-ETHGroup {
    <#
    .SYNOPSIS
        Finds a Group in IAM
         
    .DESCRIPTION
        Finds a Group in IAM with the specified filter
 
    .PARAMETER Name
        The name of the group to find (accepts wildcards *)
     
    .PARAMETER AdminGroup
        The AdminGroup to filter on
         
    .EXAMPLE
        Find-ETHGroup -Name "biol-micro-isg*"
     
        In this example, the all groups are found that start with "biol-micro-isg*"
 
    .EXAMPLE
        Find-ETHGroup -Name "biol-micro-isg*" -AdminGroup "D-BIOL"
 
        In this example, all groups of Admin Group "D-BIOL" are found that start with "ID-S4D"
 
    #>
    param (
        [CmdletBinding()]
        [Parameter(Position = 0)]
        [string]$Name,
        
        [Parameter(Position = 1)]
        [string]$AdminGroup
    )

    BEGIN {
        # Check if client is initialized
        Test-IsIAMClientInitialized | Out-Null

        if (-not $Name -and -not $AdminGroup) {
            throw "Please specify at least one filter criterium!"
        }
    }

    PROCESS {

        $url = "/groupmgr/groups?"

        if ($Name) {
            $url += "name=$Name"
        }

        if ($AdminGroup -and $Name) {
            $url += "&"
        }

        if ($AdminGroup) {
            $url += "agroup=$AdminGroup"
        }

        Invoke-IAMMethod -Url $url -Method Get -Credentials $script:IAMCreds | 
        ForEach-Object { $_.pstypenames.Insert(0, "ETHZ.ID.IAMClient.IAMGroupSearchResult"); $_ } |
        Sort-Object AdminGroup, type, Name
    }

    END {

    }    
}



function Get-ETHGroup {
    param (
        [CmdletBinding()]
        [Parameter(Position = 0, Mandatory = 1)]
        [string]$Identity
    )

    BEGIN {
        # Check if client is initialized
        Test-IsIAMClientInitialized | Out-Null

        $url = "/groupmgr/group/$Identity"
    }

    PROCESS {
        return (Invoke-IAMMethod -Url $url -Method Get -Credentials $script:IAMCreds)
    }

    END {

    }    
}



function Get-ETHGroupMember {
    [CmdletBinding()]
    param (
        [Parameter(Position = 0, Mandatory = 1, ValueFromPipelineByPropertyName = 1)]
        [string]$Identity
    )

    BEGIN {
        $Group = Get-ETHGroup -Identity $Identity
    }

    PROCESS {
        return ($Group | Select-Object -expand members)
    }

    END {

    }

}


function Get-ETHMaillist {
    param (
        # List Name
        [Parameter(Position = 0, Mandatory = $true)]
        [string]$Identity
    )

    BEGIN {
        Test-IsIAMClientInitialized | Out-Null

        $Url = "/mailinglists/$Identity"
    }

    PROCESS {
        return (Invoke-IAMMethod -Url $Url -Method Get -Credentials $script:IAMCreds)
    }
}


function Get-ETHMaillistMember {
    [CmdletBinding()]
    param (
        # List Name
        [Parameter(Position = 0, Mandatory = $true, ValueFromPipeline = $true)]
        [string]$Identity
    )

    BEGIN { }

    PROCESS {
        
        $membersCn = (Get-ETHMaillist -Identity $Identity).members

        foreach ($member in $membersCn) {
            $Name = ($member -split ",OU=")[0] -replace "CN="
        
            # determine if the member is a user or a mailinglist
            if ($member -like "*OU=EthLists,*") {
                $objectClass = "group"
            }
            else {
                $objectClass = "user"
            }
            
            # create simple return object
            [pscustomobject]@{
                name              = $Name;
                objectClass       = $objectClass;
                distinguishedName = $member; 
            }
        }
    }
}


function Get-ETHPerson {
    param (
        [Parameter(Position = 0, Mandatory = 1)]
        [string]$Identity
    )

    BEGIN {
        $url = "/usermgr/person/$Identity"

        # is client initialized?
        Test-IsIAMClientInitialized | Out-Null
    }

    PROCESS {
        return (Invoke-IAMMethod -Url $url -Method Get -Credentials $script:IAMCreds)
    }

    END {

    }
    
}


function Get-ETHPersonServices {
    param (
        # ETH user name
        [Parameter(Position = 0, Mandatory = 1)]
        [String]$Identity
    )

    BEGIN {
        # Check if client is initialized
        Test-IsIAMClientInitialized | Out-Null
    }

    PROCESS {
        return (Invoke-IAMMethod -Url "/usermgr/user/$Identity/services" -Method GET -Credentials $script:IAMCreds)
    }
}


function Get-ETHUser {
    <#
    .SYNOPSIS
        Gets the parameters of a IT-Service for a user (Similar to Get-ADUser)
         
    .DESCRIPTION
        Gets all parameters for a given service from IAM for the given user
        Default is the "Mailbox" service
 
    .PARAMETER Identity
        The username to find
 
    .PARAMETER Service
        The service name to get the parameters for
 
    .EXAMPLE
        Get-ETHUser aurels
 
    .EXAMPLE
        Get-ETHUser aurels -Service LDAP
     
    #>
    param (
        [Parameter(Position = 0, Mandatory = 1, ValueFromPipeline = $true)]
        [string]$Identity,
        [Parameter(Position = 1, Mandatory = 0)]
        [string]$Service = "Mailbox"
    )

    BEGIN {
        $url = "/usermgr/user/$Identity/service/$Service"

        # is client initialized?
        Test-IsIAMClientInitialized | Out-Null
    }
    
    PROCESS {
        $result = Invoke-IAMMethod -Url $url -Method Get -Credentials $script:IAMCreds
    }

    END {
        return $result
    }
    
}


function Get-ETHUserGroupMembership {
    <#
.SYNOPSIS
    Gets all memberships of the given user
     
.DESCRIPTION
    This will load all group memberships with type "Custom","Admin" and "Netsup" for the given user(s)
 
.PARAMETER Identity
    The username to find
 
.EXAMPLE
    Get-ETHUserGroupMembership aurels
 
.EXAMPLE
    "aurels","jgrand" | Get-ETHUserGroupMembership
 
#>
    [CmdletBinding()]
    param (
        [Parameter(Position = 0, Mandatory = 1, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = "Name")]
        [string]$Identity
    )

    BEGIN {
        # Check if client is initialized
        Test-IsIAMClientInitialized | Out-Null
        
    }

    PROCESS {
        $url = "/groupmgr/user/$Identity"

        if (-not (Get-ETHUser $Identity)) {
            throw "User $Identity could not be found"
        }

        $groups = (Invoke-IAMMethod -Url $url -Method Get -Credentials $script:IAMCreds).Groups
        $groups | Add-Member -MemberType NoteProperty -Value $Identity -Name "User"

        # set type for all objects
        $groups | ForEach-Object { $_.pstypenames.Insert(0, "ETHZ.ID.IAMClient.IAMGroupMembership") }

        return ($groups | Sort-Object -property Type, Name)
        
    }

    END { }

}


Function Write-RequestToConsole {
    param (
        [string]$Method,
        [hashtable]$Headers,
        [string]$JsonBody
    )

    Write-Verbose "-- || -- || -- || -- || --"

    Write-Verbose "$($Method.toUpper()) $Uri"

    foreach ($h in $Headers.Keys) {
        # Do not print basic auth string to console, instead override with some value
        if ($h -ne "Authorization") {
            Write-Verbose "${h}: $($Headers[$h])"
        }
        else {
            Write-Verbose "${h}: Basic BasicAuthString99999="
        }
    }
    Write-Verbose "Body: $JsonBody"
    
}

function Write-ResponseToConsole {
    param (
        $Response
    )
    Write-Verbose "------ RESPONSE:" 
    if ($null -ne $Response) {
        Write-Verbose (ConvertTo-Json $Response)
    }
}

function Convert-CnToName {
    [CmdletBinding()]
    param(
        # Canonical Name
        [Parameter(Position = 0, Mandatory = $true, ValueFromPipeline = $true)]
        [string]$Cn
    )

    PROCESS {
        return ($Cn -split ",")[0] -replace "CN="
    }
}


function Test-IsIAMClientInitialized {
    if ($null -eq $script:IAMCreds) {
        Initialize-IAMClient
        return $true
    }

    return $true
}


function Initialize-IAMClient {
    [CmdletBinding()]
    param(
        # Credentials to validate
        [Parameter(Position = 1, Mandatory = 1)]
        [pscredential]$Credentials,

        [switch]$Force,

        [switch]$EnableDebugOutput,

        [string]$ApiHost = "https://iam.passwort.ethz.ch"
    )

    $script:ApiHost = $ApiHost

    if ($Force -eq $true) {
        Write-Warning "The -Force switch is included for backwards compatibility only, it has no functionality"
    }

    # Enable Debug mode for script
    if ($EnableDebugOutput) {
        $script:DebugMode = $true
        $VerbosePreference = "Continue" 
    }
    else {
        $VerbosePreference = "SilentlyContinue"
    }

    if (-not (Test-ETHCredentials $Credentials)) {
        throw "Could not validate your credentials"
    }
     
    $script:IAMCreds = $Credentials

    Set-StrictMode -Version latest

      
}  




Function Invoke-IAMMethod {
    [CmdletBinding(SupportsShouldProcess = 1)]
    param (
        [Parameter(Position = 0, Mandatory = 1)]
        [string]$Url,

        [Parameter(Mandatory = 1)]
        [Microsoft.PowerShell.Commands.WebRequestMethod]$Method,

        [Parameter(Position = 1)]
        [psobject]$Body = "",
        
        [Parameter(Position = 2)]
        [pscredential]$Credentials

    )

    BEGIN {

        $Headers = @{ }

        If ($Credentials -ne $null) {
            $AuthHeader = "Basic " + [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes("$($Credentials.UserName):$($Credentials.GetNetworkCredential().Password)"));
            # only set auth header when needed
            $Headers.Add("Authorization", $AuthHeader);
        }

        if ($Body -ne "") {
            if ($Body -is [Array]) {
                $JsonBody = ConvertTo-Json @($Body) -Compress
            }
            else {
                $JsonBody = ConvertTo-Json $Body -Compress
            }
        }
        else {
            $JsonBody = ""
        }

        # Accept header
        $Headers.Add("Accept", "application/json");

        if (-not [string]::IsNullOrWhiteSpace($JsonBody)) {
            $Headers.Add("Content-type", "application/json; charset=utf-8");
        }

        # Form complete URL and parse it
        $Uri = $script:ApiHost + $Url
        if (-not [uri]::IsWellFormedUriString($Uri, "Absolute")) {
            throw "Could not parse URI $Uri"
            return
        }

    }

    PROCESS {
        if ($PSCmdlet.ShouldProcess($Url)) {
            if ($script:DebugMode) {
                Write-RequestToConsole -Method $Method.ToString() -Headers $Headers -JsonBody $JsonBody
            }

            try {


                # only provide the body when needed, as it gives an error when used with GET
                if ($Method -eq [Microsoft.PowerShell.Commands.WebRequestMethod]::Get) {
                    $Response = Invoke-RestMethod -Uri $Uri -Method $Method -Headers $Headers
                }
                else {
                    $Response = Invoke-RestMethod -Uri $Uri -Method $Method -Headers $Headers -Body $JsonBody
                }

                # Only write to console if debug is enabled
                if ($script:DebugMode) {
                    Write-ResponseToConsole -Response $Response
                }
            }
            catch {

                # if response is a string, is contains a json object
                if ($null -ne $_.Exception.Response) {
                    # read answer from stream
                    if ($_.Exception.Response.Content.GetType().GetMethods().Name -contains "ReadAsStreamAsync") {
                        $responseStream = $_.Exception.Response.Content.ReadAsStreamAsync().Result
                    }
                    else {
                        $responseStream = $_.Exception.Response.GetResponseStream()
                    }
                    $responseStream = $_.Exception.Response.Content.ReadAsStreamAsync().Result
             
                
                
                    # clean up reader
                    $streamReader.Dispose()

                    if ($errResponse -ne "") {
                        
                        try {
                            $errObject = ConvertFrom-Json $errResponse
                            Write-Error -Exception $_ -Message ($errObject.level + " -> " + $errObject.message)
                            return
                        }
                        catch {
                            # response did not contain valid JSON, return original error message ( see below )
                        }
                        
                    }
                }
                # we did not get any additional info from the error message, just throw the original message
                                        
                # throw original error
                throw $_
            }

            
        }

        END {
            return $Response
        }

    }


function New-ETHGroup {
    <#
    .SYNOPSIS
        Creates a new group in IAM
         
    .DESCRIPTION
        Creates a new group in IAM with the given properties
 
    .PARAMETER Name
        The name of the group
 
    .PARAMETER Description
        The description to give the group
     
    .PARAMETER Targets
        The targets to export the group to. Valid are "AD" and "LDAPS" (both can be specified)
 
    .PARAMETER AdminGroup
        The Admin Group to assign this group to
 
    .EXAMPLE
        New-ETHGroup -Name "biol-micro-isg-testgroup_api" -Description "20191203/asc: TestGroup" -Targets AD -AdminGroup "D-BIOL"
 
        This example creates one group, with the name "biol-micro-isg-testgroup_api" with a description and Admin Group "D-BIOL" exported to AD only.
 
         
    .EXAMPLE
        "biol-micro-testgroup1","biol-micro-testgroup2" | New-ETHGroup -Description "20191203/asc: TestGroup" -Targets AD -AdminGroup "D-BIOL" -Members "aurels","jgrand"
         
        This example creates two groups, both with the same members, "aurels" and "jgrand"
    #>
    param (
        [CmdletBinding()]
        [Parameter(Position = 0, Mandatory = 1, ValueFromPipeline = $true)]
        [string]$Name,
        
        [Parameter(Position = 1, Mandatory = $false)]
        [string]$Description,
        
        [Parameter(Position = 2, Mandatory = $false)]
        [ValidateSet("AD", "LDAPS")]
        [string[]]$Targets,

        [Parameter(Position = 3, Mandatory = $true)]
        [string]$AdminGroup,

        [Parameter(Position = 4, Mandatory = $false)]
        [string[]]$Members
    )

    BEGIN {
        # Check if client is initialized
        Test-IsIAMClientInitialized | Out-Null

        $url = "/groupmgr/group"
    }

    PROCESS {

        $Body = @{
            "name"        = $Name
            "description" = $Description
            "admingroup"  = $AdminGroup
            "members"     = $Members
            "targets"     = $Targets
        }

        Invoke-IAMMethod -Url $url -Method Post -Body $Body -Credentials $script:IAMCreds
    }

    END {

    }    
}



function New-ETHPersona {
    param(
        # Username of Persona parent
        [Parameter(Position = 0, Mandatory = 1)]
        [string]
        $ParentIdentity,

        # New Username
        [Parameter(Position = 1, Mandatory = 1)]
        [string]
        $NewUserName,

        [Parameter(Position = 2)]
        [string]
        $UserComment = "",

        # Initial Password
        [Parameter(Position = 3, Mandatory = 1)]
        [string]
        $InitPwd

    )

    BEGIN {
        $NewUser = [PSCustomObject]@{
            username    = $NewUserName;
            memo        = $UserComment;
            init_passwd = $NewPassword;
        }
    }

    PROCESS {
        Invoke-IAMMethod -Url "/usermgr/person/$ParentIdentity" -Method POST -Credentials $script:IAMCreds -Body $NewUser
    }
}


function Remove-ETHGroup {
    <#
    .SYNOPSIS
        Deletes a group in IAM
         
    .DESCRIPTION
        Deletes a group with the specified name in IAM
 
    .PARAMETER Name
        The name of the group
 
    .EXAMPLE
        Remove-ETHGroup -Name "biol-micro-isg-testgroup_api"
 
        In this example, the group "biol-micro-isg-testgroup_api" is deleted
 
    .EXAMPLE
        Get-ETHGroup "biol-micro-isg-testgroup_api" | Remove-ETHGroup
 
        In this example, the group "biol-micro-isg-testgroup_api" is deleted using the pipeline.
             
     
    #>
    param (
        [CmdletBinding()]
        [Parameter(Position = 0, Mandatory = 1, ValueFromPipelineByPropertyName = "name")]
        [string]$Name
    )

    BEGIN {
        # Check if client is initialized
        Test-IsIAMClientInitialized | Out-Null

        
    }

    PROCESS {

        $url = "/groupmgr/group/$Name"

        Invoke-IAMMethod -Url $url -Method Delete -Credentials $script:IAMCreds

        return $Name
    }

    END {

    }    
}





function Remove-ETHGroupMember {
    [CmdletBinding(SupportsShouldProcess = $true)]
    param (
        [Parameter(Position = 0, Mandatory = 1)]
        [string]$Identity,

        [Parameter(Position = 1, Mandatory = 1)]
        [string[]]$Members
    )

    BEGIN {
        # Check if client is initialized
        Test-IsIAMClientInitialized | Out-Null

        # Validate input arguments
        if (-not ($ExistingGroup = Get-ETHGroup -Identity $Identity)) {
            throw "Group $Identity was not found"
        }

        if ($Members.Count -le 0) {
            throw "No members specified"
        }
    }

    PROCESS {
        $ToRemoveMembers = @($Members | Where-Object { $ExistingGroup.members -contains $_ })

        # Check if there are any members in the group that need to be removed
        if ($ToRemoveMembers.Count -eq 0) {
            Write-Debug "Did not need to remove any members from $Identity"
            return $ExistingGroup
        }

        if ($PSCmdlet.ShouldProcess($Identity)) {
            try {
                return (Invoke-IAMMethod -Url "/groupmgr/group/$Identity/members/del" -Method Put -Body $ToRemoveMembers -Credentials $script:IAMCreds)
            }
            catch {
                throw "Could not update group $Identity"
            }
        }
    }

    END { }
}


function Remove-ETHMaillist {
    [CmdletBinding(SupportsShouldProcess = $true)]
    param (
        # List Name
        [Parameter(Position = 0, ParameterSetName = "ByName")]
        [string]$Identity,

        [Parameter(ValueFromPipeline = $true, ParameterSetName = "ByPipeline")]
        [psobject]$MailObject

    )

    BEGIN {
        Test-IsIAMClientInitialized | Out-Null

        if ($MailObject -ne $null) {
            $Identity = $MailObject.listName
        }

        $Url = "/mailinglists/$Identity"
    }

    PROCESS {
        if ($PSCmdlet.ShouldProcess("Deleting Mailliglist $Identity")) {
            return (Invoke-IAMMethod -Url $Url -Method Delete -Credentials $script:IAMCreds)
        }
    }
}


function Remove-ETHMaillistMember {
    param (
        # List Name
        [Parameter(Position = 0, Mandatory = $true)]
        [string]$Identity,

        # Member to add or remove
        [Parameter(Position = 1, Mandatory = $true, ValueFromPipeline = $true)]
        [string[]]$Members
    )

    BEGIN {
        Test-IsIAMClientInitialized | Out-Null

        $Url = "/mailinglists/$Identity/members/del"
    }

    PROCESS {
        return (Invoke-IAMMethod -Url $Url -Body $Members -Method Put -Credentials $script:IAMCreds)
    }


}


function Reset-ETHUserPassword {
    param (
        [Parameter(Position = 0, Mandatory = 1)]
        [string]$Identity,

        # Parameter help description
        [Parameter(Position = 1, Mandatory = 1)]
        [securestring]$NewPassword,

        [Parameter(Position = 2, Mandatory = 1)]
        [string]$ServiceName
    )

    BEGIN {
        $BSTR = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($NewPassword)
        $PlainText = [System.Runtime.InteropServices.Marshal]::PtrToStringAuto($BSTR)
    }

    PROCESS {

        try {
            $result = Invoke-IAMMethod -Url "/usermgr/user/$Identity/service/$ServiceName/password" -Body @{password = $PlainText } -Credentials $script:IAMCreds -Method Put
            return $result;
        }
        catch {
            Write-Error "Could not reset the password of the user $Identity, Error: $_"
            return;
        }
    }
}


function Set-ETHGroup {
    <#
    .SYNOPSIS
        Edits an existing group in IAM
         
    .DESCRIPTION
        Sets specific properties of an existing group in IAM
 
    .PARAMETER Identity
        The name of the group
 
    .PARAMETER NewName
        Rename the group to this new name
 
    .PARAMETER Description
        Set the description of this group
     
    .PARAMETER Targets
        !!Not implemented in IAM!!
        The targets to export the group to. Valid are "AD" and "LDAPS" (both can be specified)
     
    .PARAMETER AdminGroup
        !!Not implemented in IAM!!
        The Admin Group to assign this group to
 
    .EXAMPLE
        Set-ETHGroup -Identity "biol-micro-api_test" -Description "NewDescription"
         
        Change the description of the group "biol-micro-api_test".
     
    #>
    param (
        [CmdletBinding()]
        [Parameter(Position = 0, Mandatory = $true, ValueFromPipelineByPropertyName = "name")]
        [string]$Identity,

        [Parameter(Position = 1, Mandatory = $false)]
        [string]$NewName,
        
        [Parameter(Position = 2, Mandatory = $false)]
        [string]$Description,
        
        [Parameter(Position = 3, Mandatory = $false)]
        [ValidateSet("AD", "LDAPS")]
        [string[]]$Targets,

        [Parameter(Position = 4, Mandatory = $false)]
        [string]$AdminGroup

    )

    BEGIN {
        # Check if client is initialized
        Test-IsIAMClientInitialized | Out-Null

        
    }

    PROCESS {

        $url = "/groupmgr/group/$Identity"

        $Body = @{ }

        if ($NewName) { $Body["name"] = $NewName }
        if ($Description) { $Body["description"] = $Description }
        if ($Targets) { $Body["targets"] = $Targets }
        if ($AdminGroup) { $Body["admingroup"] = $AdminGroup }

        if ($body.Count -gt 0) {
            Invoke-IAMMethod -Url $url -Method Put -Body $Body -Credentials $script:IAMCreds -ea Continue
        }

        $Identity = if ($NewName) { $NewName } else { $Identity }
        Get-ETHGroup $Identity
    }

    END {

    }    
}



function Set-ETHGroupMember {
    <#
    .SYNOPSIS
        Sets the members of an ETH group to the specified member list
         
    .DESCRIPTION
        Removes / Adds members to the given group until the memberlist is equal to the one submitted
        You can specify either usernames or *custom* groups
 
    .PARAMETER Identity
        The group to edit
 
    .PARAMETER Members
        The list of members to set the group memberlist to
 
    .EXAMPLE
        PS> Set-ETHGroupMember -Identity biol-micro-isg -Members @("aurels","ausc")
 
    .EXAMPLE
        PS> Set-ETHGroupMember -Identity biol-micro-isg -Members @("biol-micro-isg-sadm","aurels")
 
        Added: {"aurels", "ausc"}
        Removed: {}
        Kept: {}
 
    .OUTPUTS
        pscustomobject. Returns a custom object with 3 properties Added, Removed and Kept to show what the cmdlet did
 
    #>
    [CmdletBinding(SupportsShouldProcess = $true, HelpUri = "https://gitlab.ethz.ch/aurels/iam-powershell/tree/master/docs/Set-ETHGroupMember.md")]
    [OutputType([PSCustomObject])]
    param(
        # Group Name
        [Parameter(Position = 0, Mandatory = $true)]
        [string]$Identity,

        # Members to sync to
        [Parameter(Position = 1, Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = "Name")]
        [AllowEmptyCollection()]
        [string[]]
        $Members
    )

    BEGIN {
        # Check if client is initialized
        Test-IsIAMClientInitialized | Out-Null

        try {
            $ExistingMembers = @(Get-ETHGroupMember $Identity)
        }
        catch {
            throw "Could not find group $Identity"
        }
    }

    PROCESS {
        # get members to be removed & added
        $MemberCompare = Compare-GroupMembers -ExistingMembers $ExistingMembers -NewMembers $Members
        $ToBeAdded = $MemberCompare.ToAdd
        $ToBeRemoved = $MemberCompare.ToRemove

        try {

            if ($ToBeAdded.Count -gt 0) {
                if ($PSCmdlet.ShouldProcess($Identity, "Add-ETHGroupMember")) {
                    # Discard output of Add-ETHGroupMember
                    $null = Add-ETHGroupMember -Identity $Identity -Members $ToBeAdded
                }
            }

            if ($ToBeRemoved.Count -gt 0) {
                if ($PSCmdlet.ShouldProcess($Identity, "Remove-ETHGroupMember")) {
                    $null = Remove-ETHGroupMember -Identity $Identity -Members $ToBeRemoved
                }
            }

        }
        catch {
            throw "Failed to update group membership of group $Identity, try again to restore group integrity!`r`nError: $_"
        }

        return @{
            Added   = $ToBeAdded;
            Removed = $ToBeRemoved;
            Kept    = $MemberCompare.ToKeep;
        }
        
    }

    END { }
}


function Set-ETHMaillistMembers {
    [CmdletBinding()]
    param (
        # Maillist name
        [Parameter(Position = 0, Mandatory = $true)]
        [string]
        $Identity,

        # Members
        [Parameter(Position = 1, Mandatory = $true)]
        [string[]]$Members
    )

    BEGIN {
        Test-IsIAMClientInitialized | Out-Null

        try {
            $ExistingMembers = @((Get-ETHMaillistMember -Identity $Identity).name)
        }
        catch {
            throw "Could not find Mailinglist $Identity"
        }
    }

    PROCESS {
        $MemberCompare = Compare-GroupMembers -ExistingMembers $ExistingMembers -NewMembers $Members
        $ToAddMembers = $MemberCompare.ToAdd
        $ToRemoveMembers = $MemberCompare.ToRemove

        # Add members
        try {
            if ($ToAddMembers.Count -gt 0) {
                $null = Add-ETHMaillistMember -Identity $Identity -Members $ToAddMembers
                Write-Debug "Successfully added $($ToAddMembers.Count) new members to Mailinglist $Identity"
            }
        }
        catch {
            Write-Error "Failed to add $($ToAddMembers.Count) members to mailinglist. $([System.Environment]::NewLine)Error: $_"
            return
        }

        # Remove members
        try {
            if ($ToRemoveMembers.Count -gt 0) {
                $null = Remove-ETHMaillistMember -Identity $Identity -Members $ToRemoveMembers
                Write-Debug "Successfully removed $($ToRemoveMembers.Count) members from Mailinglist $Identity"
            }
        }
        catch {
            Write-Error "Failed to remove $($ToRemoveMembers.Count) members from mailinglist. $([System.Environment]::NewLine)Error: $_"
            return
        }

        return @{
            Added   = $ToAddMembers;
            Removed = $ToRemoveMembers;
            Kept    = $MemberCompare.ToKeep;
        }
    }
}



function Set-ETHUser {
    [CmdletBinding()]
    param (
        [Parameter(Position = 0, Mandatory = 1)]
        [string]$Identity,
        [Parameter(Position = 1, Mandatory = 1, ValueFromPipeline = 1)]
        [psobject]$User,
        [Parameter(Position = 2, Mandatory = 0)]
        [string]$Service = "Mailbox"
    )


    # Check if client is initialized
    $null = Test-IsIAMClientInitialized

    $sourceUser = Get-ETHUser -Identity $Identity
    $changedProperties = Get-ObjectDiffs $sourceUser $User

    if ($changedProperties.Count -eq 0){
        # nothing to do
        return $sourceUser
    }


    Invoke-IAMMethod -Url "/usermgr/user/$Identity/service/$Service" -Method Put -Body $changedProperties -Credentials $script:IAMCreds
    
}


function Set-ETHUserITService {
    param (
        # ETH user name
        [Parameter(Position = 0, Mandatory = 1)]
        [string]
        $Identity,

        # IT Service Name
        [Parameter(Position = 1, Mandatory = 1)]
        [string]
        $ITServiceName,

        # Body
        [Parameter(Position = 2, Mandatory = 1)]
        [psobject]
        $Body
    )
    BEGIN {
        # Check if client is initialized
        Test-IsIAMClientInitialized | Out-Null
    }

    PROCESS {
        return (Invoke-IAMMethod -Url "/usermgr/user/$Identity/service/$ITServiceName" -Method Put -Credentials $script:IAMCreds -Body $Body)
    }
}


function Sync-ETHGroupMember {

    <#
    .SYNOPSIS
    Synchronizes users from multiple groups and mailing lists to a group and a mailinglist
     
    .DESCRIPTION
    Copies all **users** from the source groups/lists to the given destination group/list
     
    .PARAMETER SourceGroups
    The list of groups to read members from
     
    .PARAMETER SourceLists
    The list of mailinglists to read members from
     
    .PARAMETER DestGroup
    The destination group that will be set to all members from the given groups / lists
 
    .PARAMETER DestList
    The destination mailinglist that will be set to all members from the given groups / lists
 
    .EXAMPLE
    PS> Sync-ETHGroupMember -SourceGroups "biol-micro-isg" -DestList "MICRO_IT_STAFF"
 
    Copies all members from the group "biol-micro-isg" to the Maillinglist "MICRO_IT_STAFF"
     
    .EXAMPLE
    PS> Sync-ETHGroupMember -SourceLists "MICRO_IT_STAFF","MICRO_AD_STAFF" -DestList "MICRO_STAFF"
 
    Copies all members from the source lists to the destination list
 
    .EXAMPLE
    PS> Sync-ETHGroupMember -SourceLists "MICRO_IT_STAFF","MICRO_AD_STAFF" -SourceGroups "biol-micro-institute" -DestGroup "biol-micro-institute"
 
    Adds all members from the given lists to the destination group without removing users
 
    .OUTPUTS
        System.Collections.Hashtable
        A hashtable with a report on each group/list that was modified and what was done (Add / Remove / Keep Members)
     
    #>


    [CmdletBinding(SupportsShouldProcess = $true, DefaultParameterSetName = "ToGroup")]
    [OutputType([System.Collections.HashTable])]
    param(
        # Group Name
        [Parameter(Position = 0)]
        [Alias("ReferenceGroups")]
        [string[]]$SourceGroups,

        # Mailinglist to sync from
        [Parameter(Position = 1)]
        [string[]]$SourceLists,

        # Group to sync members to
        [Parameter(Position = 2, ParameterSetName = "ToGroup", Mandatory = 1)]
        [Parameter(ParameterSetName = "ToBoth", Mandatory = 1)]
        [Alias("SyncGroup")]
        [string]$DestGroup,

        # List to sync members to
        [Parameter(Position = 3, ParameterSetName = "ToList", Mandatory = 1)]
        [Parameter(ParameterSetName = "ToBoth", Mandatory = 1)]
        [string]$DestList,

        # Falls back to AD if group cannot be loaded via IAM
        [Parameter()]
        [switch]$AllowADFallback
    )

    BEGIN {

        # Validate input arguments
        if ($SourceGroups.Count -eq 0 -and $SourceLists.Count -eq 0) {
            throw "At least one source group or list has to be specified!"
        }

        if ([string]::IsNullOrWhiteSpace($DestGroup) -and [string]::IsNullOrWhiteSpace($DestList)) {
            throw "At least one destination group has to be specified!"
        }

        if ($AllowADFallback -and (Get-Module).Name -notcontains "ActiveDirectory") {
            try {
                Import-Module ActiveDirectory
            }
            catch {
                throw "To use the ActiveDirectory fallback, install RSAT tools!"
            }
        }

        # Check if client is initialized
        Test-IsIAMClientInitialized | Out-Null

        # Validate destination group exists
        if ($DestGroup) {
            try {
                $null = Get-ETHGroup -Identity $DestGroup # discard output
            }
            catch {
                throw "Could not find group $DestGroup"
            }
        }

        if ($DestList) {
            try {
                $null = Get-ETHMaillist -Identity $DestList # discard output
            }
            catch {
                throw "Could not find list $DestList"
            }
        }

        $ListsToProcess = @()
        $GroupsToProcess = @()

        if ($SourceLists.Count -gt 0) { 
            $ListsToProcess = @($SourceLists | ForEach-Object { [PSCustomObject]@{Name = $_; Type = "List" } }) 
        }

        if ($SourceGroups.Count -gt 0) {
            $GroupsToProcess = @($SourceGroups | ForEach-Object { [PSCustomObject]@{Name = $_; Type = "Group" } })
        }
    }

    PROCESS {
        
        # Store all members from the different sourcegroups in a hashset,
        # so that duplicates are automatically eliminated
        $AllMembersList = New-Object 'System.Collections.Generic.HashSet[string]' 
        
        foreach ($Source in @($ListsToProcess + $GroupsToProcess)) {
            # retrieve type for output messages
            $SourceType = $Source.Type
            try {
                switch ($SourceType) {
                    "Group" { 
                        # Get Group members
                        $Group = Get-ETHGroup $Source.Name
                        $AllMembersList.UnionWith([string[]]@($Group.members))
                    }
                    "List" {
                        # Get Maillist members
                        $ListMembers = Get-ETHMaillistMember $Source.Name | Where-Object objectClass -eq "user"
                        $AllMembersList.UnionWith([string[]]@($ListMembers.name)) # add all members to the list
                    }
                    Default {
                        # Invalid
                        throw "GroupType '$SourceType' invalid. Valid are 'List','Group'!"
                    }
                }
            
            }
            catch {
                # Group / List was not found in IAM
                # Perform ad fallback if needed
                if (-not $AllowADFallback) {
                    throw "Could not find $SourceType '$($Source.Name)' in IAM"
                }
                try {
                    # get all users from AD group as fallback
                    $Members = Get-ADGroupMember -Identity $Source.Name | Where-Object objectClass -eq "user"
                    $AllMembersList.UnionWith([string[]]($Members.name))
                }
                catch {
                    throw "Could not find $SourceType '$($Source.Name)' in AD"
                }
            
            }
        }

        # Store changes in a hashtable for every group modified
        $Changes = @{ }


        if ($DestGroup -ne "" -and $PSCmdlet.ShouldProcess($DestGroup, "Set-ETHGroupMember")) {
            $Changes.Add($DestGroup, (Set-ETHGroupMember -Identity $DestGroup -Members $AllMembersList))
        }

        if ($DestList -ne "" -and $PSCmdlet.ShouldProcess("$DestList", "Set-ETHMaillistMembers")) {
            $Changes.Add($DestList, (Set-ETHMaillistMembers -Identity $DestList -Members $AllMembersList))
        }

        return $Changes
    }

    END {

    }
}



function Test-ETHCredentials {
    [CmdletBinding()]
    param (
        [Parameter(Position = 0, Mandatory = 1)]
        [pscredential]$Credentials
    )
    
    $script:IAMCreds = $Credentials
    
    try {    
        Get-ETHUser -Identity $Credentials.UserName -ErrorAction Stop
        return $true
    }
    catch {
        # write error to error stream as non-terminating error
        Write-Error $_
        return $false
    }
    finally {
        $script:IAMCreds = $null
    }
    
}


$script:IAMCreds = $null
$script:ApiHost = "" # will set during initialization
$script:DebugMode = $false

if ($PSVersionTable.PSVersion.Major -le 5){
    # set TLS1.2 as default when running in PSv5
    # if TLS1.3 is out, this should be specified
    # https://docs.microsoft.com/en-us/security/engineering/solving-tls1-problem#update-windows-powershell-scripts-or-related-registry-settings
    [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12
}


Export-ModuleMember -Function 'Invoke-IAMMethod','Add-ETHGroupmember','Find-ETHGroup','Get-ETHGroup','Get-ETHGroupMember','New-ETHGroup','Remove-ETHGroup','Remove-ETHGroupMember','Set-ETHGroup','Set-ETHGroupMember','Sync-ETHGroupMember','Add-ETHMaillistMember','Clear-ETHMaillistMember','Get-ETHMaillist','Get-ETHMaillistMember','Remove-ETHMaillist','Remove-ETHMaillistMember','Set-ETHMaillistMembers','Get-ETHPerson','Get-ETHPersonServices','New-ETHPersona','Add-ETHUserITService','Add-ETHUserMailAlias','Get-ETHUser','Get-ETHUserGroupMembership','Reset-ETHUserPassword','Set-ETHUser','Set-ETHUserITService','Initialize-IAMClient','Test-ETHCredentials'