WhiteboardAdmin.psm1
|
Set-Variable AdalClientId -option Constant -value '1950a258-227b-4e31-a9cf-717495945fc2' Set-Variable AdalRedirectUri -option Constant -value 'https://login.microsoftonline.com/common/oauth2/nativeclient' <# .SYNOPSIS Gets one or more Whiteboards from the Microsoft Whiteboard service and returns them as objects. .PARAMETER UserId The ID of the user account to query Whiteboards for. .PARAMETER WhiteboardId (Optional) The ID of a specific Whiteboard to query, if not specified all whiteboards are queried. .PARAMETER ForceAuthPrompt (Optional) Always prompt for auth. Use to ignore cached credentials. .EXAMPLE Get-Whiteboard -UserId 00000000-0000-0000-0000-000000000001 Get all of a user's Whiteboards. #> function Get-Whiteboard { [CmdletBinding()] param( [Parameter(Mandatory=$true)] [Guid]$UserId, [Parameter(Mandatory=$false)] [Guid]$WhiteboardId, [Parameter(Mandatory=$false)] [switch]$ForceAuthPrompt) $response = Invoke-WhiteboardRequest ` -Method GET ` -Endpoint "api/v1.0/users/$UserId/whiteboards" ` -ContentType 'application/json' ` -ForceAuthPrompt:$ForceAuthPrompt if ($null -eq $WhiteboardId) { return $response } # Filter client-side since there is no admin GET API that addresses a single whiteboard. return $response | Where-Object {$_.id -eq $WhiteboardId} } <# .SYNOPSIS Gets all of the board owners from the Microsoft Whiteboard service in a given geography. The response is a JSON object with the following properties: Items: A list of strings containing the owner ids ContinuationToken: A continuation token to pass in future calls to this API. The token can expire when new results are computed. In this case a 410 is returned, and the call should be retried with a null continuation token. When this situation occurs, duplicate owner ids may be returned. If null, there are no more owners to return. Geography: The geography for which this results were calculated. TenantId: The tenant ID these owners belong to. This data is not live calculated, and instead is based on cached values that are calculated every 2-4 weeks. As a result, admins should be aware that this may be an incomplete list. .PARAMETER Geography The geography to look up whiteboards in. Valid options are "Europe", "Australia", and "Worldwide". "Worldwide" contains all data not stored in Europe or Australia. At the time of writing, this data is stored in the US. .PARAMETER ContinuationToken (Optional) A continuation token based on the last time this function was called. Due to the large volume of boards in a tenant, results are returned in chunks at a time, with a continuation token to signify where to pick up from. To start from the beginning, pass in null. .PARAMETER ForceAuthPrompt (Optional) Always prompt for auth. Use to ignore cached credentials. #> function Get-WhiteboardOwners { [CmdletBinding()] param( [Parameter(Mandatory=$true)] [ValidateSet('Worldwide', 'Europe', 'Australia')] [string]$Geography, [Parameter(Mandatory=$false)] [string]$ContinuationToken = $null, [Parameter(Mandatory=$false)] [switch]$ForceAuthPrompt) $headers = @{"x-ms-continuation"=$ContinuationToken "x-ms-continuationToken"=$ContinuationToken } $response = Invoke-WhiteboardRequest ` -Method GET ` -Endpoint "api/v1.0/admin/whiteboardowners/geographies/$Geography" ` -ContentType 'application/json' ` -ForceAuthPrompt:$ForceAuthPrompt ` -Headers $headers return $response } <# .SYNOPSIS Sets the owner for a Whiteboard. .PARAMETER WhiteboardId The Whiteboard for which the owner is being changed. .PARAMETER OldOwnerId The ID of the previous owner. .PARAMETER NewOwnerId The ID of the new owner. .PARAMETER ForceAuthPrompt (Optional) Always prompt for auth. Use to ignore cached credentials. .EXAMPLE Set-WhiteboardOwner -OldOwnerId 00000000-0000-0000-0000-000000000001 -NewOwnerId 00000000-0000-0000-0000-000000000002 Move a Whiteboard from one user to another. #> function Set-WhiteboardOwner { [CmdletBinding( SupportsShouldProcess = $true, ConfirmImpact='High')] param( [Parameter(Mandatory=$true)] [Guid]$WhiteboardId, [Parameter(Mandatory=$true)] [Guid]$OldOwnerId, [Parameter(Mandatory=$true)] [Guid]$NewOwnerId, [Parameter(Mandatory=$false)] [switch]$ForceAuthPrompt) if ($PSCmdlet.ShouldProcess("Whiteboard: $WhiteboardId")) { return Invoke-WhiteboardRequest ` -Method PATCH ` -Endpoint "api/v1.0/users/$OldOwnerId/whiteboards/$WhiteboardId" ` -ContentType 'application/json-patch+json' ` -Body (ConvertTo-Json -Compress @(@{"op"="replace"; "path"="/OwnerId"; "value"=$NewOwnerId })) ` -ForceAuthPrompt:$ForceAuthPrompt } } <# .SYNOPSIS Transfer ownership of all Whiteboards owned by a user to another user. .PARAMETER OldOwnerId The ID of the previous owner. .PARAMETER NewOwnerId The ID of the new owner. .PARAMETER WhatIf Execute the command without making any actual changes. Only calls read methods on the REST service. .PARAMETER ForceAuthPrompt (Optional) Always prompt for auth. Use to ignore cached credentials. .EXAMPLE Invoke-TransferAllWhiteboards -OldOwnerId 00000000-0000-0000-0000-000000000001 -NewOwnerId 00000000-0000-0000-0000-000000000002 -WhatIf Check how many Whiteboards will be transferred without transferring them. .EXAMPLE Invoke-TransferAllWhiteboards -OldOwnerId 00000000-0000-0000-0000-000000000001 -NewOwnerId 00000000-0000-0000-0000-000000000002 Transfer (and prompt before performing any write actions). #> function Invoke-TransferAllWhiteboards { [CmdletBinding( SupportsShouldProcess = $true, ConfirmImpact='High')] param( [Parameter(Mandatory=$true)] [Guid]$OldOwnerId, [Parameter(Mandatory=$true)] [Guid]$NewOwnerId, [Parameter(Mandatory=$false)] [switch]$ForceAuthPrompt) $whiteboards = Get-Whiteboard -UserId $OldOwnerId -ForceAuthPrompt:$ForceAuthPrompt # Only transfer Whiteboards actually owned by this Id $whiteboardsOwned = @($whiteboards | Where-Object { [Guid]::Parse($_.ownerId) -eq $OldOwnerId }) Write-Verbose "Found $($whiteboardsOwned.Length) Whiteboards for owner $($OldOwnerId)" if ($PSCmdlet.ShouldProcess("Whiteboards for Owner: $OldOwnerId")) { $whiteboardsOwned | ForEach-Object { Set-WhiteboardOwner -OldOwnerId $OldOwnerId -NewOwnerId $NewOwnerId -WhiteboardId $_.id -Confirm:$false } } } <# .SYNOPSIS Deletes the specified Whiteboard for the given user from the Microsoft Whiteboard service. If the user is the owner of the whiteboard, the entire whiteboard will be deleted. If the user has joined the whiteboard but does not own it, they will be removed and the whiteboard will still be accessible by others. .PARAMETER UserId The ID of the user account to delete the Whiteboard from. .PARAMETER WhiteboardId The ID of a specific Whiteboard to delete. .PARAMETER ForceAuthPrompt (Optional) Always prompt for auth. Use to ignore cached credentials. .EXAMPLE Remove-Whiteboard -UserId 00000000-0000-0000-0000-000000000001 -WhiteboardId 00000000-0000-0000-0000-000000000002 Deletes the whiteboard #> function Remove-Whiteboard { [CmdletBinding()] param( [Parameter(Mandatory=$true)] [Guid]$UserId, [Parameter(Mandatory=$true)] [Guid]$WhiteboardId, [Parameter(Mandatory=$false)] [switch]$ForceAuthPrompt) if ($PSCmdlet.ShouldProcess("Delete whiteboard $WhiteboardId for User $UserId?")) { Invoke-WhiteboardRequest ` -Method DELETE ` -Endpoint "api/v1.0/users/$UserId/whiteboards/$WhiteboardId" ` -ContentType 'application/json' ` -ForceAuthPrompt:$ForceAuthPrompt } } <# .SYNOPSIS Gets tenant settings from the Microsoft Whiteboard service and returns them as an object. .PARAMETER ForceAuthPrompt (Optional) Always prompt for auth. Use to ignore cached credentials. .EXAMPLE Get-WhiteboardSettings Get the users Whiteboard settings. #> function Get-WhiteboardSettings { [CmdletBinding()] param( [Parameter(Mandatory=$false)] [switch]$ForceAuthPrompt) $response = Invoke-WhiteboardRequest ` -Method GET ` -Endpoint "api/v1.0/whiteboards/enabled" ` -ForceAuthPrompt:$ForceAuthPrompt return $response } <# .SYNOPSIS Sets the tenant settings for the Microsoft Whiteboard services. .PARAMETER Settings The object to use as Whiteboard Settings. Should be retrieved via Get-WhiteboardSettings .PARAMETER ForceAuthPrompt (Optional) Always prompt for auth. Use to ignore cached credentials. .EXAMPLE $settings = Get-WhiteboardSettings $settings.isEnabledGa = $true Set-WhiteboardSettings -Settings $settings Enables Microsoft Whiteboard for your tenant. #> function Set-WhiteboardSettings { [CmdletBinding()] param( [Parameter(Mandatory=$true)] [psobject]$Settings, [Parameter(Mandatory=$false)] [switch]$ForceAuthPrompt) $jsonSettings = ConvertTo-Json $Settings $response = Invoke-WhiteboardRequest ` -Method POST ` -Endpoint "api/v1.0/whiteboards/enabled" ` -ContentType 'application/json' ` -Body $jsonSettings ` -ForceAuthPrompt:$ForceAuthPrompt return $response } <# .SYNOPSIS Gets all the whiteboards associated with a tenant in a specific geography. .PARAMETER Geography The geography to grab the whiteboards from. Valide options are Australia, Europe, or Worldwide. .PARAMETER IncrementalRunName (Optional) Save incremental progess as the cmdlet runs. Use to resume a partially completed Get-WhiteboardsForTenant. Use the same run name on later calls to continue a previously cancelled/failed run Writes progress and results to txt files in the current directory: "Whiteboards-*.txt" contains the incremental results containing whiteboards in JSON for the tenant where * is the provided RunName "WhiteboardAdminRun-*.txt" contains the state of the current where * is the provided RunName. This file should not be modified manually .PARAMETER ForceAuthPrompt (Optional) Always prompt for auth. Use to ignore cached credentials. .EXAMPLE Get-WhiteboardsForTenant -Geography Europe Gets all the whiteboards associated with the caller's tenant in Europe #> function Get-WhiteboardsForTenant { [CmdletBinding()] param( [Parameter(Mandatory=$true)] [ValidateSet('Worldwide', 'Europe', 'Australia')] [string]$Geography, [Parameter(Mandatory=$false)] [string]$IncrementalRunName, [Parameter(Mandatory=$false)] [switch]$ForceAuthPrompt) # helper function for calling the Get-WhiteboardOwners API wrapped in a retry function Get-WhiteboardOwnersWithRetry( [Parameter(Mandatory=$true)] [string]$Geography, [Parameter(Mandatory=$false)] [string]$ContinuationToken, [Parameter(Mandatory=$false)] [switch]$ForceAuthPrompt) { $retryCount = 0 while ($true) { try { $results = Get-WhiteboardOwners -Geography $Geography -ContinuationToken $ContinuationToken -ForceAuthPrompt:$ForceAuthPrompt return $results } catch { $retryCount++ if ($retryCount -gt 4) { throw $_.Exception } } } } # helper function for calling the Get-Whiteboard API for a user wrapped in a retry and filtering for # a specific geography. function Get-WhiteboardsInGeographyForUser( [Parameter(Mandatory=$true)] [string]$OwnerId, [Parameter(Mandatory=$true)] [string]$Geography) { $retryCount = 0 $baseApi = "" if ($Geography -eq 'Worldwide') { $baseApi = "us*" } elseif ($Geography -eq 'Europe') { $baseApi = "eu*" } elseif ($geography -eq 'Australia') { $baseApi = "au*" } while ($true) { try { return Get-Whiteboard -UserId $ownerId | Where-Object -Property baseApi -like $baseApi } catch { $retryCount++ if ($retryCount -gt 4) { throw $_.Exception } } } } # A helper function to set up files for incremental results between runs. Allows for continuing from a previously cancelled run function Set-WhiteboardsIncrementalRun( [Parameter(Mandatory=$true)] [string]$ContinuationTokenFileName, [Parameter(Mandatory=$true)] [string]$WhiteboardResultsFileName) { if(Test-Path -Path $ContinuationTokenFileName) { $existingContinuationToken = Get-Content -Path $ContinuationTokenFileName if(-not [string]::IsNullOrEmpty($existingContinuationToken)) { Write-Host "Previous run detected. Continuing get-whiteboard enumeration`n" return $existingContinuationToken } else { Write-Warning "$ContinuationTokenFileName is corrupted. Whiteboard enumeration will start from the beginning.`n" } } New-Item -Name $WhiteboardResultsFileName -ItemType "file" -Force | Out-Null Write-Host "Starting new get-whiteboard enumeration and clearing any previous run data`n" Write-Host "Whiteboards will be added to $WhiteboardResultsFileName in the current directory`n" Write-Host "The run state will be written to $ContinuationTokenFileName. This file does not contain readable data, but necessary for incremental results. To resume a previous cmdlet call, make the same call with the same parameters`n" return $null } $continuationToken = $null # Set up files to write the results for incremental runs. Allows for continuing from a previously cancelled run $incrementalResults = -not [string]::IsNullOrEmpty($IncrementalRunName) $continuationTokenFileName = "WhiteboardAdminRun-$IncrementalRunName.txt" $whiteboardResultsFileName = "Whiteboards-$IncrementalRunName.txt" if($incrementalResults) { $continuationToken = Set-WhiteboardsIncrementalRun -ContinuationTokenFileName $continuationTokenFileName -WhiteboardResultsFileName $whiteboardResultsFileName } $whiteboardsAll = @() do { Write-Host "Getting page of owners`n" $results = Get-WhiteboardOwnersWithRetry -Geography $Geography -ContinuationToken $continuationToken -ForceAuthPrompt:$ForceAuthPrompt $ForceAuthPrompt = $false $continuationToken = $results.continuationToken foreach($ownerId in $results.items) { Write-Host "Adding boards for owner $ownerId`n" $whiteboards = Get-WhiteboardsInGeographyForUser -OwnerId $ownerId -Geography $Geography if($incrementalResults) { foreach($whiteboard in $whiteboards) { Add-Content -Path $whiteboardResultsFileName -Value (ConvertTo-Json $whiteboard -Compress -Depth 1) } } else { $whiteboardsAll = $whiteboardsAll + $whiteboards } } # Store the continuation token if($incrementalResults) { $continuationToken | Out-File $continuationTokenFileName } } while(-not [string]::IsNullOrEmpty($continuationToken)) if($incrementalResults) { Remove-Item $continuationTokenFileName Write-Host "Completed Get-WhiteboardsForTenant. Results stored in $whiteboardResultsFileName" return } else { return $whiteboardsAll } } function Invoke-WhiteboardRequest( [Parameter(Mandatory=$true)] [Microsoft.PowerShell.Commands.WebRequestMethod]$Method, [Parameter(Mandatory=$true)] [string]$Endpoint, [Parameter(Mandatory=$false)] [string]$ContentType = $null, [Parameter(Mandatory=$false)] [string]$Body = $null, [Parameter(Mandatory=$false)] [hashtable]$Headers = $null, [Parameter(Mandatory=$false)] [switch]$ForceAuthPrompt) { # Make sure TLS 1.2 is a supported protocol since this is all the whiteboard service supports. [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol, [Net.SecurityProtocolType]::Tls12 if ($Headers -ne $null) { $Headers['Authorization'] = Get-WhiteboardAuthenticationHeader -ForceAuthPrompt:$ForceAuthPrompt } else { $Headers = @{ 'Authorization' = Get-WhiteboardAuthenticationHeader -ForceAuthPrompt:$ForceAuthPrompt } } $invokeRestMethodArgs = @{ Method = $Method Uri = "https://$(Get-WhiteboardHostName -Environment $env:Environment)/$Endpoint" ContentType = $ContentType UserAgent = "WhiteboardAdminModule/$((Get-Module WhiteboardAdmin | Select-Object -First 1).Version)" Headers = $Headers } if (-Not [string]::IsNullOrEmpty($Body)) { $invokeRestMethodArgs["Body"] = $Body } try { return Invoke-RestMethod @invokeRestMethodArgs } catch [System.Net.WebException] { $ex = $_.Exception if ($ex.Status -ne [System.Net.WebExceptionStatus]::ProtocolError) { # Rethrow the exception if the failure wasn't caused by a protocol error. throw $ex } $response = $ex.Response if ($response.StatusCode -ne [System.Net.HttpStatusCode]::Unauthorized) { # Rethrow the exception if the failure wasn't caused by a unauthroized response throw $ex } # Try to deserialize the adal claims challenge. # This can happen if the endpoint makes an onbehalf # of request that requires additional claims (like MFA) try { $stream = $response.GetResponseStream() $streamReader = [System.IO.StreamReader]::new($stream) $content = $streamReader.ReadToEnd() $claims = ($content | ConvertFrom-Json).claims if ([string]::IsNullOrEmpty($claims)) { throw $ex } } catch { throw $ex } $invokeRestMethodArgs['Headers']['Authorization'] = Get-WhiteboardAuthenticationHeader -Claims $claims -ForceAuthPrompt:$ForceAuthPrompt return Invoke-RestMethod @invokeRestMethodArgs } } function Get-WhiteboardAuthenticationHeader( [Parameter(Mandatory=$false)] [string]$Claims, [Parameter(Mandatory=$false)] [switch]$ForceAuthPrompt) { $whiteboardResourceId = Get-WhiteboardResourceId -Environment $env:Environment $aadAuthority = Get-AadAuthority -Environment $env:Environment $authContext = [Microsoft.IdentityModel.Clients.ActiveDirectory.AuthenticationContext]::new($aadAuthority) $promptBehavior = if ($ForceAuthPrompt -eq $true) { [Microsoft.IdentityModel.Clients.ActiveDirectory.PromptBehavior]::Always } else { [Microsoft.IdentityModel.Clients.ActiveDirectory.PromptBehavior]::Auto } $platformParameters = [Microsoft.IdentityModel.Clients.ActiveDirectory.PlatformParameters]::new($promptBehavior) $userIdentifier = [Microsoft.IdentityModel.Clients.ActiveDirectory.UserIdentifier]::AnyUser if (-Not ([string]::IsNullOrEmpty($Claims))) { $adalQueryString = "claims=$Claims" } $result = $authContext.AcquireTokenAsync($whiteboardResourceId, $AdalClientId, $AdalRedirectUri, $platformParameters, $userIdentifier, $adalQueryString).Result return $result.CreateAuthorizationHeader(); } function Get-WhiteboardHostName( [Parameter(Mandatory=$false)] [ValidateSet('Prod', 'Int', 'Dev', '')] [string] $Environment) { switch ($Environment) { 'Dev' { return "dev.whiteboard.microsoft.com"} 'Int' { return "int.whiteboard.microsoft.com"} default { return "whiteboard.microsoft.com" } } } function Get-WhiteboardResourceId( [Parameter(Mandatory=$false)] [ValidateSet('Prod', 'Int', 'Dev', '')] [string] $Environment) { switch ($Environment) { 'Int' { return "https://int.whiteboard.microsoft.com"} default { return "https://whiteboard.microsoft.com" } } } function Get-AadAuthority( [Parameter(Mandatory=$false)] [ValidateSet('Prod', 'Int', 'Dev', '')] [string] $Environment) { switch ($Environment) { 'Int' { return "https://login.windows-ppe.net/common"} default { return "https://login.microsoftonline.com/common" } } } |