HTTP Gateway

Introduction

The HTTP Gateway builds an HTTP entry point into your Resolve Actions Pro deployment. Depending on which RSRemote instance you deploy the gateway, you can control in which network this entry point appears.

Enabling the HTTP Gateway

The initial configuration of the HTTP Gateway is done in the blueprint.properties file. There, you need to enable the gateway (rsremote.receive.http.active = true) and, optionally, set other properties such as enabling SSL (rsremote.receive.http.ssl) and the SSL certificate location (rsremote.receive.http.sslcertificate).

You can find details about reconfiguring blueprint.properties in Modifying the Blueprint and Re-configuring RSRemote. For the full list of HTTP Gateway properties, see Blueprint Configuration.

Alternatively, you can set up the same properties through the UI, as follows:

1. Navigate to Remote Administration > Gateway Administration.
2. Select HTTP.
3. Click Actions > Gateway Configuration.
4. In the Gateway Configuration screen, click Edit.
5. Make your changes and finally click Save Changes.

After doing the initial configuration, you can continue setting up filters and authentication methods in the Actions Pro Web UI.

Setting Up HTTP Authentication

Setting up authentication is the first step before creating gateway filters.

Authentication is optional for the HTTP Gateway. You can set up unauthenticated endpoints or endpoints that require authentication, all at the same time. For example, you could use an unauthenticated endpoint for running an Automation that only shows status information while requiring authentication for Automations that make changes to actual systems.

The HTTP Gateway supports basic, OAuth, or no authentication. You need to create an HTTP Authentication record even if you don't require authentication, as this is how you specify what network port to use.

Authentication is bound to a port number. After you configure the type of authentication for a port number, you can bind that port number to a gateway filter, which specifies the endpoint path and the Automation to run.

Setting Up Unauthenticated Access

You need to create an HTTP Authentication record even if you don't require authentication, as this is how you specify what network port to use.

Take these steps to define a network port that will accept unauthenticated HTTP requests:

1. Navigate to Remote Administration > Gateway Filter Administration.
2. In Gateway Type at the top, select HTTP.
   Settings specific to the HTTP Gateway appear, divided into two tabs: Filters and HTTP Gateway.
3. Click the HTTP Gateway tab.
4. Click Create New.
5. In Port, enter the port number that you want to use with the HTTP Gateway.
   The number must be in the 1-65535 range.
6. Click SSL if you want to require an HTTPS connection for requests to this HTTP port.
   note

   This setting requires enabling SSL in the blueprint.properties file, inclufing setting up an SSL certificate. See Enabling the HTTP Gateway.

7. In Auth Type, select None.
8. Optionally, click Advances Configuration and then make the following settings:
   • In Exclude Ciphers, enter a list of outdated SSL encryption algorithms to ban from using.
     The list can be a comma-separated list or a regular expression.
     Only applies to HTTPS connections.
     Examples:

     DES,3DES,IDEA
     ^(.(DES|3DES|IDEA).|.*_(MD5|SHA|SHA1))$
9. Click Save.
10. Deploy the HTTP Authentication to the RSRemote:
    1. Select the entry that you just created.
    2. At the top, click Deploy and then select the replace/append policy to apply.

Setting Up Basic Authentication

For less demanding applications that still require a certain level of security, you can protect your HTTP endpoint with basic authentication.

Take these steps to define a network port that will accept HTTP requests secured with basic authentication:

1. Navigate to Remote Administration > Gateway Filter Administration.
2. In Gateway Type at the top, select HTTP.
   Settings specific to the HTTP Gateway appear, divided into two tabs: Filters and HTTP Gateway.
3. Click the HTTP Gateway tab.
4. Click Create New.
5. In Port, enter the port number that you want to use with the HTTP Gateway.
   The number must be in the 1-65535 range.
6. Click SSL if you want to require an HTTPS connection for requests to this HTTP port.
   note

   This setting requires enabling SSL in the blueprint.properties file, inclufing setting up an SSL certificate. See Enabling the HTTP Gateway.

7. In Auth Type, select Basic Auth.
8. Optionally, click Advances Configuration and then make the following settings:
   • In Exclude Ciphers, enter a list of outdated SSL encryption algorithms to ban from using.
     The list can be a comma-separated list or a regular expression.
     Only applies to HTTPS connections.
     Examples:

     DES,3DES,IDEA
     ^(.(DES|3DES|IDEA).|.*_(MD5|SHA|SHA1))$
   • In Basic Auth Username, enter the username that will have to be included with each HTTP request.
   • In Basic Auth Password, enter the password that will have to be included with each HTTP request.
9. Click Save.
10. Deploy the HTTP Authentication to the RSRemote:
    1. Select the entry that you just created.
    2. At the top, click Deploy and then select the replace/append policy to apply.

Setting Up OAuth Authentication

OAuth allows you to authenticate requests to Actions Pro using a short-lived Access token instead of permanent credentials. In HTTP Gateway terms, Actions Pro plays the role of both the Identity Provider (IdP) and the Service Provider (SP).

