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

Read Only

Other restrictions
username Username string Yes

Yes

dn Distinguished name string Yes

Yes

server_name Server name string No

Yes

server_address Server address string No

Yes

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

reason

Disable reason

interger

No

Default is 0. One of 0 (manually disabled), 1 (account inactivity), 2 (too many failed attempts), 3 (account expiry), 4 (password expiry), 5 (FTM activation expiry), 6 (revoked token), 7 (usage limit exceeded), or 8 (pending administrator approval).

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

Patching this attribute will effectively reset the password.

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

recovery_answer Password recovery security answer string Yes

Required if recovery_by_question is true.

fido

FIDO

boolean

No

No

Default is disabled.

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.

DELETE

/api/v1/ldapusers/[id]/

Delete an LDAP user.

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

Read Only

Other restrictions
username Username string Yes

Yes

dn Distinguished name string Yes

Yes

server_name Server name string No

Yes

server_address Server address string No

Yes

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

reason

Disable reason

interger

No

Default is 0. One of 0 (manually disabled), 1 (account inactivity), 2 (too many failed attempts), 3 (account expiry), 4 (password expiry), 5 (FTM activation expiry), 6 (revoked token), 7 (usage limit exceeded), or 8 (pending administrator approval).

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

Patching this attribute will effectively reset the password.

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

recovery_answer Password recovery security answer string Yes

Required if recovery_by_question is true.

fido

FIDO

boolean

No

No

Default is disabled.

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.

DELETE

/api/v1/ldapusers/[id]/

Delete an LDAP user.

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.