Fortinet Document Library

Version:

Version:

Version:


Table of Contents

Download PDF
Copy Link

FortiToken provisioning with FortiAuthenticator REST API

The FortiAuthenticator API can be accessed (without additional cost or licensing) so that third-party user provisioning systems can confirm which FortiTokens are available to be provisioned to a user.

For the API to be accessible, a user must be granted administrator privileges so that they can log in. To view the FortiToken resource, cURL is being used to make the requests. For more information on how to do this, see the FortiAuthenticator REST API Solution Guide.

Accessing the REST API

To access the REST API resource, you must browse to the following URL:

https://[server_name]/api/[api_version]/[resource]/

  • server_name: Name or IP address of the FortiAuthenticator.
  • api_version: API version to be used (currently v1).
  • resource: Resource of part of config to be viewed.

For the purposes of accessing FortiToken information, the resource is /fortitokens/.

To view a list of all the available resource end-points, send a request to https://[server_name]/api/v1/?format=xml.

FortiToken resource - /fortitokens/

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

In this FortiAuthenticator GUI, this resource corresponds to Authentication > User Management > FortiTokens. As mentioned earlier, this API is used by third-party user provisioning systems to confirm which FortiTokens are available to be provisioned to a user.

Supported Fields

Field Display Name Type Required Other Restriction
serial Serial number string No  
type Type string No Either ftk or ftm.
status Status string No Either new, available, pending, or assigned.

Allowed methods

Type Allowed Methods Action
List GET Get all FortiTokens.

Allowed filters

Field Lookup Expressions Values
serial exact, iexact  
type exact, iexact Either ftk or ftm.
status exact, iexact Either new, available, pending, or assigned.

View all tokens

JSON Query
  • JSON specified via GET

curl -k -v -u "admin:zeyDZXmP6GbKcerqdWWEYNTnH2TaOCz5HTp2dAVS" https://192.168.0.122/api/v1/fortitokens/?format=json

Response

< HTTP/1.1 200 OK

< Date: Mon, 09 Jun 2014 18:17:42 GMT

< Server: Apache

< Vary: Accept,Accept-Language,Cookie

< X-Frame-Options: SAMEORIGIN

< Content-Language: en

< Cache-Control: no-cache

< Transfer-Encoding: chunked

< Content-Type: application/json

<

* Connection #0 to host 192.168.0.122 left intact

* Closing connection #0

{"meta": {"limit": 20, "next": null, "offset": 0, "previous": null, "total_count": 2},

"objects": [{"resource_uri": "/api/v1/fortitokens/1/", "serial": "FTKMOB44142CCBF3",

"status": "available", "type": "ftm"}, {"resource_uri": "/api/v1/fortitokens/2/",

"serial": "FTKMOB4471BB94D1", "status": "available", "type": "ftm"}]}

View subset of tokens using filters

This example shows how to obtain a list of specific tokens, for example the first available FortiToken Mobile (FTM) token.

JSON Query
  • JSON specified via GET

curl -k -v -u "admin:zeyDZXmP6GbKcerqdWWEYNTnH2TaOCz5HTp2dAVS" -H 'Accept:

application/json'

"https://192.168.0.122/api/v1/fortitokens/?format=json&type=ftm&status=available&limit

=1"

The URL requires additional quoting in this case otherwise the Unix CLI treats the "&" as an instruction to place the cURL command into the background.
Response

< HTTP/1.1 200 OK

< Date: Mon, 09 Jun 2014 18:17:42 GMT

< Server: Apache

< Vary: Accept,Accept-Language,Cookie

< X-Frame-Options: SAMEORIGIN

< Content-Language: en

< Cache-Control: no-cache

< Transfer-Encoding: chunked

< Content-Type: application/json

<

* Connection #0 to host 192.168.0.122 left intact

* Closing connection #0

{"meta": {"limit": 1, "next":

"/api/v1/fortitokens/?status=available&type=ftm&offset=1&limit=1&format=json",

"offset": 0, "previous": null, "total_count": 2}, "objects": [{"resource_uri":

"/api/v1/fortitokens/1/", "serial": "FTKMOB44142CCBF3", "status": "available", "type":

"ftm"}]}

Authentication resource - /auth/

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

The 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 has already been locally validated (e.g. via LDAP, local DB, or a proprietary, unsupported authentication method).

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

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

"<password>"}

 

The token_code and password fields are optional, i.e. you can validate the token only, or the password only.  If both token and password are specified, the password will be validated first before the token code. Furthermore, if a user doesn't have two-factor authentication configured, validation for that user with any token_code will fail.

Supported fields

Field Display Name Type Required Other Restriction
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 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 Credentials are 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.

To see the general response codes, see the FortiAuthenticator REST API Solution Guide (Appendix A - API Response Codes).

