Authentication (/auth/)

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

This authentication API is for validation of user credentials. Either the password, token or both can be validated. This is useful for adding an additional factor authentication (e.g. token) to web portals where the first factor as already being validated locally e.g. via LDAP and RADIUS user credentials, or local DB or a proprietary, unsupported authentication method as is common in the banking industry.

This API is for the validation of local user password and token passcode or remote user passcode only. Validation of remote (LDAP) user password is not supported. This is by design as most systems have an established mechanism for authentication via e.g. LDAP or some other proprietary mechanism as shown below.

User lockout policies can be configured under Authentication > User Account Policies > Lockouts. The policies will be applied as configured.

To authenticate a user, you need to POST to https://[server_name]/api/1/auth/ with the following key-value pair (in JSON format, but XML also possible):

{"username": "<username>", "token_code": "<token_code>", "password": "<password>"}

with "token_code" and "password" being optional fields i.e. you can just validate the token only or the password only. If password and token are specified, the password will be validated first before token code.

Behavior of the API

Either password or token_code needs to be specified.
If both are specified, password will be validated first, then token_code.
If both are specified, it is acceptable to concatenate both the user's password and token code in as the password value and provide an empty string as the token_code value.
If only one is specified (either password or token_code), only that credential will be validated.
If a user doesn't have two-factor authentication configured, validation for that user with any token_code will fail.
If a user is configured with only FortiToken authentication (password-based authentication is disabled), specifying any password will fail.

Before being able to validate an email token or SMS token, a token code needs to be triggered and sent to the user.

Please refer to either Local users (/localusers/), LDAP users (/ldapusers/) or RADIUS users (/radiususers/) documentation on how to send the token code.

Supported fields

Field	Display name	Type	Required	Other restrictions
username	Username	string	Yes
password	Password	string	No
token_code	Security token code	string	No	Supported token authentication: FortiToken, email token, SMS token

Allowed methods

Type	Allowed methods	Action
List	POST	Validate user's credentials.

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		User is successfully authenticated.
401 Unauthorized	User authentication failed	Credential is incorrect.
401 Unauthorized	Account is disabled	User account is currently disabled.
401 Unauthorized	No token configured	User does not have token-based authentication configured.
401 Unauthorized	Token is out of sync	The security token requires synchronization.
404 Not Found	User does not exist	The given username does not exist in the system.

Validate a user password

Query

JSON specified via Accept Header

curl -k -v -u "admin:zeyDZXmP6GbKcerqdWWEYNTnH2TaOCz5HTp2dAVS" -d '{"username":"testuser","password":"testpass"}' -H "Content-Type: application/json" https://192.168.0.122/api/v1/auth/

Response

< HTTP/1.1 200 OK

< Date: Fri, 14 Sep 2012 15:38:57 GMT

< Server: Apache

< Vary: Cookie

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

< Content-Length: 0

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

Validate a users token code

Query

JSON specified via Content-Type Header

curl -k -v -u "admin:zeyDZXmP6GbKcerqdWWEYNTnH2TaOCz5HTp2dAVS" -d '{"username":"testuser","token_code":"893753"}' -H "Content-Type: application/json" https://192.168.0.122/api/v1/auth/

Response

< HTTP/1.1 200 OK

< Date: Fri, 14 Sep 2012 15:47:22 GMT

< Server: Apache

< Vary: Cookie

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

< Content-Length: 0

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

Error states

Response (incorrect password)

HTTP/1.1 401 UNAUTHORIZED

Date: Thu, 13 Sep 2012 13:57:24 GMT

Server: Apache

Vary: Cookie

Set-Cookie: sessionid=abe8bac6fc50caf5eadf1e57f0c60e3e; httponly; Path=/

Content-Length: 26

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

Response (incorrect token code)

HTTP/1.1 401 UNAUTHORIZED

Date: Thu, 13 Sep 2012 13:55:18 GMT

Server: Apache

Vary: Cookie

Set-Cookie: sessionid=e95090804ee0e3b8903618138b38a5c8; httponly; Path=/

Content-Length: 26

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

Response (incorrect username)

HTTP/1.1 404 NOT FOUND

Date: Thu, 13 Sep 2012 13:58:54 GMT

Server: Apache

Vary: Cookie

Set-Cookie: sessionid=3b353061d9141567c02bb0d057b18284; httponly; Path=/

Content-Length: 19

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