.. _external-provisioning:

=====================
External Provisioning
=====================

External provisioning is an optional extension to Cloud Softphone’s standard provisioning workflow. It allows providers
to apply dynamic logic at the moment the app signs in or activates, making it possible to integrate with backend systems,
enforce business rules, and supply configuration or credentials that depend on the individual user. This adds a flexible,
real-time layer on top of the static provisioning defined in the Cloud Softphone portal.

External provisioning is commonly used for:

- Access control and session management.
- Issuing user-specific SIP credentials.
- Returning per-user configuration overrides.
- Creating new users during onboarding.

From a technical perspective, the external provisioning endpoint is invoked after the app downloads its base provisioning
from the Cloud Softphone portal. The app sends a set of input parameters, including username and password, to the
provider’s web service. The service returns an :ref:`account-xml` document, which is merged with the default provisioning
to produce the final configuration used by the app.


Web Service Definition
======================

External provisioning consists of two related but separately configurable web services:

- 1. Initial external provisioning, triggered when the user signs in or activates the app for the first time
- 2. Re-provisioning, triggered automatically on app startup and periodically if enabled

Both web services are configured in the Cloud Softphone portal and follow the standard :ref:`web-service-definition`
syntax, but each uses its own prefix and placeholder rules.

Initial External Provisioning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Initial external provisioning uses the prefix ``InitialProvisioning``, for example:

- ``InitialProvisioningUrl``
- ``InitialProvisioningPostData``
- ``InitialProvisioningMethod``

At this stage, the app has not yet created an account, so the web service receives parameters directly from the initial
login screen. The following placeholders are available:

- ``%username%`` — the username entered by the user
- ``%password%`` — the password entered by the user
- ``%fullcode%`` — the Cloud ID of the application

These placeholders are expanded directly in the URL or request body before the web service is called.

Account XML does not yet exist at this stage; ``%account[...]%`` cannot be used during initial provisioning. The
``%username%`` and ``%password%`` values come directly from the login screen.

Re-Provisioning
~~~~~~~~~~~~~~~

Re-provisioning uses the prefix ``extProv``:

- ``extProvUrl`` - the URL of the re-provisioning web service
- ``extProvMethod`` - the HTTP method to use for the re-provisioning web service
- ``extProvPostData`` - the POST data to send to the re-provisioning web service
- ``extProvInterval`` - the interval in seconds at which the app will automatically call the re-provisioning web service
- ``extProvLogoutStatusCode`` - the HTTP status code to return to trigger logout

Unlike initial provisioning, re-provisioning operates on an existing account. Because of this, the service must use the
``%account[...]%`` placeholder syntax to access values stored in the Account XML, such as:

- ``%account[username]%``
- ``%account[password]%``
- ``%account[X-install-id]%``

The initial placeholders ``%username%`` and ``%password%`` do not work during re-provisioning and must be wrapped in
``account[...]``.

.. warning::
    During re‑provisioning, ``%username%`` and ``%password%`` DO NOT expand. They must be referenced as
    ``%account[username]%`` and ``%account[password]%``.

Re‑provisioning executes on application startup and, if enabled via ``extProvInterval``, the app will periodically re-call the re-provisioning web service using the
``extProv*`` parameters.

- The app sends ``If-Modified-Since`` header, allowing the provider to return ``304 Not Modified``.
- If ``200 OK`` is returned with updated Account XML, the app merges the changes and refreshes the account.

.. warning::
 The default value for ``extProvInterval`` is 0, which means that external re-provisioning will be called only when
 creating or editing account. To enable periodical automatic re-provisioning, specify non-zero value of
 ``extProvInterval`` in your Account XML.

.. note::
    To avoid conflicts, the account is not modified when Settings page of the application is open, or if there is a call
    in progress. As soon as the user closes Settings and/or all calls end, the changes are applied.

Web Service Response
====================

The external provisioning web service must respond with an HTTP ``2xx OK`` status code and an XML body containing the
root node:

``<account> ... </account>``

The ``Content-Type`` should be ``application/xml``. The XML subtree inside the ``<account>`` node represents the
:ref:`account-xml` and will be merged into the app’s configuration.

The XML must contain exactly one ``<account>`` root node; additional nodes or wrappers are ignored. When merging, nodes
returned in the ``<account>`` XML override values from the base provisioning.

If the service returns a non-``2xx`` status code, the provisioning process stops and the app shows a generic error
message. To display a custom error message, return a non-``2xx`` status and include:

 .. code-block:: xml

  <error>
    <message>Custom error message comes here</message>
  </error>

