provisionAddon — Provisioning SiteLock Firewall & CDN

SiteLock Firewall & CDN is a content delivery network-based web application firewall product. Firewall & CDN can be provisioned as an add-on to an existing package or by itself. See also Provisioning an add-on as a standalone product if you intend to provision this for a user who doesn’t have an existing SiteLock scanning package.

SiteLock Firewall & CDN is provided at four different levels of service:

  • Basic

  • Professional

  • Premium

  • Enterprise

Only one level of the SiteLock Firewall & CDN service may be provisioned to a site at any given time.

The API endpoint is:

https://api.sitelock.com/v1/partner

Request format

The example request payload contains two instances of the addonInfo element, one for each of the subscriptions being purchased. The explanation below documents one.

  • SiteLockOnlineRequest: This element is used to delineate the full API request.

    • authentication: The partner’s username, password, and branding

      • username: The partner’s API username

      • password: The partner’s API password

      • partner: (Optional) The brand name to use in messaging

    • provisionAddon: The method name

      • addonInfo: (Repeatable) The subscription to provision

        • site_id: A valid SiteLock site ID (see also Provisioning an add-on as a standalone product).

        • subscription: A partner-specific plan ID that identifies this add-on.

        • renewal_date: (Optional) A date to be used for renewal.

        • waf_origin: (Optional) A partner specified "origin" address for routing. This supports the following use cases:

          • When a domain has been newly provisioned and DNS propagation hasn’t yet completed, specifying the origin IP allows us to assume that the site will be available at this IP without the discovery process concluding successfully.

          • When a partner who operates authoritative DNS for the user moves the user’s site to a new IP (for various internal use cases), they would normally be required to call our API request setWAFOrigin. An alternative approach would be as follows:

            • Before the provisioning call to SiteLock, create an A Record with:

              • name = www-origin.domain.com.

                The name www-origin.domain.com is placeholder value, it can be whatever you choose.

              • value = the origin IP for the site.

            • Include the waf_origin element in the provisioning call, setting its value to www-origin.domain.com.

            • Going forward:

              • You will keep this A Record up to date with updates to the origin IP for the domain.

              • SiteLock will resolve the origin IP from this A Record, and you won’t need to call setWAFOrigin.

        • waf_force_ssl: (Optional) When used in conjunction with the waf_origin field, causes the site to be considered as SSL-enabled and therefore begin the site’s SSL verification process, whether or not SSL is detected on the site during discovery. This is useful for provisioning sites which are so new that their DNS information hasn’t yet propagated.

        • waf_dns_manager: (Optional) Can have one of the following values:

          • customer: Partner requires the user to update DNS records. This is the default when not specified.

          • partner: Partner will modify DNS records.

        • waf_skip_network_certificate: (optional, default value is "0") Use this parameter to skip the network certificate (CA validation process) for your deployment.

          If you choose to skip the CA validation, you will need to provide your own certificate for this deployment via the uploadWafCertificate method.

Example request

<SiteLockOnlineRequest>
    <authentication>
        <user>Username</user>
        <password>Password</password>
    </authentication>
    <provisionAddon>
        <addonInfo>
            <site_id>442676</site_id>
            <subscription>XXX</subscription>
        </addonInfo>
        <addonInfo>
            <site_id>442989</site_id>
            <subscription>XXX</subscription>
            <renewal_date>2015-01-01</renewal_date>
            <waf_origin>www-origin.example.com</waf_origin>
            <waf_force_ssl>1</waf_force_ssl>
            <waf_dns_manager>partner</waf_dns_manager>
            <waf_skip_network_certificate>1</waf_skip_network_certificate>
        </addonInfo>
    </provisionAddon>
</SiteLockOnlineRequest>

