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.
The VVX needs to be at least version 5.9 or above. If it isn’t you can upgrade it from the web interface:
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:
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:
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
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
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
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
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!