Take these steps to define a network port that will accept HTTP requests secured with an OAuth Access token:

1. Navigate to Remote Administration > Gateway Filter Administration.
2. In Gateway Type at the top, select HTTP.
   Settings specific to the HTTP Gateway appear, divided into two tabs: Filters and HTTP Gateway.
3. Click the HTTP Gateway tab.
4. Click Create New.
5. In Port, enter the port number that you want to use with the HTTP Gateway.
   The number must be in the 1-65535 range.
6. Click SSL if you want to require an HTTPS connection for requests to this HTTP port.
   note

   This setting requires enabling SSL in the blueprint.properties file, inclufing setting up an SSL certificate. See Enabling the HTTP Gateway.

7. In Auth Type, select OAuth.
8. Optionally, click Advances Configuration and then make the following settings:
   • In Exclude Ciphers, enter a list of outdated SSL encryption algorithms to ban from using.
     The list can be a comma-separated list or a regular expression.
     Only applies to HTTPS connections.
     Examples:

     DES,3DES,IDEA
     ^(.(DES|3DES|IDEA).|.*_(MD5|SHA|SHA1))$
   • In Access Token Timeout, change the expiration period of the OAuth Access token.
     The value must be between 15 and 60 minutes.
   • In Refresh Token Timeout, change the expiration period of the OAuth Refresh token.
     The value must be between 1 and 90 days.
9. Provide OAuth Client ID and Client Secret:
   • To generate random values, click Create New Credentials.
   • To provide your own values, enter them in the provided text fields.
     caution

     Don't forget to provide the OAuth Client ID and Client Secret values to the authenticating party before completing the configuration. For security reasons, these values will be hidden as soon as you click Save. If you lose the values, you will have to regenerate them.

10. Click Save.
11. Deploy the HTTP Authentication to the RSRemote:
    1. Select the entry that you just created.
    2. At the top, click Deploy and then select the replace/append policy to apply and the RSRemote queue to deploy to.

Setting Up Gateway Filters for HTTP Gateway

After setting up HTTPS authentication, you can define filters for the HTTP Gateway. A filter is a combination of a URL path to call, preprocessing script, Automation to run, and other settings relating to the endpoint.

Take these steps to create a new HTTP endpoint:

1. Navigate to Remote Administration > Gateway Filter Administration.
2. In Gateway Type at the top, select HTTP.
   Settings specific to the HTTP Gateway appear, divided into two tabs: Filters and HTTP Gateway.
3. Click the Filters tab.
4. Click Create New.
5. In Name, provide a name for the filter.
6. In Runbook, select a default Automation to run when a request is made to the endpoint.
   Before running the default Automation, the filter checks for the following conditions, in the specified order, and executes their Automations instead if the condition is met:
   • Does the filter script invoke an Automation?
   • Does a Resolution Routing rule match the event data?
7. In Interval, specify the server polling interval in seconds.
   The default value is what you set for rsremote.receive.http.interval in blueprint.properties.
8. In Order, specify the relative execution order of the filter in case multiple filters were scheduled for execution at the same time.
   Lower numbers have higher priority.
9. In Resolve Event ID, enter a Resolve Event ID value to sent to a possible Automation waiting for events when the filter is processed.
   The value can be any string.
10. On the Parameters tab, set the fields as follows:
    • URI—Enter the endpoint URL path, including a forward slash but excluding the base path.
      Example: /statistics
    • Port—Select one of the ports that you configured in Setting Up HTTP Authentication. If you leave the field blank, the default port from blueprint.properties (rsremote.receive.http.port) is used, together with the SSL setting from the same file.
    • Block Call—Select the request's blocking level:
      • Default (non-blocking)—The filter immediately returns a "200 OK" response.
      • Gateway Script (blocking level 1)—Returns after the filter script completes. You can set the response code and message using the filter script.
      • Worksheet ID (blocking level 2)—The filter waits for the specified Automation to start executing and returns the worksheet ID. You can set the response code and message using the filter script.
      • Execution Complete (blocking level 3)—The filter waits for the specified Automation to complete before returning a response. The response contains the worksheet ID, the execution condition, and the severity.
      • Filtered Response (blocking level 3 + response formatting)—Same as Execution Complete, but instead of a fixed response, it returns RESULT.detail from an ActionTask named httpfilter_response that you need to include in the executed Automation with the exact same name. You can customize the response using the ActionTask's code and finally setting it to the assessor's RESULT structure's detail variable.
    • Content Type—The content type of the response body.
11. On the Filter Script tab, enter an optional preprocessing script.
    Using the script's code, you can process the request data (URL or request body parameters) before it is sent to RSControl.
12. At the top of the screen, toggle Active on or off depending on whether you want to activate the filter right away or not.
    note

    You still need to deploy the filter to use it.

13. At the top, click Save.
14. Go back to the Gateway Filter Administration screen.
15. Deploy the filter to the RSRemote:
    1. Select the filter that you just created.
    2. At the top, click Deploy and then select the replace/append policy to apply and the RSRemote queue to deploy to.