Response format for non-SSL sites

  • SiteLockOnlineResponse: This element is used to delineate the full API response.

    • provisionAddon: The method name

      • addonStatuses: This element has no attributes.

        • addonStatus: (Repeatable) This element corresponds to the addonInfo element in the request

          • account_id: The SiteLock account ID related to the site_id provided in the request to provisionAddon

          • site_id: The SiteLock site ID from the provisionAddon request

          • subscription: The plan ID provided in the subscription field from the provisionAddon request

          • subscription_id: The unique value used to identify the instance of the service. This value can be used in deleteAddon requests.

          • status: The value can be one of the following:

            • ok: Success return value

            • error: Error return value. The message element contains more detail.

          • code: (Optional) This element is present when the value of status is error. To view a list of possible error codes, see Error codes.

          • message: The detailed error or success message, for example:

            • WAF Subscription added ok

            • Invalid/Unknown Account ID

          • dns_new_cname: (Repeatable) The value to which the user’s CNAME record should be set. If the partner doesn’t programmatically make this change in the user’s records, SiteLock’s UI will prompt the user to manually make the necessary change during the activation process on the SiteLock Dashboard.

          • dns_new_a: (Repeatable) The values to which the user’s A records should be set. If the partner doesn’t programmatically make this change in the user’s records, SiteLock’s UI will prompt the user to manually make the necessary change during the activation process on the SiteLock Dashboard.

Since multiple provisioning requests can be submitted in one request, the status of an individual provisioning request should be determined by reading the status and message fields of the concerned addonStatus element. To find the addonStatus element in question, our partners would use the site ID and SiteLock subscription plan ID submitted by them in the request to provisionAddon.

Example response for non-SSL sites

<SiteLockOnlineResponse>
    <provisionAddon>
        <addonStatuses>
            <addonStatus>
                <account_id>379430</account_id>
                <site_id>442676</site_id>
                <subscription>XXX</subscription>
                <subscription_id>1234</subscription_id>
                <status>ok</status>
                <message>ANP Subscription added ok</message>
                <dns_new_cname>new-cname.sitelockdns.com</dns_new_cname>
                <dns_new_a>1.2.3.4,5.6.7.8</dns_new_a>
            </addonStatus>
            <addonStatus>
                <account_id>379430</account_id>
                <site_id>442989</site_id>
                <subscription>XXX</subscription>
                <subscription_id>1235</subscription_id>
                <status>ok</status>
                <message>WAF Subscription added ok</message>
                <dns_new_cname>new-cname.sitelockdns.com</dns_new_cname>
                <dns_new_a>9.8.7.6,5.4.3.2</dns_new_a>
            </addonStatus>
        </addonStatuses>
    </provisionAddon>
</SiteLockOnlineResponse>

Response format for sites where SSL is required but a basic level subscription was requested

  • SiteLockOnlineResponse: This element is used to delineate the full API response.

    • provisionAddon: The method name

      • addonStatuses: This element has no attributes.

        • addonStatus: (Repeatable) This element corresponds to the addonInfo element in the request

          • account_id: The SiteLock account ID related to the site_id provided in the request to provisionAddon

          • error_code: An error code from either:

          • error_message: The error message explaining the issue in question

          • extended_error_code: Contains either a value from Firewall & CDN extended error codes or the value -1, indicating the major error_code prevented the Firewall & CDN product from even attempting to provision due to errors which couldn’t be resolved (for example, missing site information)

          • message: This field exists for legacy purposes and for displaying messages not related to direct errors from the Firewall & CDN provisioning process (for example, messages specified in Additional error codes for Firewall & CDN).

          • site_id: The SiteLock site ID from the provisionAddon request

          • status: Can be one of the following values:

            • ok: Success return value

            • error: Error return value. The message element contains more detail.

          • subscription: The plan ID provided in the subscription field from the provisionAddon request

          • will_retry: A 0 (false) or 1 (true) indicating, respectively, whether the error encountered (as detailed in extended_error_code) is able to be retried. If true (for example, site doesn’t resolve), then it will be retried for 12 days before the subscription will be automatically cancelled. During this time, it’s considered active. For more information, see getAnpProvisioningStatus: Managing the activation process.

          • code: Legacy mode only. If error_code is AEX, this field will contain the contents of extended_error_code. Otherwise, it will contain error_code from Additional error codes for Firewall & CDN.

