Fortinet black logo

REST API Solution Guide

LDAP users (/ldapusers/)

LDAP users (/ldapusers/)

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

This endpoint represents imported remote LDAP user resource. This can be found in the FortiAuthenticator GUI under Authentication > Remote Auth. Servers > LDAP.

Supported fields

Field Display name Type Required Other restrictions
username Username string Yes Read-only
dn Distinguished name string Yes Read-only
server_name Server name string No Read-only
server_address Server address string No Read-only
email E-mail address string No Must be a valid e-mail address
first_name First name string No max length = 30
last_name Last name string No max length = 30
active Account Status boolean No
mobile_number Mobile number string No max length = 25, must follow international number format: +[country_code]-[number]
token_auth Token Auth boolean No Whether second factor authentication should be enabled. If true, token_type is required.
token_type Token Type string No One of ftk, ftm, ftc, email, sms, or dual. If email is chosen, email is required. If SMS is chosen, mobile_number is required.
token_serial Token Serial string No If token_type is ftm, or ftk, and this is not present or blank, the next available token will be assigned.
ftm_act_method FTM Activation Delivery Method string No One of email or sms. If email is chosen, email is required. If SMS is chosen, mobile_number is required. Both are required if dual is selected.
password Password string No max length = 50
recovery_by_question Allow password recovery with security question boolean No
recovery_question Password recovery security question string No Required if recovery_by_question is set to true.
recovery_answer Password recovery security answer string No Required if recovery_by_question is set to true.

Allowed methods

HTTP method Resource URI Action
GET /api/v1/ldapusers/ Get all non-admin LDAP users.
GET /api/v1/ldapusers/[id]/ Get a specific non-admin LDAP user.
POST /api/v1/ldapusers/[id]/sendoobtoken/ Send an out-of-band token code (email/SMS token) to an LDAP user.
POST /api/v1/ldapusers/[id]/verifyrecoveryanswer/ Verify the recovery answer for a specific LDAP user. Note: recovery_answer must be included.
PATCH /api/v1/ldapusers/[id]/ Update specified fields for a specific LDAP user with ID.

Allowed filters

Field Lookup expressions Values
username exact, iexact, contains, icontains, in
dn exact, iexact, contains, icontains
first_name exact, iexact, contains, icontains, in
last_name exact, iexact, contains, icontains, in
email exact, iexact, contains, icontains, in
active exact
server_name exact, iexact, contains, icontains
server_address exact, iexact, contains, icontains
token_type ftk, ftm, ftc, email, sms
token_serial exact, iexact

Third-party integration: FTM provisioning

For integration with a third-party authentication server which needs to manage token validation, it is possible for the FortiAuthenticator to return FTM seed during provisioning. However, certain conditions must be met:

  • Seed may only be returned when provisioning an FTM to an existing user via PATCH method.
  • A GET URL parameter (returnseed=1) needs to be specified to explicitly tell FortiAuthenticator to return an encrypted seed for the token (e.g. https://[server_name]/api/v1/ldapusers/2/?returnseed=1).
  • A seed encryption passphrase must be specified in FortiGuard settings.

The seed is encrypted and returned as a PSKC XML file string according to RFC 6030. The key is derived from the configured passphrase using the PBKDF2 key derivation function (32 byte key length, 1000 iterations), encrypted with AES 256 CBC encryption, and signed with a SHA256 HMAC.

Whenever an FTM is provisioned, its activation code will be returned as well.

LDAP users (/ldapusers/)

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

This endpoint represents imported remote LDAP user resource. This can be found in the FortiAuthenticator GUI under Authentication > Remote Auth. Servers > LDAP.

Supported fields

Field Display name Type Required Other restrictions
username Username string Yes Read-only
dn Distinguished name string Yes Read-only
server_name Server name string No Read-only
server_address Server address string No Read-only
email E-mail address string No Must be a valid e-mail address
first_name First name string No max length = 30
last_name Last name string No max length = 30
active Account Status boolean No
mobile_number Mobile number string No max length = 25, must follow international number format: +[country_code]-[number]
token_auth Token Auth boolean No Whether second factor authentication should be enabled. If true, token_type is required.
token_type Token Type string No One of ftk, ftm, ftc, email, sms, or dual. If email is chosen, email is required. If SMS is chosen, mobile_number is required.
token_serial Token Serial string No If token_type is ftm, or ftk, and this is not present or blank, the next available token will be assigned.
ftm_act_method FTM Activation Delivery Method string No One of email or sms. If email is chosen, email is required. If SMS is chosen, mobile_number is required. Both are required if dual is selected.
password Password string No max length = 50
recovery_by_question Allow password recovery with security question boolean No
recovery_question Password recovery security question string No Required if recovery_by_question is set to true.
recovery_answer Password recovery security answer string No Required if recovery_by_question is set to true.

Allowed methods

HTTP method Resource URI Action
GET /api/v1/ldapusers/ Get all non-admin LDAP users.
GET /api/v1/ldapusers/[id]/ Get a specific non-admin LDAP user.
POST /api/v1/ldapusers/[id]/sendoobtoken/ Send an out-of-band token code (email/SMS token) to an LDAP user.
POST /api/v1/ldapusers/[id]/verifyrecoveryanswer/ Verify the recovery answer for a specific LDAP user. Note: recovery_answer must be included.
PATCH /api/v1/ldapusers/[id]/ Update specified fields for a specific LDAP user with ID.

Allowed filters

Field Lookup expressions Values
username exact, iexact, contains, icontains, in
dn exact, iexact, contains, icontains
first_name exact, iexact, contains, icontains, in
last_name exact, iexact, contains, icontains, in
email exact, iexact, contains, icontains, in
active exact
server_name exact, iexact, contains, icontains
server_address exact, iexact, contains, icontains
token_type ftk, ftm, ftc, email, sms
token_serial exact, iexact

Third-party integration: FTM provisioning

For integration with a third-party authentication server which needs to manage token validation, it is possible for the FortiAuthenticator to return FTM seed during provisioning. However, certain conditions must be met:

  • Seed may only be returned when provisioning an FTM to an existing user via PATCH method.
  • A GET URL parameter (returnseed=1) needs to be specified to explicitly tell FortiAuthenticator to return an encrypted seed for the token (e.g. https://[server_name]/api/v1/ldapusers/2/?returnseed=1).
  • A seed encryption passphrase must be specified in FortiGuard settings.

The seed is encrypted and returned as a PSKC XML file string according to RFC 6030. The key is derived from the configured passphrase using the PBKDF2 key derivation function (32 byte key length, 1000 iterations), encrypted with AES 256 CBC encryption, and signed with a SHA256 HMAC.

Whenever an FTM is provisioned, its activation code will be returned as well.