Configuration

Module Configuration

By selecting REST API Server in the explorer tree menu, users can configure how the module will accept connections. The following screenshot shows the different available options for REST API Server Configuration:

Parameters:

Mode: Specifies what protocols will be accepted by the REST API Server. Available options are “HTTP”, “HTTPS” and “Both (HTTP & HTTPS)”.

HTTP:

• TCP port: specifies the HTTP port number for connecting to the REST API Server. The default port number is 3003. The valid range is 1 to 65535. This port may not be used by any other application on the same machine.
• Network interface: Specifies the interface for accessing the REST API Server via HTTP. You can either select the network interface by clicking the browse button or enter the IP address manually.

  
  

HTTPS:

• TCP port: Specifies the HTTPS port number for connecting to the REST API Server. The default port number is 3443. The valid range is 1 to 65535. This port may not be used by any other application on the same machine.
• Network interface: Specifies the interface for accessing the REST API Server via HTTPS. You can either select the network interface by clicking the browse button or enter the IP address manually
• Certificate helper: Facilitates establishing HTTPS connections with custom self-signed certificates, offering control over the certificate generation process.
  Note:

  This feature is available from N3uron version 1.21.9.
  
  

  

  To open the self-signed Certificate helper, right-click on the icon next to the HTTPS title section, and then fill out the form.

  • Common Name: The fully qualified domain name (FQDN) for which the certificate is being requested. This is typically the domain name of the server where the certificate will be installed (e.g., www.example.com).
  • Organization Name: The legal name of the organization or company that is requesting the certificate.
  • Organization Department: The specific department or division within the organization that is requesting the certificate.
  • Email: The email address associated with the organization or individual requesting the certificate.
  • Country: The two-letter ISO code representing the country where the organization is located (e.g., US for United States, CA for Canada, ES for Spain).
  • State: The full name or abbreviation of the state or province where the organization is located.
  • Locality: The city or locality where the organization is located.
  • Street: The street address of the organization's physical location.
  • Postal Code: The postal or ZIP code of the organization's location.
  • Key Size: The size of the cryptographic key pair to be generated for the certificate, measured in bits. Common key sizes include 2048 bits or 4096 bits.
  • Expiration Days: The number of days until the certificate expires. This determines the validity period of the certificate before it needs to be renewed.

When filling out the form to generate the CSR, ensure that all information provided is accurate and matches the organization's official details. This information will be embedded in the CSR and subsequently used to issue the SSL/TLS certificate.

• Certificate type: Specifies the server HTTPS certificate. The following options are available:
  • Self-signed: The server willautomatically create and sign a certificate using an internal certification authority, which can be downloaded by clicking on the ellipsis button on the right side of the Self-signed certificate field.  
    Note    

    Starting from N3uron version 1.21.9, the generation of self-signed certificates has been relocated to the Certificate helper.
    This certification authority is valid for all the REST API Server instances and must be imported into each system/web client that will access the REST API Server via HTTPS. When selecting the “Self-signed” option, the following section will appear:
  • Self-signed certificate parameters:
    • Certified hosts: Comma-separated host list (domains/host names and/or IPs) that will be included in the auto-generated SSL certificate. It is important to include all the hosts where the REST API Server will be accessed so the web client does not show any errors. Hosts 127.0.0.1, localhost and system hostname will be automatically added to the certificate.
      
      Note    

      Starting from N3uron version 1.21.9, specifying certified hosts is no longer necessary.

• • Embedded: The provided certificates will be embedded in the configuration file. When selecting the “Embedded” option, the following section will appear:
    Note:

    This feature is available from N3uron version 1.21.7.
    The key for the embedded certificate file will be secure and cannot be downloaded.
    • Custom certificate parameters:
      • Key: Certificate key in PEM format.
      • Key passphrase: Optional. Certificate key passphrase.
      • CA bundle/chain: Optional. CA bundle in PEM format.
      • Certificate: Certificate in PEM format.
  • File path: File path where the certificate files are located, with a hot-reload option. The path is relative to the data/<instance name>/cert/ folder. When selecting the “File path” option, the following section will appear:
    • File path certificate parameters:
      • Key path: Certificate key in PEM format. The path is relative to the data/<instance name>/cert/ folder.
      • CA bundle/chain: Optional. Certificate CA bundle in PEM format. The path is relative to the data/<instance name>/cert/ folder. The file will not be reloaded, so it is necessary to restart the module if the file is modified while the module is running.
      • Certificate path: Certificate in PEM format. The path is relative to the data/<instance name>/cert/ folder.
      • Reload interval: Expressed in seconds, specifies the interval to reload certificates if file changes were detected. Set to 0 to disable.

Access Configuration

The REST API Server uses authorization to ensure secure data access. This includes authenticating the sender and verifying their permission to access or manipulate data.

Currently, two types of authorization are supported: Role authentication, which involves sending a verified username and password, and Token authentication, which uses an API key.

Role Authentication 

Selecting this option, permissions will be assigned to the Roles previously created in the Roles section.

Parameters:

• Enabled: Specifies whether or not any authentication attempt will be blocked. 
• API Access: N3uron REST API calls use the GET and POST methods and can be categorized into the following groups:
  • Alarm: Access to tag alarms namespace.
  • Backup: Access to the node backup system.
  • Certificate: Access to the node certificate system.
  • License: Access to the node licensing system.
  • Link: Access node link system.
  • Module: Access modules system.
  • System: Access node system namespace.
  • Tag: Access tag namespace.
• Tag access: 
  • Tag Filter: Define and configure the filter for tags to be included in the message.
    Note:

    It is mandatory to add a filter even when the whole model is going to be published.
    • Mode: Specifies whether the filter must include or exclude tags. 
      Note:

      Include filters are applied first and exclude filters are applied to the include filters' results.
    • Path: Specifies the path of the tag or group of tags to be filtered. 
    • Regex Pattern: This is a regular expression for filtering which tags will be included. By default, it is set to .*, meaning no filter is applied. Readers can find further information about regular expressions at RegExr.

Token Authentication

This option enables requests to authenticate using an access key. The token is a text string, included either in the request header or passed as a parameter.

Parameters:

• Enabled: Specifies whether or not any authentication attempt will be blocked. 
• Token: API key value autogenerated by clicking on the button on the right side. Authentication can be made using two methods: GET parameter and HTTP header.
  • An example, being the token 123ABC:
    • GET parameter: Adding the bearer token in a token URL parameter. Example: https://<address>:<port>/module?cmd=details&token=123ABC.
    • HTTP header: Adding the bearer token to the HTTP Authorization header. Example: Authorization: Bearer 123ABC.
• API Access: N3uron REST API calls use the GET and POST methods and can be categorized into the following groups:
  • Alarm: Access to tag alarms namespace.
  • Backup: Access to the node backup system.
  • Certificate: Access to the node certificate system.
  • License: Access to the node licensing system.
  • Link: Access node link system.
  • Module: Access modules system.
  • System: Access node system namespace.
  • Tag: Access tag namespace.
• Tag access: 
  • Tag Filter: Define and configure the filter for tags to be included in the message.
    Note:

    It is a mandatory to add a filter even when the whole model is going to be published.
    • Mode: Specifies whether the filter must include or exclude tags. 
      Note:

      Include filters are applied first and exclude filters are applied to the include filters' results.
    • Path: Specifies the path of the tag or group of tags to be filtered. 
    • Regex Pattern: This is a regular expression for filtering which tags will be included. By default, it is set to .*, meaning no filter is applied. Readers can find further information about regular expressions at RegExr.

REST API Server Full Product Details