SSO API login for third party devices/softwares - SonicWall UTM

This document specifies the external Application Program Interface (API) for third-party devices, software, or scripts to pass its user login/logout notifications directly to the SonicWall firewall for SSO API.

It is needed to enable a Third‐party client on the SonicWall firewall to be able to use the API. It sends HTTPS requests to the API indicating user logins and user logouts. The SonicWall firewall can then apply configured per‐user policies for access rights, which may include user group memberships supplied by either the API or looked up via LDAP.

For more details, please refer to SSO API Reference Guide.

Step 1:  Configuration

This KB presumes that an SSO agent and Local/LDAP users are configured. For assistance, follow the KB articles below:

1. How can I configure Single Sign-On on SonicWall firewall? | SonicWall
2. How can I Install Single Sign On (SSO) software and configure the SSO feature? | SonicWall
   
3. How to integrate LDAP/Active Directory user authentication? | SonicWall
4. Steps to Import User group to the Sonicwall using LDAP | SonicWall
   

For the purpose of demonstration, this example has both Local Users and LDAP configured. I have 1 local user sso1 and 1 imported LDAP user 'user001' as part of 'groupb' OU. LDAP should be green and tests cleared.

Next, In the same page, we need the SSO agent enabled and 3rd party API enabled to accept the user notifications from API softwares/commands.

SSO should be configured and ready to accept notifications from user devices/softwares. The IP is where my SSO agent is configured.

The next step would be to add from where the SSO user is logging in. It can be a device or software or even a script that runs API. You need to specify this IP, so that SonicWall recognizes and allows the user to be mapped. This KB uses a shared secret, however, a certificate or both can also be used. 

The API client would not turn green unless the user is authenticated. Till then it would be Amber.

For this demonstration, we are using a 'Low (no shared secret verification)' Security level.

CAUTION:  The medium and low security levels are intended for testing or diagnostic purposes only and are not recommended for production use. High levels should always be used where security may be an issue. If the client sending requests over the SSO API consists of software or scripts that are running on a computer potentially at risk of getting malware installed, CSRF prevention should be enabled.

It is recommended to use a different port number for SSO calls and use a custom HTTPS port. I'm using the HTTPS management port.

Note that the options to select Certificate or Both for authentication of the client is only available if a dedicated HTTPS port number is used.

NOTE: Navigate to Device | Users | Settings and change the 'User authentication method' to LDAP+Local users if using imported users from LDAP

Step 2: API Content Format

Request Format

Messages passed over the SSO API are standard web HTTP requests. They are sent over HTTPS to the firewall’s web server, forming a REST‐conformant API as described here. The URI begins with a path that identifies the web service and/or collection (SSO and users, respectively). . The initial request line in the HTTP header of an API request gives the method, its
accompanying URI, and identifies a user by his or her IP address:

POST  api/sso/user HTTP/1.1                                To log in a user (with the IP address given in the content)

DELETE api/sso/user/ip-address HTTP/1.1         To log out the user at the given IP address

OPTIONS api/sso/user                                             To query the methods supported and the parameters that can be sent with them, making the API self‐describing

REST also specifies that requests passing content should give the format of the content in the request’s Content‐Type header.

Content-Type: application/json
Content-Type: application/xml

More details about the commands and responses in SSO API Reference Guide (sonicwall.com)

User Login

POST has the IP of SonicWall interface (10.x.x.65). And the IP in the body (192.168.168.20) of API data is where the SSO agent is installed.

200 OK means the user is successfully logged and can be verified under User | Status page of SonicWall. 

cURLcommand:

curl --location 'https://10.x.x.65/api/sso/user' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Content-Type: application/xml' \
--data '{
    "ip" : "192.168.168.20",
    "name": "sso1",
    "group" : "SSO-testing-Group",
    "group-lookup" : true
    
}'

User Logout

Logout with DELETE has the IP address of SonicWall interface (10.x.x.65) and the IP address of SSO agent  (192.168.168.20)  API call. Body only has the user name.

cURL command:

curl --location --request DELETE 'https://10.x.x.65/api/sso/user/192.168.168.20' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
    "name": "sso1"
}'

Multiple login can be done using array. The body of the POST call will have:

The body content is:

[
{ "ip": "ip-address-1", "name": "user-name", "domain": "dom-name" "type": "type-of-user", … },

{ "ip": "ip-address-2", "name": "user-name", "domain": "dom-name", "type": "type-of-user", … },

{ "ip": "ip-address-3", "name": "user-name", "domain": "dom-name", "type": "type-of-user", … },

{ "ip": "ip-address-4", "name": "user-name", "domain": "dom-name", "type": "type-of-user", … }
]

Reference:

SSO API Reference Guide (sonicwall.com)