Example of Successful External Provisioning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Request

 .. code-block:: http

    GET /prov?cloud_username=johndow&cloud_password=12345678&cloud_id=EXAMPLE&initialScreen=1 HTTP/1.1
    Host: provider.com
    Connection: close
    Cache-Control: max-age=0
    User-Agent: CloudSoftphone/1.5.6


Response

 .. code-block:: http

    HTTP/1.1 200 OK
    Date: Sun, 15 Mar 2015 00:46:17 GMT
    Server: Apache/2.4.7 (Ubuntu)
    Vary: Accept-Encoding
    Content-Length: 183
    Keep-Alive: timeout=5, max=100
    Connection: Keep-Alive
    Content-Type: text/xml

    <account>
      <username>B63349F4EE</username>
      <password>45F4BF5F0E191F5DCC27</password>
      <allowMessage>0</allowMessage>
      <X-install-id>AD4535EF902BB13</X-install-id>
    </account>

This example demonstrates initial provisioning returning dynamically assigned SIP credentials.

Use Cases for External Provisioning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

External provisioning gives providers granular control over account setup and ongoing configuration. Typical use cases
include:

1. Delivering SIP Credentials Without Exposing Them to the End User
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    Many providers authenticate users using email, phone number, customer ID, or another identifier that is not the
    actual SIP username. External provisioning allows:

    - The user to sign in using a simple credential
    - The provider’s backend to validate the user
    - The backend to return the real SIP username and password inside the ``<account>`` XML

    This ensures each user receives the correct SIP credentials without ever seeing or learning those credentials.

2. Per-User Configuration Overrides
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    Providers can adjust configuration dynamically for individual users. Any parameter from :ref:`account-xml`
    can be overridden based on:

    - Service tier
    - Subscription level
    - Device type
    - Backend rules

    For example, disabling messaging for a specific user:

    .. code-block:: xml

        <allowMessage>0</allowMessage>

    Or enabling/disabling other features on a per-user basis.

3. Controlling Access to Features
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    External provisioning can be used to tailor feature availability at the user level. Examples include:

    - Linkup Messaging (``<linkupMessagingEnabled>0</linkupMessagingEnabled>``)
    - Conferencing     (``<conferencingEnabled>0</conferencingEnabled>``)
    - Any provider-defined add-on service

    This gives providers precise control over which capabilities are available to each user.

4. Adding Custom Account Parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    Providers may return additional XML nodes to store metadata or internal identifiers. These values are preserved in
    the account and can be referenced later using:

    ``%account[customNode]%``

    For example:

    .. code-block:: xml

        <X-install-id>AD4535EF902BB13</X-install-id>

    This can be used for analytics, tracking, device registration, or routing logic.

5. User Onboarding and Automatic Account Creation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    Initial external provisioning can serve as an integration hook for creating users in the provider’s backend.
    Typical flows include:

    - Creating a SIP account during activation
    - Allocating phone numbers or extensions
    - Initializing service resources for first-time users

    This allows providers to offer a smooth sign-up or activation experience without requiring manual backend operations.

.. note::
    Feature overrides returned by external provisioning (for example ``allowMessage`` or ``linkupMessagingEnabled``)
    override portal defaults during merge. However, paid or licensed features must still be enabled in the Cloud
    Softphone portal for them to be configurable via external provisioning.

6. Enforcing Logout via External Provisioning
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    External provisioning can be used to enforce user logout based on a specific HTTP status code returned by the
    re‑provisioning web service. See :ref:`enforcing-logout-via-external-provisioning` for more details.

Enforcing Logout via External Provisioning
==========================================

Overview
~~~~~~~~

Mobile and desktop applications can enforce a user logout based on a specific HTTP status code returned by the external
re‑provisioning web service. This is configured using the ``extProvLogoutStatusCode`` parameter in the
:ref:`web-service-definition`.

Purpose
~~~~~~~

This mechanism is helpful in scenarios such as:

- Off‑boarding customers or employees
- Enforcing password resets or credential rotation
- Temporary access revocation

How to Configure
~~~~~~~~~~~~~~~~

In the Cloud Softphone portal, set the parameter for re‑provisioning:

- ``extProvLogoutStatusCode``

Set this value to the HTTP status code your provisioning service will return to trigger logout.

For example, if ``extProvLogoutStatusCode = 410``, returning HTTP ``410 Gone`` from the provisioning server forces
immediate logout.

Behavior on Logout
~~~~~~~~~~~~~~~~~~

When the provisioning web service returns the configured status code:

- The user is unregistered from SIP.
- The application notifies the :ref:`account_removal_reporter_webservice` (if configured).
- A local encrypted backup is created, containing Preferences, local call history, and Quickdials. On the next
  successful login, the backup is automatically restored.