Validate a user password

JSON 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

JSON 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

FortiToken provisioning with FortiAuthenticator REST API

The FortiAuthenticator API can be accessed (without additional cost or licensing) so that third-party user provisioning systems can confirm which FortiTokens are available to be provisioned to a user.

For the API to be accessible, a user must be granted administrator privileges so that they can log in. To view the FortiToken resource, cURL is being used to make the requests. For more information on how to do this, see the FortiAuthenticator REST API Solution Guide.

Accessing the REST API

To access the REST API resource, you must browse to the following URL:

https://[server_name]/api/[api_version]/[resource]/

  • server_name: Name or IP address of the FortiAuthenticator.
  • api_version: API version to be used (currently v1).
  • resource: Resource of part of config to be viewed.

For the purposes of accessing FortiToken information, the resource is /fortitokens/.

To view a list of all the available resource end-points, send a request to https://[server_name]/api/v1/?format=xml.

FortiToken resource - /fortitokens/

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

In this FortiAuthenticator GUI, this resource corresponds to Authentication > User Management > FortiTokens. As mentioned earlier, this API is used by third-party user provisioning systems to confirm which FortiTokens are available to be provisioned to a user.

Supported Fields

Field Display Name Type Required Other Restriction
serial Serial number string No  
type Type string No Either ftk or ftm.
status Status string No Either new, available, pending, or assigned.

Allowed methods

Type Allowed Methods Action
List GET Get all FortiTokens.

Allowed filters

Field Lookup Expressions Values
serial exact, iexact  
type exact, iexact Either ftk or ftm.
status exact, iexact Either new, available, pending, or assigned.

View all tokens

JSON Query
  • JSON specified via GET

curl -k -v -u "admin:zeyDZXmP6GbKcerqdWWEYNTnH2TaOCz5HTp2dAVS" https://192.168.0.122/api/v1/fortitokens/?format=json

Response

< HTTP/1.1 200 OK

< Date: Mon, 09 Jun 2014 18:17:42 GMT

< Server: Apache

< Vary: Accept,Accept-Language,Cookie

< X-Frame-Options: SAMEORIGIN

< Content-Language: en

< Cache-Control: no-cache

< Transfer-Encoding: chunked

< Content-Type: application/json

<

* Connection #0 to host 192.168.0.122 left intact

* Closing connection #0

{"meta": {"limit": 20, "next": null, "offset": 0, "previous": null, "total_count": 2},

"objects": [{"resource_uri": "/api/v1/fortitokens/1/", "serial": "FTKMOB44142CCBF3",

"status": "available", "type": "ftm"}, {"resource_uri": "/api/v1/fortitokens/2/",

"serial": "FTKMOB4471BB94D1", "status": "available", "type": "ftm"}]}

View subset of tokens using filters

This example shows how to obtain a list of specific tokens, for example the first available FortiToken Mobile (FTM) token.

JSON Query
  • JSON specified via GET

curl -k -v -u "admin:zeyDZXmP6GbKcerqdWWEYNTnH2TaOCz5HTp2dAVS" -H 'Accept:

application/json'

"https://192.168.0.122/api/v1/fortitokens/?format=json&type=ftm&status=available&limit

=1"

The URL requires additional quoting in this case otherwise the Unix CLI treats the "&" as an instruction to place the cURL command into the background.
Response

< HTTP/1.1 200 OK

< Date: Mon, 09 Jun 2014 18:17:42 GMT

< Server: Apache

< Vary: Accept,Accept-Language,Cookie

< X-Frame-Options: SAMEORIGIN

< Content-Language: en

< Cache-Control: no-cache

< Transfer-Encoding: chunked

< Content-Type: application/json

<

* Connection #0 to host 192.168.0.122 left intact

* Closing connection #0

{"meta": {"limit": 1, "next":

"/api/v1/fortitokens/?status=available&type=ftm&offset=1&limit=1&format=json",

"offset": 0, "previous": null, "total_count": 2}, "objects": [{"resource_uri":

"/api/v1/fortitokens/1/", "serial": "FTKMOB44142CCBF3", "status": "available", "type":

"ftm"}]}

Authentication resource - /auth/

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

The 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 has already been locally validated (e.g. via LDAP, local DB, or a proprietary, unsupported authentication method).

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

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

"<password>"}

 

The token_code and password fields are optional, i.e. you can validate the token only, or the password only.  If both token and password are specified, the password will be validated first before the token code. Furthermore, if a user doesn't have two-factor authentication configured, validation for that user with any token_code will fail.

Supported fields

Field Display Name Type Required Other Restriction
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 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 Credentials are 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.

To see the general response codes, see the FortiAuthenticator REST API Solution Guide (Appendix A - API Response Codes).

Validate a user password

JSON 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

JSON 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