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.
|
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.