Sunday 13 February 2022

Poly VVX Teams SIP Gateway Tool

Microsoft recently released their Standard SIP Gateway product for a range of Poly, AudioCodes, Yealink and Cisco Standard SIP based phones. This service allows you to register these devices to a Teams user account and do basic call functions. The way Microsoft has implemented its provisioning process for these devices is very interesting. They have used a combination of device provisioning features that these phones already had with a custom authentication process. It’s actually very clever and was obviously a serious design investment on top of an already complex large scale Standard SIP infrastructure deployment.

The one drawback with Microsoft’s provisioning procedure, in my opinion, is that it requires a real-life human at some point to physically handle each phone device. For existing phone devices that are likely already deployed all over office buildings, the idea of finding every device is a bit of a nightmare. The enrollment feature is built around Teams Admin Centre which means that the device must first be connected to your Teams Tenant before it can be administered. Well, that was until this blog post… 😊

After looking at the way the Team SIP Gateway works, and the way the Poly VVX phones worked, I figured that I could possibly streamline this process to be done entirely remotely (avoiding the physical human phone-touching component). After some prototyping it turned out this could in fact be done. 

As a public good, I decided to release a version of the tool that allows you to very quickly provision an existing Poly VVX to connect to the Teams SIP Gateway and remotely sign-in/sign-out the device. Due to the importance of security and keeping your Standard SIP sign in credentials safe, I recommend that you always change the passwords on your VVXs to something more complex and secret. To help with this, the tool also has the capability to do remote password changes in bulk.

 

Poly VVX Teams SIP Gateway Tool


A swiss army knife for your Poly VVXs and the Microsoft Teams SIP Gateway.



Features:

  • GUI and command line execution modes. To use the GUI just run the tool without the "-Command" flag. To use command line mode run the tool using the "-Command" flag. See the command line flags section of this post for more details.
  • Connect to individual IP Addresses or Ranges of IP Addresses using the IP list capability.
  • Remotely connect to phones and do initial provisioning without having to log into the web interface manually.
  • Remotely check the status of phones to see if they are provisioned, signed-in or signed-out.
  • Remotely Sign-in the VVX phone to Microsoft Teams by clicking the "Teams Sign In" button. The tool will make the request for a Pairing Code and then you can complete the sign in through a browser. Once this process is completed, the phone will auto-reboot and sign into Teams (this includes provisioning reboots from Microsoft and takes about 5 mins).
  • Remotely Sign-out the VVX phone to Microsoft Teams by clicking the "Teams Sign Out" button. This will Sign Out the phone and have it reboot automatically back to the logged out state.
  • Change the password used by phones to harden the security of the device. This is important because using defaults will leave your devices' SIP registration credentials open to be stolen.
  • Remotely restart VVX phones by clicking the "Reboot" button. There shouldn’t be many occasions when you need to do this. However, if something doesn’t seem to be working a reboot will get the phone to run through its provisioning again which may fix your problem.
  • Import CSV of device IP Addresses. The CSV file only requires one column with a header column named "IPAddress". The CSV format that is exported from the Results Dialog can also be directly imported.

Requirements:

  • You will need direct IP access over the network to the subnets where the phones are deployed (no firewalls blocking web ports) and access to the Internet for connections to Microsoft's provisioning service (via TCP Port 443). You will get connection errors if this access is not available.
  • The phone needs to be accessible via its web interface (i.e you can connect to it with a browser and see the web interface) in order to connect to it with this tool. If the web interface is disabled you will need to enable it via local config server or configuring the device directly: Advanced > Administration Settings > Web Server Configuration > Enabled
  • The VVX needs to be at least version 5.9 or above. If it isn’t you can upgrade it from the web interface:




Note: The tool works on PowerShell version 5 and 7. The choice is yours. Enjoy!

 

Download from Github

 


Command Line Flags


The Tool can be run either with the GUI or as a pure command line tool that returns result objects that you can use within your scripts. To use command line mode, you must use the "-Command" flag to tell the tool what function you would like it to perform. When the "-Command" flag is used, it automatically tells the tool not to load the GUI.


Command Line Options:


 -Command

If you specify a command then the tool will not load the GUI and instead will execute the command directly and respond with an output object.

Values: "status", "signin", "signout", "provision", "changepassword", "restart"

Note: When using the provision flag you will need to also specify the DeviceRegion flag. When using the changepassword flag you will also need to specify the DeviceNewPassword flag.

Example: .\PolyVVXTeamsSIPGatewayTool.ps1 -DeviceIPRange @("10.0.0.141", "10.0.0.0/24") -DeviceAdminPassword "P@ssw0rd" -DeviceUseHTTPS $true -Command status

Output Object Format:

              IPAddress  : 10.0.0.238

              Model      : VVX 411

              MACAddress : 64:16:7F:25:12:88

              Version    : 6.3.1.8427

              Result     : Provisioned and signed out

 

Note: Some commands will not give outputs for the Model, MACAddress and Version values. They will respond with a blank string ("") if there is no data available so you should check for this if you are expecting this information.

 

-DeviceWebPort

This is the web port on the phone device. The tool will try to connect to this port to get to the web interface.

Values: 1-65535

 

-DeviceUseHTTPS

This specifies if HTTP or HTTPS is used to connect to the device. $true or $false

Values: $true or $false

 

-DeviceAdminUsername

This specifies the admin username on the VVX. This should always be "Polycom"

Value: "Polycom" - Don't change this unless you know something I don't.

 

-DeviceAdminPassword

