FortiGate REST API Token Authentication
Before going through this article, please go over the first part of this series: Getting Started With FortiGate REST API.
In order to use the FortiOS REST API, you are required to authenticate your API calls using an API token. You can generate an API token by creating a new REST API admin. The unique token will be used to authorize subsequent API calls to your FortiGate device.
These steps should be carried out from the FortiGate GUI, while logged in as a super admin. Please note that I am using a FortiGate 6.0.3 virtual machine for this tutorial.
Determine your IP address
- Navigate to the dashboard section on the FortiGate GUI, click on Main and locate the Administrators widget.
- In the administrators’ widget, hover your mouse over it, you’ll see all current admins, select the show active administrator sessions from your user ID.
- Copy the source IP address for your-userid as it will be needed to specify trusted hosts in a later step of creating a REST API Admin.
Learn how to use basic and advanced FortiGate features, including security profiles, networking and security. Get started with the Fortinet NSE 4 bundle training.
Create an Administrator profile
For a start, we will create a profile that only has READ access to the firewall address permission group. For the administrator profile, you can select one of the existing ones or create a new one by clicking on the create icon.
The new admin profile will require a name and access permissions.
Name your admin profile appropriately. For this part, it will be Firewall_Read. You can change any of the access control permissions to specifically restrict or limit the functionality.
As a good practice, the REST API admin should have the minimum permissions required to complete the request.
In this section, we only need access to the firewall address permission group. Populate the fields as shown in the image below.
Click OK to create the Firewall_Read admin profile with only the Firewall and Address permissions changed as shown. A REST API admin with read-only permission to a resource can only send read requests (HTTP GET) to the resource.
FortiGate: Create a REST API Admin
To generate a new REST API admin:
- Navigate the FortiGate GUI, click on System and select administrators
- Click on the Create New icon and choose REST API admin
The New REST API admin window will show up. Give it a descriptive name for the API user. In our case, it will be Firewall_Read_User.
Disable the public key infrastructure (PKI Group) as it will not be used at the moment. ‘CORS Allow Origin’ will also stay disabled for the moment.
In the trusted hosts’ field, paste the IP address from previously seen active administrator sessions, and with forward-slash(/32) in order to match your trusted source IP address only.
Also, in the REST API administrator, you are required to restrict access to one or more trusted subnets. To ensure the API token can only be used from trusted hosts, the source address needs to be specified!
The new REST API admin can now be confirmed by clicking OK.
The system will automatically generate a new API key, this key will only be displayed once. Please copy that key and hit close. If you lose your API key and you want to generate a new one, you can do so, by going back to administrator and click on the regenerate icon, the regenerated API key will once again be unique and all previous keys will be invalidated.
How To Create a REST API admin using the CLI
Modify the sample below to create the REST API admin.
config system api-user edit "Firewall_Read_User" set comments "REST API admin with firewall read only permission." set api-key SH23sQt?+/9D9/mKb1oQoDvlP32ggn/cpQeGcY /VGU= set accprofile "Firewall_Read" set vdom "root" config trusthost edit 1 set ipv4-trusthost 10.0.1.10 255.255.255.255 next end next end
Then generate an API token using the CLI command below. Make note of the token as it is only shown once:
execute api-user generate-key Firewall_Read_User