Security Rules

Security Rules

 

Introduction

Security rules enable you to define the invocation and access rules of your Catalyst Basic I/O and Advanced I/O functions. The Security Rules feature is essentially a JSON file that allows you to configure the following properties of a function:

  • The HTTP methods that can be used to access the function
  • Whether authentication is required or optional to access the function
Note:
  • Security rules do not define configurations for Cron and Event functions as they cannot be directly executed by end users.
  • The configuration parameters in security rules are the same for both Java and Node.js functions.

Security Rules is a basic API management tool that is considered to be the default security configuration of a function. When you create a Basic I/O or an Advanced I/O function in the Catalyst console or deploy a function from the CLI to the remote console, the security rules definitions are created for it automatically in the console. Catalyst populates default values for the security rules definitions of the function. You can later modify them according to your requirements.

For advanced API management, you can disable Security Rules and enable API Gateway for your function and web client end points. API Gateway is an enhancement to Security Rules that acts as a single entryway to access Catalyst functions and web clients.

Points to remember:

  • When you enable API Gateway for your Catalyst application, Security Rules will be disabled automatically.
  • You can migrate Security Rules definitions of your functions to API Gateway.
  • When API Gateway is disabled, the configurations defined for a function in Security Rules will be followed by default.
 

Key Concepts

Before you configure definitions in Security Rules, understand its fundamental concepts in detail.

Configurations Available in Security Rules

Security rules enable you to configure HTTP access and authentication for each Basic I/O and Advanced I/O function in your project, by defining values for each of those parameters in the JSON file.

The following values can be set for each parameter definition for a function:

Available ParametersAllowed Values
methodsGET, POST, DELETE, PUT, PATCH
authenticationoptional, required

Methods

The methods parameter enables you to define the HTTP methods that can be used to access a function. Catalyst provides support for GET, POST, DELETE, PUT, and PATCH methods by default.

When you remove a method from the JSON file for a particular function, the end user will not be able to trigger the function with that HTTP method. For example, if you remove the POST method, the user will not be able to pass any input values in the function call using that method, and if you remove the GET method for a function, the user will not be able to call the function URL.

You can therefore customize the HTTP methods that can be allowed to call a function and remove unrequired methods for better security.

Authentication

The authentication parameter allows you to enable or disable authentication to access a function. It defines whether a user needs to authenticate their identity to call a particular function. The authentication parameter is set to optional for all your functions by default when you create them.

When this parameter is set to optional for a function, any user will be able to access the function's URL without undergoing an authentication check. The function URL will therefore be globally accessible to everyone and all function calls will be allowed with no restrictions from Catalyst.

To restrict access to the function to only authenticated users and increase security, you can set the parameter to required. This informs Catalyst to perform an authentication check on the user when they call the function.

Security Rules supports two types of authentication methods:

  • Catalyst Users Authentication:

    This authentication method enables access for all users of your Catalyst application added in Catalyst Authentication, by default. You can handle this authentication method by incorporating a user sign-in form in your Catalyst application, and enabling a login session. The app users will then be able to call the function automatically without needing to go through any additional user verification.

  • OAuth-Based Authentication:

    This authentication method enables access for the users with an OAuth access token. You can pass the access token as a header in the function call request as shown in this example:

    curl -X POST \
    			https://shipmenttracking-61317105.zohocatalyst.com/CustomerPortal/create \
    			-H "Authorization: Zoho-oauthtoken 1000.910***************************16.2f****************************57"
     

    To implement OAuth authentication in your Catalyst application, refer to our OAuth Authentication help documentation for detailed steps.

 

Configuring Security Rules for Basic I/O and Advanced I/O Functions

The security rules definitions for a Basic I/O function are configured with the following default values when the function is created:

"functions": {
        "LogDelivery": {
            "methods": [
                "GET",
                "POST",
                "DELETE",
                "PUT",
                "PATCH"
            ],
            "authentication": "optional"
        }
    }
 

The security rules definitions for an Advanced I/O function are configured with the following default values when the function is created:

"advancedio": {
        "CustomerPortal": [
            {
                ".*": {
                    "methods": [
                        "GET",
                        "POST",
                        "DELETE",
                        "PUT",
                        "PATCH"
                    ],
                    "authentication": "optional"
                }
            }
        ]
    }
 

By default, the wildcard pattern .* is used by Catalyst to define the configurations of an Advanced I/O function, indicating that these definitions apply to all the routes created in the Advanced I/O function.

You can configure different definitions for each route defined in an Advanced I/O function individually. For example, if you have defined two routes called /vendor and /customer in the function, you can enable or disable specific methods and the authentication for each route independently like:

"advancedio": {
        "CustomerPortal": [
            {
                "/vendor": {
                    "methods": [
                        "GET",
                        "POST",
                        "PUT"
                    ],
                    "authentication": "required"
                },
                "/customer": {
                    "methods": [
                        "GET",
                        "POST",
                        "DELETE",
                        "PUT",
                        "PATCH"
                    ],
                    "authentication": "optional"
                }
            }
        ]
    }
 

Advantages of API Gateway over Security Rules

While the Security Rules feature defines the configurations for basic routing and authentication functionalities for your functions, API Gateway enables you to create individual APIs, provides more flexibility in customizing routing and authentication, and provides additional functionalities.

Some advantages of API Gateway over Security Rules include:

  • In addition to the HTTP methods supported by Security Rules, you can aggregate all HTTP methods under a single method called ANY, and create a single API for it in API Gateway.
  • You can configure a custom request URL and target URL and create individual APIs for each request method for every URL.
  • In addition to Catalyst Users Authentication and OAuth Authentication, API Gateway also supports authentication using API Keys.
  • You can configure throttling for each individual API.
  • You can also create APIs for web clients and configure their definitions.
 

Implementation

You can access and customize security rules definitions for each function from the Catalyst console. As mentioned earlier, the security rules definitions are created for a function automatically when it is created. Similarly, if you delete a function, Catalyst will delete its security rules definitions automatically.

Modify Definitions in Security Rules

To modify security rules definitions for a Basic I/O or Advanced I/O function in Catalyst:

  1. Navigate to Security Rules under Compute from the Catalyst console.
  2. Modify the definitions as required.
  3. Click Save.

The modified definitions will be applied for the function.

You must follow these guidelines while configuring definitions in Security Rules:

  • You must follow the syntax of a JSON file format while configuring security rules.
  • If you delete the methods or authentication parameters from the file, the default configurations will be automatically enabled for your function.
  • You will not be able to provide any values for a parameter which are not the supported values.

The console will display an error if you violate any of these guidelines.

The editor window enables auto-completion of your code, and also provides tools that enrich your coding experience. Right-click on the editor window to open the tools.

Share this post : FacebookTwitter

Still can't find what you're looking for?

Write to us: support@zohocatalyst.com