This specifies the admin password for the VVX web interface.

Values: Default "456". Any string is valid.

 

-DeviceIPRange

This specifies an array object containing and IP Address, IP Address range in subnet format (10.0.0.1/24), or IP Range in dashed format (e.g 10.0.0.1-10.0.0.254)

Value: Array format (e.g @() format). Examples:

               -DeviceIPRange @("10.0.0.238", "10.0.0.141")

               -DeviceIPRange @("192.168.0.200/24", "192.168.1.10/24")

              -DeviceIPRange @("192.168.0.200-192.168.0.220", "192.168.1.10-192.168.1.20")

 

-DeviceRegion

This is the region where the phones are being deployed. This flag should always be used when using the Command flag with "provision" input (or it will default to "Asia Pacific"). The appropriate region URL provided by Microsoft will be selected for the region you select. You should use your local region for best performance.

Values: "Asia Pacific", "Europe", "America"

 

-DeviceNewPassword

This setting can be used to send the new password when using the "changepassword" Command flag.

 


Command Line Examples


Below are some examples of using the tool in command line mode:


Get device status:

.\PolyVVXTeamsSIPGatewayTool.ps1 -DeviceIPRange @("10.0.0.141", "10.0.0.238") -DeviceAdminPassword "12345" -DeviceUseHTTPS $true -Command status


Sign in device:

.\PolyVVXTeamsSIPGatewayTool.ps1 -DeviceIPRange @("10.0.0.141", "10.0.0.238") -DeviceAdminPassword "12345" -DeviceUseHTTPS $true -Command signin


Sign out device:

.\PolyVVXTeamsSIPGatewayTool.ps1 -DeviceIPRange @("10.0.0.141", "10.0.0.238") -DeviceAdminPassword "12345" -DeviceUseHTTPS $true -Command signout


Provision device:

.\PolyVVXTeamsSIPGatewayTool.ps1 -DeviceIPRange @("10.0.0.141", "10.0.0.238") -DeviceAdminPassword "12345" -DeviceUseHTTPS $true -DeviceRegion "Asia Pacific" -Command provision


Change device password:

.\PolyVVXTeamsSIPGatewayTool.ps1 -DeviceIPRange @("10.0.0.141", "10.0.0.238") -DeviceAdminPassword "456" -DeviceUseHTTPS $true -DeviceNewPassword "12345" -Command changepassword


Restart device:

.\PolyVVXTeamsSIPGatewayTool.ps1 -DeviceIPRange @("10.0.0.141", "10.0.0.238") -DeviceAdminPassword "12345" -DeviceUseHTTPS $true -Command restart



How to use the Tool


As a prerequisite you need to know at least what IP Address range your phones are on. The tool requires that you enter an IP Address or Range of IP Addresses to try to connect to. If your devices are spread over a subnet with other devices you can run the "Get Teams Status" function on the whole subnet to figure out what the MAC Addresses and IP Addresses are of all the phones. You can then export this information as a CSV file for future runs.

Step 1: Change the Password on the phone(s)

Okay, first thing is first, let's secure these phones so your precious SIP Server authentication details cannot be stolen from your device. The default password for the VVX is "456". If you haven't already changed the password to something that’s hard to guess, I suggest changing it to something complex.

Click the “Change Password” button.

 

Step 2: Provision the phone(s)

In most cases you shouldn't have to manually update the software on the phones; this will get done as part of the provisioning process. Enter the IP Address/Range of the phone(s) and click the “Inital Provision” button. The tool will then connect to the phone and update its provisioning server information to point to Microsoft and it will automatically reboot.



The phone will now connect to the Microsoft provisioning service and download a base configuration (it actually downloads a couple of config files in multiple steps). It will also upgrade the firmware on the device to the supported Teams version. The software upgrade process can take some time (approx. 10+ mins). I would recommend you give it some time (~20 mins) before moving to the next step.

 

Step 3: Check the Status of your phone(s)

Click the “Get Teams Status” button.

If your phones have finished provisioning you should see a status of “Status: Provisioned and signed out”. If you can’t connect to the phone then it is likely still in the process of updating its software or rebooting. Give it some time if this is the case.

 

Step 4: Sign in the Phone(s)

If these are devices that have resource accounts that you know the Azure Active Directory Username and Password for, then you can sign them into Teams. Check you have the correct IP Addresses or IP Ranges configured in the tool. Then click the “Teams Sign in” button and wait for the pairing code to be shown in the Results Dialog.




Open a browser window and browse to the URL supplied (https://aka.ms/siplogin) and sign in with the user you would like to sign the phone in as:


Once signed in you will be asked for a pairing code. Enter the Pair Code supplied by the Teams SIP Gateway Tool results dialog:


Enter the Pairing Code from the Teams Sing in Result Dialog window from the tool. You should then see a success screen:


Now the phone will automatically reboot and complete the sign in process. This can take 5 minutes to complete on the device as it has to reboot and get a new configuration from Microsoft.

 

Step 5: Check the Status of your phone(s)

Click the “Get Teams Status” button. Once they are signed in you should get a “Status: Provisioned and signed in”.

 

Step 6: Relax

Job's done. Kick back and relax. You’ve earnt it.

  

The Wrap Up


When I first started this discovery process, researching the way the Microsoft SIP Gateway worked, I didn't think it would lead to this. However, I’m pretty happy with the outcome and think that the tool should save you some time if you choose to use it. If you have any feedback feel free to drop it in the comments. Stay safe and be cool!



Read more →

Popular Posts