Fortinet black logo

Administration Guide

Configuring API gateway rules

Configuring API gateway rules

To restrict API access, you can configure certain rules involving API key verification, API key carryover, API user grouping, sub-URL setting, and specified actions FortiWeb will take in case of any API call violation.

To create an API gateway rule

  1. Go to API Gateway > API Gateway Policy, and select the API Gateway Rule tab.
  2. Click Create New.
  3. Configure these settings:
    NameType a unique name that can be referenced in other parts of the configuration.
    Host StatusEnable to apply this rule only to HTTP requests for specific web hosts. Also configure Host.
    HostSelect the name of a protected host that the Host: field of an HTTP request must be in to match the API gateway rule.
    This option is available only if Host Status is enabled.
  4. Click OK.
  5. For Match URL Prefixes, configure the URL prefixes to be routed to the backend.
  • Click Create New.
  • Enter the Frontend Prefix; the frontend prefix is the URL path in a client call, for example, /fortiweb/, the URL is like this HTTPS://172.22.14.244/fortiweb/example.json?param=value.
  • Enter the Backend Prefix; the backend prefix is the path which the client request will be replaced with, for example, /api/v1.0/System/Status/.
    After the URL rewriting, the URL is like this HTTPS://10.200.3.183:90/api/v1.0/System/Status/example.json?param=value.
  • Click OK.
    You can enter multiple URL prefixes, which means multiple URL paths may math the API gateway rule.
  • For Request Settings, configure these settings:
    Attach HTTP HeaderInsert specific header lines into HTTP header.
    API Key VerificationWhen an user makes an API request, the API key will be included in HTTP header or parameter, FortiWeb obtains the API key from the request. When this option is enabled, FortiWeb verifies the key to check whether the key belongs to an valid API user.
    API Key Carried in

    Indicate where FortiWeb can find your API key in HTTP request:

    • HTTP Parameter

    • HTTP Header

    Available only when API Key Verification is Enable.

    Parameter NameEnter the parameter name in which FortiWeb can find the API key when API Key Carried in is HTTP Parameter.

    Available only when API Key Verification is Enable.
    Header Field NameEnter the header filed name in which FortiWeb can find the API key when API Key Carried in is HTTP Header.

    Available only when API Key Verification is Enable.
    Allow User GroupSelect a user group created in API User > API User Group to define which users have the persmission to access the API.

    Available only when API Key Verification is Enable.

    Per-user Rate Limit

    Limit API requests by users. Type the maximum number of API call requests allowed per user in a certain number of seconds.

    Rate LimitType the maximum number of API call requests allowed in a certain number of seconds.
  • For Sub-URL Settings, when the user's call matches the frontend prefix, you can also define a set of sub-URL rules to further define the subpaths.
    • Click Create New.
    • Configure these settings:
      HTTP MethodSelect the HTTP method from the drop down list.
      Type

      Select whether the URL Expression field must contain either:

      • Simple String—The field is a string that the request URL must exactly.

      • Regular Expression—The field is a regular expression that defines a set of matching URLs.

      URL Expression

      Depending on your selection in Type, enter either:

      • The literal URL, such as /folder1/index.htm that the HTTP request must contain in order to match the rule, or use wildcards to match multiple URLs, such as /folder1/* or /folder1/*/index.htm. The URL must begin with a slash ( / ).

      • A regular expression, such as ^/*.php, matching all and only the URLs to which the input rule should apply. The pattern does not require a slash ( / ).; however, it must at least match URLs that begin with a slash, such as /index.cfm.

        When you have finished typing the regular expression, click the >> (test) icon.
        This opens the Regular Expression Validator window where you can finetune the expression. For details, see Appendix E: Regular expressions

      API Key VerificationWhen an user makes an API request, the API key will be included in HTTP header or parameter, FortiWeb obtains the API key from the request. When this option is enabled, FortiWeb verifies the key to check whether the key belongs to an valid API user.
      Inherit API Key SettingWhen this option is enabled, you don't need to specify where the API key is carried. Instead, the Sub-URL settings will follow that in Request Settings.

      Available only when API Key Verification is Enable.
      API Key Carried in

      Indicate where FortiWeb can find your API key in HTTP request:

      • HTTP Parameter

      • HTTP Header

      Available only when API Key Verification is Enable and Inherit API Key Setting is Disable.

      Parameter NameEnter the parameter name in which FortiWeb can find the API key when API Key Carried in is HTTP Parameter.

      Available only when API Key Verification is Enable and Inherit API Key Setting is Disable.
      Header Field NameEnter the header filed name in which FortiWeb can find the API key when API Key Carried in is HTTP Header.

      Available only when API Key Verification is Enable and Inherit API Key Setting is Disable.
      Allow User GroupSelect a user group created in API User > API User Group to define which users can make the requests.

      Available only when API Key Verification is Enable.

      Per-user Rate Limit

      Limit API requests by users. Type the maximum number of API call requests allowed per user in a certain number of seconds.

      Rate LimitType the maximum number of API call requests allowed in a certain number of seconds.

      X-RateLimit-*Headers

      Enable to add X-RateLimit-* headers in the response packet if the user exceeds the rate limit. The following information can be displayed to users: the request limit, the remaining requests, and the minimum time to wait before the user is allowed to send the next request.

    • Click OK.
      Note: When API request matches both the frontend prefix and sub-URL, the settings in Sub-URL Settings will dominate those in Request Settings.
  • For Action, FortiWeb will take the specified action when any violation is detected in the API call; for example, an API key verification fails or a request occurrence exceeds the rate limit.
    • Configure these settings.
      Action

      Select which action FortiWeb will take when it detects a violation of the policy:

      • Alert—Accept the connection and generate an alert email and/or log message.

      • Alert & Deny—Block the request (or reset the connection) and generate an alert and/or log message.

      • Deny (no log)—Block the request (or reset the connection).

      • Period Block—Block subsequent requests from the client for a number of seconds. Also configure Block Period.

      The default value is Alert.

      Block PeriodEnter the number of seconds that you want to block subsequent requests from a client after FortiWeb detects that the client has violated the policy. The valid range is 1–10,000 seconds.

      This setting is available only if Action is set to Period Block.
      Severity

      When policy violations are recorded in the attack log, each log message contains a Severity Level (severity_level) field. Select which severity level FortiWeb will use when it logs a violation of the policy:

      • Informative
      • Low
      • Medium
      • High

      The default value is Low.

      Trigger PolicySelect the trigger, if any, that FortiWeb will use when it logs and/or sends an alert email about a violation of the policy. For details, see Viewing log messages.
    • Click OK.
      To apply the rule in API gateway policy, see Configuring API gateway policy.

    Configuring API gateway rules

    Configuring API gateway rules

    To restrict API access, you can configure certain rules involving API key verification, API key carryover, API user grouping, sub-URL setting, and specified actions FortiWeb will take in case of any API call violation.

    To create an API gateway rule

    1. Go to API Gateway > API Gateway Policy, and select the API Gateway Rule tab.
    2. Click Create New.
    3. Configure these settings:
      NameType a unique name that can be referenced in other parts of the configuration.
      Host StatusEnable to apply this rule only to HTTP requests for specific web hosts. Also configure Host.
      HostSelect the name of a protected host that the Host: field of an HTTP request must be in to match the API gateway rule.
      This option is available only if Host Status is enabled.
    4. Click OK.
    5. For Match URL Prefixes, configure the URL prefixes to be routed to the backend.
    • Click Create New.
    • Enter the Frontend Prefix; the frontend prefix is the URL path in a client call, for example, /fortiweb/, the URL is like this HTTPS://172.22.14.244/fortiweb/example.json?param=value.
    • Enter the Backend Prefix; the backend prefix is the path which the client request will be replaced with, for example, /api/v1.0/System/Status/.
      After the URL rewriting, the URL is like this HTTPS://10.200.3.183:90/api/v1.0/System/Status/example.json?param=value.
    • Click OK.
      You can enter multiple URL prefixes, which means multiple URL paths may math the API gateway rule.
  • For Request Settings, configure these settings:
    Attach HTTP HeaderInsert specific header lines into HTTP header.
    API Key VerificationWhen an user makes an API request, the API key will be included in HTTP header or parameter, FortiWeb obtains the API key from the request. When this option is enabled, FortiWeb verifies the key to check whether the key belongs to an valid API user.
    API Key Carried in

    Indicate where FortiWeb can find your API key in HTTP request:

    • HTTP Parameter

    • HTTP Header

    Available only when API Key Verification is Enable.

    Parameter NameEnter the parameter name in which FortiWeb can find the API key when API Key Carried in is HTTP Parameter.

    Available only when API Key Verification is Enable.
    Header Field NameEnter the header filed name in which FortiWeb can find the API key when API Key Carried in is HTTP Header.

    Available only when API Key Verification is Enable.
    Allow User GroupSelect a user group created in API User > API User Group to define which users have the persmission to access the API.

    Available only when API Key Verification is Enable.

    Per-user Rate Limit

    Limit API requests by users. Type the maximum number of API call requests allowed per user in a certain number of seconds.

    Rate LimitType the maximum number of API call requests allowed in a certain number of seconds.
  • For Sub-URL Settings, when the user's call matches the frontend prefix, you can also define a set of sub-URL rules to further define the subpaths.
    • Click Create New.
    • Configure these settings:
      HTTP MethodSelect the HTTP method from the drop down list.
      Type

      Select whether the URL Expression field must contain either:

      • Simple String—The field is a string that the request URL must exactly.

      • Regular Expression—The field is a regular expression that defines a set of matching URLs.

      URL Expression

      Depending on your selection in Type, enter either:

      • The literal URL, such as /folder1/index.htm that the HTTP request must contain in order to match the rule, or use wildcards to match multiple URLs, such as /folder1/* or /folder1/*/index.htm. The URL must begin with a slash ( / ).

      • A regular expression, such as ^/*.php, matching all and only the URLs to which the input rule should apply. The pattern does not require a slash ( / ).; however, it must at least match URLs that begin with a slash, such as /index.cfm.

        When you have finished typing the regular expression, click the >> (test) icon.
        This opens the Regular Expression Validator window where you can finetune the expression. For details, see Appendix E: Regular expressions

      API Key VerificationWhen an user makes an API request, the API key will be included in HTTP header or parameter, FortiWeb obtains the API key from the request. When this option is enabled, FortiWeb verifies the key to check whether the key belongs to an valid API user.
      Inherit API Key SettingWhen this option is enabled, you don't need to specify where the API key is carried. Instead, the Sub-URL settings will follow that in Request Settings.

      Available only when API Key Verification is Enable.
      API Key Carried in

      Indicate where FortiWeb can find your API key in HTTP request:

      • HTTP Parameter

      • HTTP Header

      Available only when API Key Verification is Enable and Inherit API Key Setting is Disable.

      Parameter NameEnter the parameter name in which FortiWeb can find the API key when API Key Carried in is HTTP Parameter.

      Available only when API Key Verification is Enable and Inherit API Key Setting is Disable.
      Header Field NameEnter the header filed name in which FortiWeb can find the API key when API Key Carried in is HTTP Header.

      Available only when API Key Verification is Enable and Inherit API Key Setting is Disable.
      Allow User GroupSelect a user group created in API User > API User Group to define which users can make the requests.

      Available only when API Key Verification is Enable.

      Per-user Rate Limit

      Limit API requests by users. Type the maximum number of API call requests allowed per user in a certain number of seconds.

      Rate LimitType the maximum number of API call requests allowed in a certain number of seconds.

      X-RateLimit-*Headers

      Enable to add X-RateLimit-* headers in the response packet if the user exceeds the rate limit. The following information can be displayed to users: the request limit, the remaining requests, and the minimum time to wait before the user is allowed to send the next request.

    • Click OK.
      Note: When API request matches both the frontend prefix and sub-URL, the settings in Sub-URL Settings will dominate those in Request Settings.
  • For Action, FortiWeb will take the specified action when any violation is detected in the API call; for example, an API key verification fails or a request occurrence exceeds the rate limit.
    • Configure these settings.
      Action

      Select which action FortiWeb will take when it detects a violation of the policy:

      • Alert—Accept the connection and generate an alert email and/or log message.

      • Alert & Deny—Block the request (or reset the connection) and generate an alert and/or log message.

      • Deny (no log)—Block the request (or reset the connection).

      • Period Block—Block subsequent requests from the client for a number of seconds. Also configure Block Period.

      The default value is Alert.

      Block PeriodEnter the number of seconds that you want to block subsequent requests from a client after FortiWeb detects that the client has violated the policy. The valid range is 1–10,000 seconds.

      This setting is available only if Action is set to Period Block.
      Severity

      When policy violations are recorded in the attack log, each log message contains a Severity Level (severity_level) field. Select which severity level FortiWeb will use when it logs a violation of the policy:

      • Informative
      • Low
      • Medium
      • High

      The default value is Low.

      Trigger PolicySelect the trigger, if any, that FortiWeb will use when it logs and/or sends an alert email about a violation of the policy. For details, see Viewing log messages.
    • Click OK.
      To apply the rule in API gateway policy, see Configuring API gateway policy.