Functions/Connect-AdbServer.ps1
|
<#
.SYNOPSIS Login to the adb server. The session is stored in the module context and is returned as a session object if required. .DESCRIPTION The adb server is specified by the uri. The uri may only contain the host and the protocoll. Path to the api must not be specified. Multiple autenticiation mechanism are supported: - Token This function will verify the token and then create a session from the given token. - Credential Authentication against the endpoint /api/v1/users/login is performed, the resulted token is stored in the session. - UserRequest Request access from a user by interactively query for the access in the user session. Specify the username in this parameter. - Guest No authentication at all, access is limited to guest information. .EXAMPLE PS C:\> Connect-AdbServer -Uri 'https://adb.contoso.com' -Credential 'john' Connect to the adb server by using username and password. .EXAMPLE PS C:\> Connect-AdbServer -Uri 'https://adb.contoso.com' -Token 'XXX' Connect to the adb server by using an existing token copied from the adb website. .EXAMPLE PS C:\> Connect-AdbServer -Uri 'https://adb.contoso.com' -UserRequest 'john' Request access from the user john. .EXAMPLE PS C:\> Connect-AdbServer -Uri 'https://adb.contoso.com' -Guest Access the adb as a guest user. .EXAMPLE PS C:\> $adbSession = Connect-AdbServer -Uri 'https://adb.contoso.com' -Credential 'john' -PassThru Store the adb session in a separate variable. #> function Connect-AdbServer { [CmdletBinding()] param ( # Adb uri. [Parameter(Mandatory = $true)] [System.String] $Uri, # Adb credentials. [Parameter(Mandatory = $true, ParameterSetName = 'Credential')] [System.Management.Automation.PSCredential] $Credential, # Adb token. [Parameter(Mandatory = $true, ParameterSetName = 'Token')] [System.String] $Token, # Adb token. [Parameter(Mandatory = $true, ParameterSetName = 'UserRequest')] [System.String] $UserRequest, # Use adb as guest. [Parameter(Mandatory = $true, ParameterSetName = 'Guest')] [switch] $Guest, # Return the session object. [Parameter(Mandatory = $false)] [switch] $PassThru ) # Prepare a session object $session = [PSCustomObject] @{ PSTypeName = 'Adb.Session' Type = $PSCmdlet.ParameterSetName Uri = '{0}/api/v1' -f $Uri.TrimEnd('/') Token = '' } switch ($session.Type) { 'Credential' { try { # Login to the adb by using username and password $loginSplat = @{ Method = 'Post' Uri = '{0}/users/login' -f $session.Uri Body = [PSCustomObject] @{ name = $Credential.UserName; password = $Credential.GetNetworkCredential().Password } | ConvertTo-Json -Compress ContentType = 'application/json' Headers = @{ 'Accept' = 'application/json' } } $result = Invoke-RestMethod @loginSplat -ErrorAction 'Stop' # Store the requested token $session.Token = $result.data.token.token } catch { throw "Credential-based login on $Uri failed: $_" } } 'Token' { try { # Store the passed token $session.Token = $Token # Verify the passed token by quering the current user Get-AdbResource -Session $session -Type 'User' -Name 'me' | Out-Null } catch { throw "The spcified token for $Uri is not valid: $_" } } 'UserRequest' { try { # Request a login token from the specified user $result = Get-AdbResource -Session $session -Type 'TokenRequest' -Name $UserRequest # Store the requested token $session.Token = $result.data.token.token } catch { throw "Token request failed for $Uri with user $UserRequest`: $_" } } 'Guest' { try { # Just try the request with the empty token to get the guest user Get-AdbResource -Session $session -Type 'User' -Name 'me' | Out-Null } catch { throw "Guest access to $Uri is not possible: $_" } } } # Store the session in the module context $Script:AdbSession = $session if ($PassThru.IsPresent) { $Script:AdbSession } } |