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