Fortinet Document Library

Version:

Version:

Version:


Table of Contents

REST API Solution Guide

Download PDF
Copy Link

SSO authentication (/ssoauth/)

URL:  https://[server_name]/api/[api_version]/ssoauth/

This endpoint represents the Fortinet SSO Authentication. This resource can be found in the FortiAuthenticator GUI under Fortinet SSO Methods > SSO. This API is for use by third-party authentication systems for dynamic transparent user Single Sign-on to a Fortinet protected network.

note icon Before attempting to authenticate, additional configuration is required under Fortinet SSO Methods > Portal Services > SSO Web Service to select which user directory is to be used for group embellishment.

Supported fields

Field Display name Type Required Other restrictions
event Event type integer/string
Yes 1=Logon
0=Logoff
username User's username string Yes max length=253
user_ip User's workstation IP (Calling-Station-Id) IPv4 Yes  
user_ipv6 User's workstation IPv6 (Calling-Station-Id) IPv6 No One of 'user_ip' or 'user_ipv6' is required
user_groups Groups to send (Fortinet-Group-Name) string No max length=253, list of groups must be separated with "+" character (group name cannot contain a "+" character)

For local users, the user must be part of a local group for successful SSO logon.

External users must have a group passed in via the user_groups field for logon/logoff.

Allowed methods

HTTP method Resource URI Action
POST api/v1/ssoauth/ Logon/logoff users to/from FSSO

Response codes

In addition to the general codes defined in Appendix A – API response codes, a POST request to this resource can result in the following return codes:

