Fortinet black logo

REST API Solution Guide

Authentication (/auth/)

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.

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

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, FortiToken Cloud, 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 General 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

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.

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

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, FortiToken Cloud, 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 General 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