SonicOS API: TOTP based two-factor authentication for management by Admin user

SonicOS API provides an alternative to the SonicOS Command Line Interface (CLI) for configuring selected functions.

You are free to choose Swagger, Postman, Git bash, or any application that allows API calls, if you are using a Linux-based operating system you can execute cURL from the terminal.

Please refer to https://sonicos-api.sonicwall.com for the entire list.  

Only the first part of this article would change, depending on the SonicWall model you use. API commands are the same for both Gen6 and Gen7 SonicWall devices. 

For this article, I'm using Postman App and will be showing the commands to run on cURL for each step.

SonicOS API is disabled by default in SonicOS. Any attempt to access SonicOS API while it is disabled results in an HTTP 403 Forbidden error. To use the SonicOS API, you must enable it, either through the SonicOS Management Interface or from the CLI. 

Please enable the SonicOS API module in the SonicWall UI.

Gen 7: Enable SonicOS API Gen7

Gen 6: Enable SonicOS API Gen6

Step 1: Enable TOTP for Admin login in SonicWall 

Login to SonicWall management page and navigate to Device | Settings | Administration > Firewall Administrator and Enable TOTP option. You may need to login at least once on browser before trying in API.

Follow this KB for detailed instructions: How do I configure Two-factor authentication for the Admin login with TOTP?

The same mobile TOTP will be bound to the admin log in and we need the same code for API as well.

Step 2: Enable Two-factor authentication for SonicOS API

Now navigate to Device | Settings | Administration > SonicOS API and enable the option 'Two-factor and Bear Token Authentication'

Step 3: Log in using SonicOS API

Logging in consists of two stages - first is to log in using the TOTP in the body of the API call, which generates a Bearer token and the second is to use this Token to run all subsequent API requests

• The API endpoint changes to */tfa
  
  
  
  
  
• The request contains login user, password and the TOTP values in the body of the call. Hit "Send" and if the call is a success, a Bearer token is generated in the Response.
  
  
  
  

  cURL command for MFA Authentication:
  
  

  curl --location 'https://192.168.168.168/api/sonicos/tfa' \

  --header 'Accept: application/Json' \
--header 'Content-Type: application/Json' \
--data '{
    "user": "admin",
    "password": "******",
    "tfa": "884444",
    "override": true
}'
  
  
  
• This Bearer token needs to be copied and used for all subsequent requests. For this article, I have used two examples of getting current System status and current logged in users. 
  
  System status:
  
  

  
  cURL command for System Status:
  
  

  curl --location --request GET 'https://192.168.168.168/api/sonicos/reporting/status/system' \

  --header 'Content-Type: application/Json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiYWRtaW4ifQ.uiagV4VWK_4wgyLLbZYWwhCWmIkhg3t6yJDTqSu-ZCtu6fWQH55yxjmWkedlGpoZA4in1qlGW5CbpdCKDKhoGQ' \
--data '{"override" : true}'
  
  
  Logged in users: 
  
  

  
  cURL command for getting info on logged in users:
  
  

  curl --location --request GET 'https://192.168.168.168/api/sonicos/user/status/logged-in/all' \
--header 'Content-Type: application/Json' \
--header 'Accept: application/Json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiYWRtaW4ifQ.uiagV4VWK_4wgyLLbZYWwhCWmIkhg3t6yJDTqSu-ZCtu6fWQH55yxjmWkedlGpoZA4in1qlGW5CbpdCKDKhoGQ' \
--data '{"override" : true}'
  
  

Step 4: Log out admin from API session

 It is recommended to log out from SonicWall via API once the desired configuration is committed. Since there were no changes made, the commit step can be skipped

cURL command for logout:

curl --location --request DELETE 'https://192.168.168.168/api/sonicos/auth' \
--header 'Authorization: *****'

In the last screenshot, the Bearer Token is parsed to an environmental variable and used in the Token section.