Reference13r3:Concept Provisioning
Overview
In 13r1 and above provisioning of phones is done with Devices. From a user point of view a provisioning code is entered on a new phone and then the rest happens automatically. There are different kind of provisioning. A user who adds a new phone, an administrator who performs rollout for many phones and maybe more. The different types of provisioning are defined one after the other.
Requirements
- HTTP/HTTPS-access to config.innovaphone.com (open port 80/443)
- further required protocols/ports see here
- device does not yet belong to a (different) domain
User adding a new phone
From a user point of view this should work as follows:
- The user unpacks the phone and connects it to the network (we assume 13r1 is on the phone already, but maybe an old build)
- On the display a form requesting a provisioning code is displayed
- The user opens myApps/Profile and selects to add a new phone
- Drop down to select a category is provided
- When the user has sent the request a provisioning code is displayed
- The user adds the provisioning code on the phone and confirms with OK.
- Note for IP101/IP102: Confirmation is done by adding # to the provisioning code.
- The phone is updated to the current version of the installation, configured, a device is added to the user in the PBX
Implementation
- Setup
-
- The Devices PBX app object must have a websocket connection flag.
- The Profile PBX app object must have a websocket connection flag, the Services flag and the "devices-api" App.
- User connects a 13r1 phone to the network
-
- The standard update url http://config.innovaphone.com/init is requested.
- The provision code form is displayed.
- User selects to add a new phone on myApps/Profile
-
- The Users instance asks Devices for a list of categories configured for provisioning
- The Users Instance requests a provisioning code from Devices with selected category
- Devices requests a provisioning code from config.innovaphone.com and supplies the devices URL to config.innovaphone.com
- config.innovaphone.com generates a random provisioning code of 12 digists without any structure
- config.innovaphone.com stores the provisioning code and URL in the database
- Devices stores the provisioning code together with domain and category in the database
- Users stores the provisioning code and with the requesting user in the database
- The user enters the provisioning code
-
- The code is sent to config.innovaphone.com
- config.innovaphone.com configures the Devices URL of the customer
- The phone connects to Devices and sends the provisioning code
- Devices assigns the phone to a domain and category
- Devices updates the phone
- Devices configures the phone
- Devices sends the mac address and provisioning code to a Users instance of matching domain. If no Users with matching domain is connected, the mac address is stored in the database so that the info can be sent, when a matching Users connects
- Users configures a device for the user
Note: Due to security reasons, provisioning codes are valid for 10 minutes from date of issue. Upon validation expiry, they are deleted from the database and no more useable anymore.
Update Software functionality in Devices
A list of jobs is stored. This list contains domain and category of the devices to be updated. With a job the json which was current on the time of creation is stored. When a device registers it is updated according to the latest matching job.
Update Config functionality in Devices
A list of jobs is stored. This list contains doman, category and a type of config with related parameters. When a device registers it is updated according to the latest jobs of all types.
Rollout of many phones on UsersAdmin
On UsersAdmin under "Register phones" phones can be provisioned for many users at once.
To provision the phones:
- Select new phone registrations and follow the steps.
- On the first step the connection with Devices is stablished.
- On the second step, the provisioning category (the categories are configured on Devices for a given domain) and the phone app are selected. A dropdown menu will be displayed if there is more than one option.
- On the third step the users must be selected
- On the fourth step the provisioning codes list is displayed. This list can also be downloaded as a CSV file. Every user must enter his code on his phone. After that, the state should change from "Pending" to "Registered".
Note: Due to security reasons, provisioning codes for rollouts are valid for 7 days from date of issue.
Privacy
When using the online provisioning, following data/information are send to innovaphone config.innovaphone.com:
- Devices APP
- Websocket URL of your AP-Platform
- Phone
- Mac Address
- Phone Model
- Firmware Version
- Bootcode version
- Timestamp of the first connect to config.innovaphone.com
- Entered Provisioning Code
- Local IP
Offline Provisioning
There is also the possibility for offline provisioning: Reference13r3:Concept_Offline_Provisioning
Show provisioning code display on phones
You have to issue the following command to show the provisioning code display on phones again: !vars create UPDATE/PROVISIONING-CODE h prompt
No reboot or config write is required
Automatic provisioning
Available with 13r1 SR13.
You can enable the automatic provisioning mechanism inside your Devices App in the domain settings.
If you enter a security token here, devices can register with this token automatically.
You then have to rollout a devices registration URL with URL parameters on your devices, which shall use this mechanism.
Let's assume the auto provisioning URL (visible in the Devices App) looks like this:
wss://apdnsname.com/domain.com/devices/sysclients?domain=domain.com&token=1j2h3j12h3&category=testcategory
The config cmd provided within an update script then looks like this, as you need to URL encode the whole value:
config change SYSCLIENT /sysadmin wss%3A%2F%2Fapdnsname.com%2Fdomain.com%2Fdevices%2Fsysclients%3Fdomain%3Ddomain.com%26token%3D1j2h3j12h3%26category%3Dtestcategory
The following parameters are available and mandatory. The values of these parameters must be URL encoded before the complete URL is URL encoded for the !config change command:
- domain: the domain name for the device
- token: a security token, which must be manually configured in the Devices App inside the domain settings
- category: the name of a provisioning category inside the given domain (it must be explicitly a provisioning category!)
Example:
Encode the values for token and category first: token: abcdef#XYZ => abcdef%23XYZ category: acme IP Phone => acme%20IP%20Phone Encode the complete provisioning URL: wss://apdnsname.com/domain.com/devices/sysclients?domain=domain.com&token=abcdef%23XYZ&category=acme%20IP%20Phone => wss%3A%2F%2Fapdnsname.com%2Fdomain.com%2Fdevices%2Fsysclients%3Fdomain%3Ddomain.com%26token%3Dabcdef%2523XYZ%26category%3Dacme%2520IP%2520Phone
Double check the Devices App URL after the Update Script is executed on the provisioned device (the URL must not contain any spaces or non urlencoded characters):
wss://apdnsname.com/domain.com/devices/sysclients?domain=domain.com&token=abcdef%23XYZ&category=acme%20IP%20Phone
Do not use a web browser to submit the config line config change SYSCLIENT ...
to the provisioned device, cause it will urldecode the URL prio sending it to the device, resulting in an incorrect configuration.
Administrative passwords
With latest 13r3 firmware and above, devices which are automatically provisioned will never receive the administrative domain password but instead a random password.
If you provision a gateway like this, you can remove it from your domain and manually add it again to receive the administrative domain password if you deploy the administrative password on your domain.
Note that you can't remove and add a device in our cloud manually! Provision the device instead with the install provided on the gateway where you enter a manually created provisioning code.
Provisioning V13 devices with V12 Update Server
If you use a V12 update server you have to delete some variables on the device. This is normally done by the V13 provisioning service which is not used in this scenario.
Therefore you need to delete the following variables in your provisioning process.
config rem UP1 /provisioning config rem UP1 /provision vars del UPDATE/PROVISIONING-CODE config write config activate
Related Articles
- Reference13r3:Concept_Offline_Provisioning
- Reference13r3:Services/Provisioning
- Reference13r3:Services/Update
- Howto:V13_Firewall_Settings
- Howto:What_Ports_are_used_for_Signaling_and_Voice_Traffic_in_SIP_and_H.323?
- Howto:Innovaphones_public_services
Known issues
Device provisioning doesn't work
Make sure that your device does not belong to a different domain. If the MAC address is already assigned to a different domain, the provisioning process is cancelled to prevent unauthorized domain moves.