Fortinet Document Library

Version:

Version:

Version:

Version:

Version:

Version:

Version:

Version:


Table of Contents

REST API Solution Guide

Realm authentication (/realmauth/)

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

This end-point is used to validate local, LDAP and RADIUS user credentials based on realm.

Note

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

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

Before being able to validate an email token or SMS token, a token code needs to be sent to the user first. Please refer to either /localusers, /ldapusers or /radiususers documentation on how to send the token code.

Supported fields

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

Allowed fields

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.

Realm authentication (/realmauth/)

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

This end-point is used to validate local, LDAP and RADIUS user credentials based on realm.

Note

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

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

Before being able to validate an email token or SMS token, a token code needs to be sent to the user first. Please refer to either /localusers, /ldapusers or /radiususers documentation on how to send the token code.

Supported fields

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

Allowed fields

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.