Example error response

<SiteLockOnlineResponse>
    <provisionAddon>
        <addonStatuses>
            <addonStatus>
                <account_id>987654</account_id>
                <error_code>AEX</error_code>
                <error_message>Site requires SSL</error_message>
                <extended_error_code>3003</extended_error_code>
                <message>Site requires SSL</message>
                <site_id>123456</site_id>
                <status>error</status>
                <subscription>8765</subscription>
                <will_retry>0</will_retry>
            </addonStatus>
        </addonStatuses>
    </provisionAddon>
</SiteLockOnlineResponse>

The value of the status element is error. In this case, there will be a specific set of nodes available to help diagnose the issue. There are actually two types of responses: Current and Legacy. The presence of the code node indicates that it’s legacy node. The absence of this node indicates current mode.

Response format for SSL sites

  • SiteLockOnlineResponse: This element is used to delineate the full API response.

    • provisionAddon: The method name

      • addonStatuses: This element has no attributes.

        • addonStatus: (Repeatable) This element corresponds to the addonInfo element in the request

          • account_id: The SiteLock account ID imputed from the site_id provided in the provisionAddon request

          • dns_ssl_verify: An additional step is required when a site is SSL-enabled. A certificate authority will independently verify that the user owns the site being provisioned. To enable this, an unobtrusive change must be temporarily made to the user’s DNS settings. Once verified, this change may be removed.

            • dns_record_domain: The domain which must have the verification record added

            • dns_record_type: The type of DNS resource record (for example, TXT) to be added

            • dns_record_value: The value to be placed into the DNS resource record for verification

          • site_id: The ID of the site

          • subscription: The plan ID provided in the subscription field from the provisionAddon request

          • subscription_id: The unique value used to identify the instance of the service. This can be used in a deleteAddon request.

          • status: The value can be one of the following values:

            • ok: Success return value

            • error: Error return value. The message element contains more detail.

          • code: This element is present when an error occurred. The value of the status element will be error in this case. To view a list of possible error codes, see Error codes.

          • message: The detailed error or success message, for example:

            • WAF Subscription added ok

            • Invalid/Unknown Account ID

          • will_retry: This element is present when an error occurred. The possible values are 0 and 1. The former indicates an unrecoverable error, and the latter implies we will retry provisioning the requested account without further action required by the partner. When 1 is returned in this element, our partners are requested to call getAnpProvisioningStatus periodically (at 6 hour intervals) to check the status of the latest provisioning attempt.

  • The main difference between a non-SSL site and an SSL-enabled site is that the former only requires a DNS routing change for SiteLock’s Acceleration and Protection to take effect. However, the latter also requires the addition of the SSL Validation DNS record, and the verification thereof before the DNS A records and CNAME alias are provided.

  • The dns_ssl_verify element is returned from the provisioning call instead of the dns_new_cname and dns_new_a elements when a site is SSL-enabled.

Since multiple provisioning requests can be submitted in one call, the status of an individual provisioning request should be determined by reading the status and message fields of the concerned addonStatus element. To find the addonStatus element in question, partners should use the site_id, and SiteLock Product ID submitted by them in the request to provisionAddon.

Example response for SSL sites

<SiteLockOnlineResponse>
    <provisionAddon>
        <addonStatuses>
            <addonStatus>
                <account_id>379430</account_id>
                <dns_ssl_verify>
                    <dns_record_domain>example.com </dns_record_domain>
                    <dns_record_type>TXT</dns_record_type>
                    <dns_record_value>globalsign-domain verification= +
                    fgjeAu2vxQO1nR3lqHhd2_8BTB7WowOwDNhj17lKg8
                    </dns_record_value>
                </dns_ssl_verify>
                <site_id>442989</site_id>
                <subscription>XXX</subscription>
                <subscription_id>1234</subscription_id>
                <status>ok</status>
                <message>ANP Subscription added ok</message>
            </addonStatus>
        </addonStatuses>
    </provisionAddon>
</SiteLockOnlineResponse>