# 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 [Account XML](../account/account.md) 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 [Web Service Definition](../reporting/intro.md#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: ` ... ` The `Content-Type` should be `application/xml`. The XML subtree inside the `` node represents the [Account XML](../account/account.md) and will be merged into the app's configuration. The XML must contain exactly one `` root node; additional nodes or wrappers are ignored. When merging, nodes returned in the `` 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: ```xml Custom error message comes here ``` ### Example of Successful External Provisioning Request ```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 ```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 B63349F4EE 45F4BF5F0E191F5DCC27 0 AD4535EF902BB13 ``` 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 `` 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 [Account XML](../account/account.md) can be overridden based on: - Service tier - Subscription level - Device type - Backend rules For example, disabling messaging for a specific user: ```xml 0 ``` 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 (`0`) - Conferencing (`0`) - 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: ```xml AD4535EF902BB13 ``` 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 [Enforcing Logout via External Provisioning](#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 [Web Service Definition](../reporting/intro.md#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 [Account Removal Reporter](../reporting/account_removal_reporter.md) (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.