.. _configure-PBR-add-on:

Add PBR config records
-------------------------

.. index:: Flowchart;Phone Based Registration Configuration Per Customer


.. tip:: 

   :ref:`use-action-search-to-navigate-automate`


Overview 
............


Phone-based registration (PBR) supports a number of configuration parameters
that define how the service operates in a specific provider or customer environment. 

You will need to create PBR configuration (PBR config) records, as follows: 

* Create a single PBR config record, globally, at Provider level. 

  The global PBR config record at the Provider level allows the PBR web service to make
  the initial connection to the Automate API.

* Create a PBR config record for each customer that will use the phone-based 
  registration add-on.

  The PBR config record at the Customer level defines the specific connection 
  parameters for a specific customer, and eventually will allow per customer 
  Automate user to be used.

  |PBR-config-list.png|



.. rubric:: Related topics

* :ref:`intro-PBR`


.. _provision-PBR-device-records-with-PINs:

Provisioning PBR device records with site-wide PINs
............................................................

Site-wide PINS are useful when PINs are required for either security or to
address use-cases where DNs are not unique.

However, the operational overhead of provisioning a device record per unique device
is not acceptable. In this case, create a single PBR device record at each site:


.. image:: /src/images/PBR-SiteWidePIN.png

.. note::

   * When using site-wide PINS the device name and pattern must be hardcoded to
     use SITE. This is case sensitive.
   * When using site-wide PINS the administrator must specify the route partition
     for the site.




.. _pbr-voss-configure:

Add PBR config records 
.............................

This procedure configures the PBR registration. Instructions are provided for the PBR config record at 
the Provider level (global) and per customer. 


.. include:: pbr-config-workflow.uml

.. important:: 

   Do not select the following options. These features are experimental and should not be enabled: 
   
   * Auto Provision PBR device record
   * Use default PIN 


1. In Automate, go to **PBR Config**, then 
   choose the hierarchy:  

   * To set up the global PBR record, choose Provider hierarchy. 
   * To set up the per customer PBR record, choose the relevant customer hierarchy. 
   
2. Fill out a name for the PBR config record. 
3. Select the **BAT Prefix Required** checkbox.

   .. note:: 
    
      * It is recommended that PBR configuration should only allow the replacement of 
        phones with fake MACs with device name prefix starting with BAT. 
        This ensures that it is never possible for a user to replace a phone that is in active use.

      * Leave **BAT DeviceName Format** as `default`.

4. Choose options based whether the use of PBR device records is required in this environment?

   a. The PBR device record allows an administrator to explicitly
      specify that a device is eligible for phone-based registration.

      Select the **PBR Device Record Required** checkbox, if required.

   b. The PBR device record allows an administrator to specify that a PIN that should
      be used when performing phone-based registration for a specific phone or for
      all phones at a site.

      Select the **Pin Required** checkbox, if required.

   c. The PBR device record can be used to guarantee that the correct device is
      replaced in environments where directory numbers are not unique within a
      CUCM cluster, for example, multiple directory numbers are configured with the same DN, 
      but located in different partitions.

      In this case, clear the **UseSiteWidePIN** checkbox.

      .. note:: 

         By default, Automate requires a PBR device record per device, but in some cases, it 
         may be sufficient to use a single pin per site. In this case, you can enable (select) 
         the **UseSiteWidePIN** checkbox. This provides limited security to ensure that a 
         PIN is still required to register a phone, but reduces the operational burden by 
         eliminating the need to provision a PBR device record for each phone. 
         See :ref:`provision-PBR-device-records-with-PINs`

5. At **Phone Registration Portal Port** and **Phone Registration Portal Address**, specify the port and the 
   IP address or hostname:

   * For HTTPS-based connectivity, the port should be `443` and the address is the IP address or hostname of an 
     Automate proxy node in a cluster.
   * For HTTP-based connectivity, the port can be `80`, and the address is the IP address or hostname of the 
     primary Automate unified node in a cluster.

   .. note:: 
    
      The phone registration portal address and the port you specify must be accessible from the phone network.

6. At **Phone Registration Portal API User** and **Phone Registration Portal API Password**, fill out the 
   email address for the API user previously created, and fill out the password. 
   
   See :ref:`create-restricted-API-role-user`

   .. note:: 

      The portal API user credentials (username and password), is required for both the 
      Provider-level PBR config record and for the PBR config record for any customers. 

7. At **Phone Registration Service Hierarchy**, specify the hierarchy: 
   
   * If the PBR config record is defined at Provider level, specify the hierarchy 
     as in the following example: `sys.hcs.CC-P`.
   * If the PBR config record is defined at the Customer level, specify the hierarchy 
     as in the following example: `sys.hcs.CC-P.FlexCorp`

8. At **CUCM IP**, specify the IP address of CUCM that is accessible to Automate using 
   HTTPS SOAP requests.

9. Save the PBR config record you configured, then run the following CLI command on the 
   primary node to restart the services: 

   ::

      cluster run all app start phone-based-registration



.. |PBR-config-list.png| image:: /src/images/PBR-config-list.png
.. |PBR-config-detail.png| image:: /src/images/PBR-config-detail.png