Code Response content Description
200 OK   FSSO login/logout request has been successfully sent to FSSO (but this doesn't mean that user has been logged-on/off, as the request is done asynchronously and is queued on FSSO side. Factors such as configuration and user not rxisting in LDAP may cause the entry to not populate FSSO).
404 Not Found SSO web service is disabled SSO web service has not been enabled so it can't be used in REST API
500 Internal Server Error   Failed to send logon/logoff request to FSSO

FSSO user login

JSON query

  • JSON specified via Accept Header

curl -k -v -u "admin:zeyDZXmP6GbKcerqdWWEYNTnH2TaOCz5HTp2dAVS" -d '{"event":"1","username":"cwindsor","user_ip":"10.1.73.175"}' -H "Content-Type: application/json" https://192.168.0.122/api/v1/ssoauth/

 

Response

< HTTP/1.1 200 OK

< Date: Fri, 20 Sep 2013 08:27:27 GMT

< Server: Apache

< Vary: Accept,Accept-Language,Cookie

< Content-Language: en

< Set-Cookie: sessionid=6q6m6ne4v7p76qclajitlf2q7202f7g6; httponly; Path=/

< Content-Length: 0

< Content-Type: text/html; charset=utf-8

<

* Connection #0 to host 192.168.0.122 left intact

* Closing connection #0

 

Verify login on FortiAuthenticator from Monitor > SSO > SSO Sessions.

Overwrite FSSO user login with different user

Note that if a login event is received with the same IP address but with a different username, the existing entry will be overwritten.

JSON query

  • JSON specified via Accept Header

curl -k -v -u "admin:zeyDZXmP6GbKcerqdWWEYNTnH2TaOCz5HTp2dAVS" -d '{"event":"1","username":"atano","user_ip":"10.1.73.175"}' -H "Content-Type: application/json" https://192.168.0.122/api/v1/ssoauth/

 

Response

< HTTP/1.1 200 OK

< Date: Fri, 20 Sep 2013 08:32:21 GMT

< Server: Apache

< Vary: Accept,Accept-Language,Cookie

< Content-Language: en

< Set-Cookie: sessionid=g062qqmsj6nr0hk5khd2q7202e4v36m; httponly; Path=/

< Content-Length: 0

< Content-Type: text/html; charset=utf-8

<

* Connection #0 to host 192.168.0.122 left intact

* Closing connection #0

 

Verify login on FortiAuthenticator from Monitor > SSO > SSO Sessions.

Logout FSSO user

JSON query

  • JSON specified via Accept Header

curl -k -v -u "admin:zeyDZXmP6GbKcerqdWWEYNTnH2TaOCz5HTp2dAVS" -d '{"event":"0","username":"atano","user_ip":"10.1.73.175"}' -H "Content-Type: application/json" https://192.168.0.122/api/v1/ssoauth/

 

Response

< HTTP/1.1 200 OK

< Date: Fri, 20 Sep 2013 08:34:09 GMT

< Server: Apache

< Vary: Accept,Accept-Language,Cookie

< Content-Language: en

< Set-Cookie: sessionid=2q de4v36msj6g05khm6nr02q72q02hk; httponly; Path=/

< Content-Length: 0

< Content-Type: text/html; charset=utf-8

* Connection #0 to host 192.168.0.122 left intact

* Closing connection #0

 

Verify logout on FortiAuthenticator from Monitor > SSO > SSO Sessions.

Logging

Note that SSO Login requests are logged regardless of whether the user details can be inserted into FSSO. For example logs may exist for SSO Logon for a user but an entry not appear in the monitor because when an LDAP lookup for group info was performed, no user existed.

SSO authentication (/ssoauth/)

URL:  https://[server_name]/api/[api_version]/ssoauth/

This endpoint represents the Fortinet SSO Authentication. This resource can be found in the FortiAuthenticator GUI under Fortinet SSO Methods > SSO. This API is for use by third-party authentication systems for dynamic transparent user Single Sign-on to a Fortinet protected network.

note icon Before attempting to authenticate, additional configuration is required under Fortinet SSO Methods > Portal Services > SSO Web Service to select which user directory is to be used for group embellishment.

Supported fields

Field Display name Type Required Other restrictions
event Event type integer/string
Yes 1=Logon
0=Logoff
username User's username string Yes max length=253
user_ip User's workstation IP (Calling-Station-Id) IPv4 Yes  
user_ipv6 User's workstation IPv6 (Calling-Station-Id) IPv6 No One of 'user_ip' or 'user_ipv6' is required
user_groups Groups to send (Fortinet-Group-Name) string No max length=253, list of groups must be separated with "+" character (group name cannot contain a "+" character)

For local users, the user must be part of a local group for successful SSO logon.

External users must have a group passed in via the user_groups field for logon/logoff.

Allowed methods

HTTP method Resource URI Action
POST api/v1/ssoauth/ Logon/logoff users to/from FSSO

Response codes

In addition to the general codes defined in Appendix A – API response codes, a POST request to this resource can result in the following return codes:

Code Response content Description
200 OK   FSSO login/logout request has been successfully sent to FSSO (but this doesn't mean that user has been logged-on/off, as the request is done asynchronously and is queued on FSSO side. Factors such as configuration and user not rxisting in LDAP may cause the entry to not populate FSSO).
404 Not Found SSO web service is disabled SSO web service has not been enabled so it can't be used in REST API
500 Internal Server Error   Failed to send logon/logoff request to FSSO

FSSO user login

JSON query

  • JSON specified via Accept Header

curl -k -v -u "admin:zeyDZXmP6GbKcerqdWWEYNTnH2TaOCz5HTp2dAVS" -d '{"event":"1","username":"cwindsor","user_ip":"10.1.73.175"}' -H "Content-Type: application/json" https://192.168.0.122/api/v1/ssoauth/

 

Response

< HTTP/1.1 200 OK

< Date: Fri, 20 Sep 2013 08:27:27 GMT

< Server: Apache

< Vary: Accept,Accept-Language,Cookie

< Content-Language: en

< Set-Cookie: sessionid=6q6m6ne4v7p76qclajitlf2q7202f7g6; httponly; Path=/

< Content-Length: 0

< Content-Type: text/html; charset=utf-8

<

* Connection #0 to host 192.168.0.122 left intact

* Closing connection #0

 

Verify login on FortiAuthenticator from Monitor > SSO > SSO Sessions.

Overwrite FSSO user login with different user

Note that if a login event is received with the same IP address but with a different username, the existing entry will be overwritten.

JSON query

  • JSON specified via Accept Header

curl -k -v -u "admin:zeyDZXmP6GbKcerqdWWEYNTnH2TaOCz5HTp2dAVS" -d '{"event":"1","username":"atano","user_ip":"10.1.73.175"}' -H "Content-Type: application/json" https://192.168.0.122/api/v1/ssoauth/

 

Response

< HTTP/1.1 200 OK

< Date: Fri, 20 Sep 2013 08:32:21 GMT

< Server: Apache

< Vary: Accept,Accept-Language,Cookie

< Content-Language: en

< Set-Cookie: sessionid=g062qqmsj6nr0hk5khd2q7202e4v36m; httponly; Path=/

< Content-Length: 0

< Content-Type: text/html; charset=utf-8

<

* Connection #0 to host 192.168.0.122 left intact

* Closing connection #0

 

Verify login on FortiAuthenticator from Monitor > SSO > SSO Sessions.

Logout FSSO user

JSON query

  • JSON specified via Accept Header

curl -k -v -u "admin:zeyDZXmP6GbKcerqdWWEYNTnH2TaOCz5HTp2dAVS" -d '{"event":"0","username":"atano","user_ip":"10.1.73.175"}' -H "Content-Type: application/json" https://192.168.0.122/api/v1/ssoauth/

 

Response

< HTTP/1.1 200 OK

< Date: Fri, 20 Sep 2013 08:34:09 GMT

< Server: Apache

< Vary: Accept,Accept-Language,Cookie

< Content-Language: en

< Set-Cookie: sessionid=2q de4v36msj6g05khm6nr02q72q02hk; httponly; Path=/

< Content-Length: 0

< Content-Type: text/html; charset=utf-8

* Connection #0 to host 192.168.0.122 left intact

* Closing connection #0

 

Verify logout on FortiAuthenticator from Monitor > SSO > SSO Sessions.

Logging

Note that SSO Login requests are logged regardless of whether the user details can be inserted into FSSO. For example logs may exist for SSO Logon for a user but an entry not appear in the monitor because when an LDAP lookup for group info was performed, no user existed.