API用户

2025/10/29大约 4 分钟

API用户

重要

API文档获取方式请参考：系统管理→FortiGuard管理→注册指南→API文档获取章节。

用户创建

进入GUI的“系统管理→管理员”页面，点击“新建”按钮，选择“REST API管理员”。
配置API用户名与“管理员配置”，这里以预置的“super_admin_readonly”为例。按需要配置“PKI组”、“CORS允许源”、“信任的主机”配置。
- 管理员配置：选择API用户的管理员权限配置（配置请参考“系统管理→管理员配置→管理员设置”章节，在GUI下，只能选择“super_admin_readonly”、“admin_no_access”以及自定义的管理员权限文件。如果需要选择预置的“super_admin”和“prof_admin”，需要在CLI下配置。
- PKI组：在API key认证的基础上开启REST API客户端证书认证，只有此PKI组中的证书用户可以访问API。
- CORS允许源：当REST API客户端是通过跨域请求（CORS）的方式访问FortiGate的API时，需要允许CORS的网站源地址（具体示例请见“系统管理→FortiGuard管理→API文档获取”中的“ 通过FNDN使用API”部分）。
- 信任的主机：限制允许访问的REST API客户端IP。
点击“确认”按钮后，会生成API key。注意该API key只会在这里显示一次，请妥善保存API key。

API用户创建完成。

config system api-user
    edit "api_user"
        set api-key ENC SH281AhpqGoK53Cq8e/pcf89amfyatlAMsh3uP0427kvqCNdFFZViV9L6q11ao=
        set accprofile "super_admin_readonly"
        config trusthost
            edit 1
                set ipv4-trusthost 192.168.100.0 255.255.255.0
            next
        end
    next
end

其他选项

CLI配置

config system api-user
    edit <user_name>
        set comments <string>
        set api-key ************    <----只能系统生成，无法在CLI中指定
        set accprofile <admin_accprofile>
        set schedule <schedule_object>
        set cors-allow-origin "https://fndn.fortinet.net"
        set peer-auth enable
        set peer-group <group>
        config trusthost
            edit 1
                set type ipv4-trusthost
                set ipv4-trusthost <class_ip&net_netmask>
            next
            edit 2
                set type ipv6-trusthost
                set ipv6-trusthost <class_ip&net_netmask>
            next
            ...
        end
    next
end

生成API key

由系统生成或重新生成API key，该key无法在CLI中指定。

execute api-user generate-key <API username>

execute api-user generate-key api_user

从FortiOS 7.6.0版本开始，可以配置API key的过期时间，单位为min。

execute api-user generate-key <API username> <expiry time>

execute api-user generate-key api_user 480

API PKI组认证

配置PKI用户，指定用于REST API客户端认证使用的证书用户，这些信息可以从用于REST API客户端认证的用户证书属性中找到。
```
config user peer
    edit "pki_user"
        set mandatory-ca-verify enable    <----默认开启
        set ca "DigiCertGlobalRootG2"
        set subject "CN = handbook.fortinet.com.cn"
        set cn "handbook.fortinet.com.cn"
    next
end
```
重要
mandatory-ca-verify选项：
- enable：需要将API客户端证书对应的CA证书安装在FortiGate上（导入方法参考：系统管理→系统设置→证书管理章节），认证时FortiGate会验证客户端证书是否与set ca指定的CA证书匹配（默认启用）。同时也要验证客户端提供的证书中的字段是否与PKI用户中配置的一致。
- disable：只要API客户端提供的证书中的属性与PKI用户中配置的一致，FortiGate即认为客户端证书有效。
- 验证证书字段有3种方式：Subject、CN或LDAP，所有字符串比较均区分大小写。

创建用户组引用PKI用户。

config user group
    edit "api_usergrp"
        set member "pki_user"
    next
end

在API用户中开启“PKI组”认证，并引用PKI用户组。

config system api-user
    edit api_user
        set peer-auth enable
        set peer-group api_usergrp
    next
end

API客户端可以使用如下命令指定API访问时使用的证书文件以及API key。

# curl -k --key ./<user private key> --cert <path of user certificate> https://<IP/FQDN>/api/v2/cmdb/firewall/address/?access_token=<api_key>

# curl -k --key ./useKeyr.pem --cert ./handbook.fortinet.com.cn.crt https://192.168.100.99/api/v2/cmdb/firewall/address/?access_token=bbQfw68qrnyN3yyybznGtgGx897qH3

FortiGate可以正确返回API查询结果。

* Server certificate:
* subject: C=US; ST=California; L=Sunnyvale; O=Fortinet; OU=FortiGate; CN=FGVM020000158352; emailAddress=support@fortinet.com
* start date: Oct 23 11:04:36 2019 GMT
* expire date: Jan 19 03:14:07 2056 GMT
* common name: FG101FTK2000XXXX
* issuer: C=US; ST=California; L=Sunnyvale; O=Fortinet; OU=Certificate Authority; CN=fortinet-subca2001; emailAddress=support@fortinet.com
::: important
GET /api/v2/cmdb/firewall/address/?access_token=bbQfw68qrnyN3yyybznGtgGx897qH3 HTTP/1.1
Host: FG101FTK2000XXXX
User-Agent: curl/8.7.1
Accept: */*

:::
< HTTP/1.1 200 OK
< Date: Wed, 08 Jul 2025 17:19:13 GMT
< Server: Apache
< X-Frame-Options: SAMEORIGIN
< Content-Security-Policy: frame-ancestors 'self'
< X-XSS-Protection: 1; mode=block
< Strict-Transport-Security: max-age=0
< X-UA-Compatible: IE=Edge
< Cache-Control: no-cache, must-revalidate
< ETag: 2a3997e13943e98865004c368a65a8de
< Content-Length: 7940
< Content-Type: application/json
<
{
"http_method":"GET",
"revision":"2a3997e13943e98865004c368a65a8de",
"results":[
{
"name":"FABRIC_DEVICE",
"q_origin_key":"FABRIC_DEVICE",
"uuid":"0f1a2390-525c-51f0-2ad2-b213f4cba84b",
"subnet":"0.0.0.0 0.0.0.0",
"type":"ipmask",
"sub-type":"sdn",
"clearpass-spt":"unknown",
"start-mac":"00:00:00:00:00:00",
"end-mac":"00:00:00:00:00:00",
"country":"",
"cache-ttl":0,
"sdn":"",
"fsso-group":[
],
......