SonicOS 7.3 Device Settings

Technical Documentation>  System Administration>  Enabling SonicOS API and Configuring Authentication Methods
Table of Contents

Enabling SonicOS API and Configuring Authentication Methods

The SonicOS API enables administrators to configure, manage, and monitor the firewall programmatically using RESTful API calls. The API configuration options provide granular control over authentication methods, cryptographic security schemes, and cross-origin resource access.

The Cross-Origin Resource Sharing (CORS) feature is supported in SonicOS 7.3.4 and later versions.

To enable SonicOS API and configure client authentication

  1. Navigate to Device | Settings > Administration.
  2. Click the SonicOS API tab.
  3. Enable SonicOS API.

  4. Configure the required API authentication and access controls:
    1. Cross-Origin Resource Sharing (CORS):
      2. Settings Description
      CORS

      Enables Cross-Origin Resource Sharing (CORS) support for API requests to protect against unauthorized cross-origin requests while allowing trusted external integrations, such as custom web portals, external dashboards, and third-party web clients.
      Allow CORS Origins

      Specify the comma-separated list of trusted web origins allowed to query the firewall API. This field is active when CORS is enabled.

      CORS Origin Formatting Rules:

      • Exact Origin format: Origins must be separated by commas, even when entered on separate lines. The field stores line breaks as spaces, and a list without commas is treated as a single entry that matches no origin. As a result, every cross-origin request is rejected with a 403 status code. For Example: https://mgmt.example.com,https://dashboard.example.com:8443
      • Wildcard support: Asterisk (*) is supported only as the sole value in the field and permits requests from any external origin. Subdomain patterns are not supported. Entries such as *.example.com or https://*.example.com are matched as entered, and requests from matching subdomains are refused with a 403 response. If asterisk (*) is entered with other origins, it is treated as an entry, and only listed origins are allowed.
      • Best Practice: Setting an asterisk (*) allows requests from any origin to pass the origin check. On the wire, the response returns the Access-Control-Allow-Origin header with the requesting origin and includes Access-Control-Allow-Credentials: true, which allows the browser to read the response. Because authentication is the only security control on this path, do not use an asterisk (*) if the Non-GUI Management Login Bearer Token Session setting is disabled.
    2. Authentication Methods:
      3. Settings Description
      RFC-7616 HTTP Digest Access authentication Enables RFC-7616 digest access authentication for API requests.
      Digest algorithms

      Select the cryptographic hash algorithms supported for digest authentication:

      • SHA256
      • MD5
      Integrity protection

      Configure the quality of protection message integrity verification:

      • Disabled: Integrity protection is not used.
      • Allowed: Accepts both standard authentication and integrity-protected requests.
      • Enforced: Requires message integrity protection on all digest requests.
      Use session variant (password hashes in place of passwords)

      Configure the use of session-based keying:

      • Disabled: Session variant is not used.
      • Allowed: Accepts both standard digest and session-based variants.
      • Enforced: Requires session-based hashed authentication.
    3. CHAP & Basic Authentication:
      4. Settings Description
      CHAP authentication Enables Challenge Handshake Authentication Protocol (CHAP) for API access.
      RFC-2617 HTTP Basic Access authentication

      Enables legacy RFC 2617 HTTP Basic authentication (credentials transmitted as base64-encoded strings).

      Ensure HTTPS is strictly enforced when using Basic authentication.
    4. Public Key Authentication:
      5. Settings Description
      Public Key authentication Enables public key authentication for the SonicOS API.
      RSA modulus (key/cipher size in bits) Specify the RSA key size in bits. The default value is 1024.
      RSA padding type

      Select the RSA padding scheme:

      • PKCS#1 v1.5: Legacy RSA padding.
      • PKCS#1 v2.0 OAEP: Optimal Asymmetric Encryption Padding.
      OAEP hash method

      Select the hashing algorithm used by OAEP:

      • SHA1
      • SHA256
      • Other (specify custom hash algorithm)

      This field is available only when the RSA padding type is set to OAEP.
      OAEP mask (MGF1) method

      Select the Mask Generation Function (MGF1) hash algorithm:

      • SHA1
      • SHA256
      • Other (specify custom mask hash)

      This field is available only when the RSA padding type is set to OAEP.
    5. Session Security & Token Validation:
      6. Settings Description
      Session security using RFC-7616 Digest authentication Enforces session security validation using RFC-7616 Digest parameters across active API sessions.
      Maximum nonce use Specify the maximum number of server nonce reuses allowed before renegotiation. The default value is 10.
      Non-GUI Management Login Bearer Token Session Check

      Enforces validation checks on Bearer Token sessions created by non-GUI management clients and scripts to prevent unauthorized session reuse.

      This option is enabled by default. When enabled, POST /api/sonicos/auth returns a bearer token in the response that you must send in the Authorization: Bearer header on every subsequent API request. Requests without this token are rejected with a 401 status code, including requests that repeat HTTP Digest authentication.

  5. Click Accept.