AzSession

Table of Contents

• Syntax
• Description
• Examples
• Parameters
• Inputs
• Outputs
• Notes
• Related Links

Reference Module: AzSession

Creates a PSSession to an Azure Virtual Machine.

Important

This module requires the Azure CLI.

Syntax

Get-AzSession
    -ResourceGroup <String>
    -VmName <String>
    [-UserName <String>]
    [<Common Parameters>]

Description

Microsoft has introduced a pretty cool feature where you can use Azure Active Directory credentials for AAA against a Linux virtual machine (see Microsoft Docs for more information). Getting signed in the first time is a bit cumbersome, but in my opinion worth it for the convenience and security.

There is, however, a massive caveat: you can no longer (trivially) SSH to the machine in an external client, as the AZAD sign-in flow generates an ephemeral key pair on the VM for you, and requires interop with AZAD to do so. The Azure CLI PowerShell module does offer a means to export a key, but due to its ephemeral nature, you can only use it for around an hour:

az ssh config --file '~./ssh/config' -n vmName -g resourceGroupName

This works fine with OpenSSH and anything that can either read its default configuration (~./ssh/config) or take a configuration file as an argument.

However, exporting the config file to the default location won’t work if you already have a configuration file (presumably to prevent clobbering the user’s settings). Inconveniently, my best friend New-PSSession doesn’t take a configuration file from the command line, so I had to find a work-around.

This module facilitates "fixing" this configuration conflict seamlessly for the end-user:

1. Temporarily rename the user’s SSH configuration.

2. Generate the ephemeral keys for the connection and associated configuration via az ssh config.

3. Copy the ephemeral configuration and keys to the default location.

4. Create a session with the VM.

5. Delete the ephemeral keys and configuration.

6. Restore the user’s configuration.

Note	For obvious reasons, other SSH sessions that rely on the user’s SSH configuration cannot be created while this module is working. Existing sessions will continue to function as expected.

Examples

Example 1. Create a reusable PSSession

[System.Management.Automation.Runspaces.PSSession] $Session = Get-AzSession -ResourceGroup 'contoso-sql' -UserName 'someone@contoso.com' -VmName 'contoso-sql01'

1. Connect to a created PSSession

[System.Management.Automation.Runspaces.PSSession] $Session = Get-AzSession -ResourceGroup 'contoso-sql' -UserName 'someone@contoso.com' -VmName 'contoso-sql01'

Enter-PSSession $Session

1. Copy files to a created PSSession

[System.Management.Automation.Runspaces.PSSession] $Session = Get-AzSession -ResourceGroup 'contoso-sql' -UserName 'someone@contoso.com' -VmName 'contoso-sql01'

Copy-Item -Path '/home/someone/lqs.sql' -ToSession $Session -Destination '/var/tmp/'

1. Copy files from a created PSSession

[System.Management.Automation.Runspaces.PSSession] $Session = Get-AzSession -ResourceGroup 'contoso-sql' -UserName 'someone@contoso.com' -VmName 'contoso-sql01'

Copy-Item -FromSession $Session -Path '/var/log/fire.log' -Destination '/home/someone/logs'

Parameters

-ResourceGroup

Specifies the Azure Resource Group in which the target Virtual Machine resides.

Type	String
Position	Named
Default Value	None
Accept Pipeline Input	False
Accept Wildcard Characters	False

-UserName

Your Azure AD username. Defaults to executing user if not set.

Type	String
Position	Named
Default Value	Executing user’s username
Accept Pipeline Input	False
Accept Wildcard Characters	False

-VmName

Specifies the name of the target Virtual Machine in Azure.

Type	String
Position	Named
Default Value	None
Accept Pipeline Input	False
Accept Wildcard Characters	False

Inputs

None

Outputs

PSSession

Notes

• This module assumes the following:

  • The target Virtual Machine has a public IP address.

  • The target Virtual Machine’s first public IP address can be used for SSH connections.

• When you are finished with the PSSession, use the Remove-PSSession cmdlet to delete the PSSession and release its resources.

Related Links

• Connect-PSSession

• Disconnect-PSSession

• Enter-PSSession

• Exit-PSSession

• Invoke-Command

• Recieve-PSSession

• Remove-PSSession

• About PSSessions