1. Using Oracle API Platform Cloud Service
  2. Manage Gateways
  3. Configure Gateway Node Domains

Configure Gateway Node Domains

Configure the domains for each of your gateway nodes, including configuring authentication providers, SSL certificates for passing requests to HTTPS endpoints, and locking down your nodes.

Topics

Sign into the WebLogic Adminstration Console for a Gateway Node Domain

Sign in to the WebLogic Server Administration Console for your gateway node domain to configure the WebLogic Server authentication providers.
To sign into the WebLogic Administration Console:
  1. Open a browser window and navigate to: http://<hostname>:<port>/console
    Where <hostname> is the DNS name or IP address of the Administration Server and <port> is the address of the port on which the gateway node Administration Server is listening for requests (8001 by default). If your browser is configured to send HTTP requests to a proxy server, you may need to configure your browser so that it does not send Administration Server HTTP requests to the proxy. If the Administration Server is running on the same machine as your Web browser, configure your browser so that requests sent to localhost or IP address 127.0.0.1 are not sent to the proxy server.
  2. When the login page appears, enter the user name and the password you used to start the Administration Server (you may have specified this user name and password during the installation process), or enter a user name that is granted one of the default global security roles.

Supported WebLogic Authentication Providers

Oracle API Platform Cloud Service supports WebLogic authentication providers in the gateway node domain for authenticating users in identity management systems.

Name Description

WebLogic Authentication provider

Accesses user and group information in WebLogic Server's embedded LDAP server.

Oracle Internet Directory Authentication provider

Accesses users and groups in Oracle Internet Directory, an LDAP version 3 directory.

Oracle Virtual Directory Authentication provider

Accesses users and groups in Oracle Virtual Directory, an LDAP version 3 enabled service.

LDAP Authentication providers

Access external LDAP stores. You can use an LDAP Authentication provider to access any LDAP server. WebLogic Server provides LDAP Authentication providers already configured for Open LDAP, Sun iPlanet, Microsoft Active Directory, and Novell NDS LDAP servers.

RDBMS Authentication providers

Access external relational databases. WebLogic Server provides three RDBMS Authentication providers: SQL Authenticator, Read-only SQL Authenticator, and Custom RDBMS Authenticator.

WebLogic Identity Assertion provider

Validates X.509 and IIOP-CSIv2 tokens and optionally can use a user name mapper to map that token to a user in a WebLogic Server security realm.

SAML Authentication provider

Authenticates users based on Security Assertion Markup Language 1.1 (SAML) assertions

Negotiate Identity Assertion provider

Uses Simple and Protected Negotiate (SPNEGO) tokens to obtain Kerberos tokens, validates the Kerberos tokens, and maps Kerberos tokens to WebLogic users

SAML Identity Assertion provider

Acts as a consumer of SAML security assertions. This enables WebLogic Server to act as a SAML destination site and supports using SAML for single sign-on.

See also About Configuring the Authentication Providers in WebLogic Server in Administering Security for Oracle WebLogic Server.

Configure WebLogic Authentication Providers

You must configure an authentication provider for your identity management system for gateway nodes to authenticate which users can send requests to APIs secured with Basic Auth and OAuth 2 policies.
You perform many of these actions in the WebLogic Server Administration Console of your gateway node domain.
To configure WebLogic authentication providers:
  1. Access the Weblogic Administration Console in your browser by navigating to http://<hostname>:<port>/console where <hostname> is the DNS name or IP address of the Administration Server and <port> is the address of the port on which the gateway node Administration Server is listening for requests (8001 by default).
  2. See to the relevant topic in Administering Security for Oracle WebLogic Server for the authentication provider you want to configure for your identity domain:
  3. (Optional) Complete these steps only if you are replacing the embedded LDAP with the identity provider you are configuring:
    1. Map the appropriate Admin role in your identity provider to the WebLogic Administrators role, available in the WebLogic XACML role mapping provider.
    2. In the boot.properties file, replace the encrypted username and password in the file with the username and password (in plain text) of the new admin user.
      The server encrypts these values when the server starts.
    3. Remove the default authenticator. See Delete security providers in Oracle WebLogic Server Administration Console Online Help.
  4. Restart the gateway WebLogic Server domain. See Starting and Stopping Servers in Administering Server Startup and Shutdown for Oracle WebLogic Server 12.1.3.

Configure SSL Certificates to Pass Requests to Services Over HTTPS

To pass requests to backend service endpoints using the HTTPS protocol, you must first import the required SSL certificates into the WebLogic trust stores for your gateway node domains.

  1. Navigate to the following directory on the machine from which your gateway node is running:
    ${GW_INSTALL_DIR}/GATEWAY_HOME/wlserver/server/lib

    Where ${GW_INSTALL_DIR} is the directory where you installed the gateway node.

  2. To import the external CA into the WebLogic trust store, execute the following command:
    keytool -import -alias myCa1 -trustcacerts -file ${CA_FILE_NAME} -keystore <trust keystore> -storepass <trust keystores Passphrase> DemoTrustKeyStorePassPhrase

    Where myCa1 is the keystore alias, ${CA_FILE_NAME} is the CA file you want to import, <trust keystore> is the name of the keystore, and <trust keystores Passphrase> is the keystore’s passphrase.

    The command depends on the Keystore type that you selected WebLogic console at servers, managedServer1, Configuration, Keystores. Change the command depending on the CA certificate that you inserted for the gateway. Keystores page provides you 4 choice:

    • Custom Identity and Command Line Trust (not supported)

    • Custom Identity and Custom Trust

    • Custom Identity and Java Standard Trust

    • Demo Identity and Demo Trust (default option)

    <trust keystore> value is found at Keystores page.

  3. Repeat this procedure for each gateway node that needs to pass requests to the same back-end service endpoints over HTTPS.

Configure the Socket Timeout When Calling Backend Services

If there is no Close token or Keep-alive token in the connection header in the response from the backend server, the keep-alive is enabled automatically. You can set a duration that the connection can remain idle.

To set a duration for which a connection can remain idle:
  1. Log in to the Weblogic Console.
  2. Click OSCG.
  3. Click the name of your NT server.
  4. Click Container Services.
  5. Click DafGeneralInformation.
  6. Click SocketTimeoutMs.
  7. Enter the desired timeout.

Gateway Node Lockdown

A Gateway Node exposes REST endpoints for the APIs deployed on it. Apart from the deployed APIs, the nodes have internal REST endpoints which need to be secured. Lockdown will restrict access to the internal endpoints to just the local servers in the domain.

Topics

Endpoints on a Gateway Node

Learn about the endpoints exposed by gateway nodes.

Gateway nodes expose the following types of REST endpoints:

  • Gateway controller endpoints

  • Internal endpoints

  • Weblogic Administration Console endpoint

  • Deployed API Endpoints

Gateway controller endpoints function as management control for the gateway node, allowing the user to control the nature of polling and state of the node. The endpoints on the gateway node use the /apiplatform context root and are deployed on the managed servers. See REST API for the Gateway Controller in Oracle API Platform Cloud Service.

The gateway node exposes internal REST endpoints for the gateway controller to invoke to be able to deploy APIs and applications. These internal endpoints uses the /prm_pm_rest context root and are deployed on the node domain’s managed servers.

The Weblogic Administration Console endpoint is deployed on the Administration Server of the gateway node domain. This endpoint uses /console context root only on the Administration Server.

All deployed Oracle API Platform Cloud Service APIs will have endpoints on the managed servers. The context roots will be decided by the API Manager. API Managers can’t use /prm_pm_rest and /apiplatform as API endpoints.

Lock Down a Gateway Node

Use the lockdown gateway node installer action to lockdown a node.

  1. Before you run the lockdown action, ensure that you’ve added the internal IP address of the machine onto which the node is installed in the listenIpAddress property in gateway-props.json File.

    WARNING:

    Failing to add the internal IP address of the machine to the listenIpAddress property before running the lockdown action will break operation of the gateway controller.

  2. Ensure that you have gateway manager runtime user credentials.
  3. Run the lockdown installer action.
All REST calls to locked endpoints (with /prm_pm_rest and /apiplatform contexts) from any host other than the machine you specified are rejected with the following HTTP 403 Forbidden error: IP address is not allowed.
To undo the lockdown, replace the IP values of the listenIpAddress with * (an asterisk) and run the lockdown action again.

Additional Gateway Node Lockdown Scenarios

Learn about additional gateway node lockdown scenarios.

Locking Down the Administration Server

The WebLogic Administration Console is accessible only using the administrative user credentials for the gateway node domain. This user is created when you install a gateway node domain. As this user, you can shut down the Administration Server to further secure the gateway node. The gateway node performs in limited capacity. After shutting down the Administration Server, the following gateway controller endpoints are unavailable:

  • /apiplatform/gatewaynode/v1/security/credentials

  • /apiplatform/gatewaynode/v1/security/profile

  • /apiplatform/gatewaynode/v1/registration

  • /apiplatform/gatewaynode/v1/registration

See REST API for the Gateway Controller in Oracle API Platform Cloud Service.

Multiple Ethernet Interfaces Exist

If multiple ethernet interfaces exist for the machine you install a node to, the lockdown action uses the ones specified in the listenIpAddress property in gateway-props.json File. Loopback IPs or use of localhost is not supported by the lockdown action.

Note:

Loopback IPs or localhost invocations to the gateway do not work and are not supported, even before lockdown.

Configure Gateway Node Firewall Properties in the WebLogic Adminsitration Console

Gateway nodes allow firewall properties to be configured. These properties will apply to all incoming traffic of application/json and application/xml types to APIs deployed on the gateway.

These limitations are not applied on the management endpoints that gateway controller exposes.

You can also configure firewall properties for all nodes registered to a gateway in the Management Portal.

  1. Sign in to the node domain’s WebLogic Server Administration Console as a user with administrative privileges.
  2. From the Domain Structure panel, expand OCSG, and then click AdminServer.
  3. On the Oracle Communication Services Gatekeeper page, expand Container Services, and then click ApiFirewall.
  4. Update any of the firewall properties you want to change:

    • MaxMessageSize: Specifies the maximum size, in bytes, of the request, excluding attachments. The default value is set to 1024000. The maximum allowed value is 200MB.

    • MaxUnboundedItems: Specifies the maximum number of unbounded items that a message can contain. The default value is set to 1024.

    • MaxItemValueLength: Specifies the maximum size of a single message entity, such as an element, attribute or comment. The default value is 102400.

    • MaxChildElementDepth: Specifies the maximum number of nested elements allowed in a message. The default value is 1024 nested elements.

  5. Click Update Attributes to save your changes.
The firewall properties you specified or updated are now enforced. You don’t need to restart the gateway node domain.

Additional Firewall Properties

Your network implementation can be vulnerable to denial of service (DOS) attacks, which generally try to interfere with legitimate communication inside the Gateway in Oracle API Platform Cloud Service .

To prevent these messages from reaching your network, Gateways in Oracle API Platform Cloud Service offer configurable RESTful message filtering. You configure this filtering behavior by using the ApiFirewall configuration MBean. ApiFirewall determines how Gateways in Oracle API Platform Cloud Service filters messages attempting to enter Oracle API Platform Cloud Service.

Attack Strategy Protection Strategy Default Result

Malicious Content Attack, including:

RESTful message attacks:

  • Oversize message layouts.

  • Oversize JSON or element values.

  • Oversize JSON array elements.

  • Messages with an inordinately large number of nested elements.

The ApiFirewall MBean settings (application tier) limit the acceptance of oversize message entities.

Rejects the message and returns the error message specified with the ErrorStatus attribute of ApiFirewallMBean.

Continuous wrong password attack.

The default WebLogic Security Provider setting (application tier) locks a subscriber out for 30 minutes after 5 wrong password attempts. This behavior is configurable. See the section on Protecting user Accounts in Administering Security for Oracle WebLogic Server for more information.

Rejects the message and returns a 500 Internal Server Error message.

External Entity Reference

Gateways in Oracle API Platform Cloud Service ApiFirewall (application tier) prohibits all references to external entities. It is possible to remove this protection.

Rejects the message and returns a 500 Internal Server Error message.

Configure Analytics Properties

Oracle API Platform Cloud Service gateway nodes use Logstash to collect analytics. Logstash aggregates data on each node before sending it to the management tier. Configure properties on each gateway node to determine how analytics are collected and how data is sent to the management tier.

To configure analytics properties:

Ensure that you perform this task as the user who installed the gateway. That user owns the analyticsagent.properties file you edit.

  1. In a plain text editor, open the analyticsagent.properties file in this directory on the gateway node domain: <GATEWAY_DOMAIN_HOME>/apics/analytics/.
  2. Edit the properties you want to change, and then save the file.
    Property Name Description Default Value

    excluded_fields

    Specifies which fields are excluded from generated EDR log file. Setting to None prints all fields. Separate multiple fields with commas.

    Valid values: None, Class, Method, ServiceName, ServiceProviderGroup, ServiceProviderId, Source, TagEdr, Direction, TsAfNT, TsBeNT, and status.

    Class,Source,TagEdr,Direction,AccessUrl,AppInstanceId,ServiceName,ServiceProviderGroup,ServiceProviderId,TransactionId,TsAfNT,TsBeNT,ErrCat,status

    rotate_filesize

    Size limit of log files. Rotation is timer based, so size will not be precise.

    Example values include: 100k, 10m, 2g

    500M

    max_logs

    Number of log files to retain. Once this value is reached, older archives are deleted on subsequent rollovers. Value of 0 means all log files are retained and none are deleted.

    10

    edr_buffersize

    Size of the EDR log buffer.

    Example values include: 100k, 10m, 2g

    4m

    edr_flush_interval

    EDR log flush interval, in milliseconds.

    5000

    logstash_check_interval

    Logstash process health check interval. If Logstash process is not detected, Analytics Agent attempts to restart.

    Example values include: 100ms, 30s, 5m, and 1h.

    15s

    stop_retry_logstash_after

    Time limit for Logstash restart attempts, after which Agent will no longer try to restart Logstash. Run <GATEWAY_DOMAIN_HOME>/apics/analytics/manageLogstash.sh start to reset this state. Setting this property to 0 means there is no time limit; the Agent will never stop trying to restart Logstash.

    Example values include: 0, 100ms, 30s, 5m, and 1h.

    5m

    logstash_install_dir

    Logstash installation directory, specified as a path relative to domain/gateway1.

    Logstash is installed at the default value when you install a gateway node domain.

    Note: You should not change this value. It is the only supported Logstash install location.

    ../../install/LOGSTASH_HOME/logstash-2.2.2

    logstash_worker

    Number of Logstash workers. Default value is the number of cores.

    -

    logstash_pipeline_batch_size

    Maximum number of events an individual worker thread collects before attempting to execute filters and outputs. Larger batch sizes are generally more efficient, but increase memory overhead.

    125

    logstash_heap_size

    Logstash heap size. Sets LS_HEAP_SIZE environment variable when starting Logstash.

    -

    logstash_pipeline_batch_delay

    Maximum amount of time, in milliseconds, that Logstash waits for new messages after receiving an event in the current pipeline worker thread. This option adjusts the latency of the Logstash pipeline. This rarely needs to be tuned.

    5

    logstash_custom_params

    Custom Logstash parameters, appended at end of the command line invoking logstash.

    --verbose -l /tmp/logstash.out

    apics_analytics_latency_min

    Minimum time, in milliseconds, between statistics uploads to the management tier.

    5000

    apics_analytics_map_expiration

    Map expiration, in milliseconds of processing time, per time period. This value must be longer than the amount of time it takes to process one time period.

    A use case for increasing this value is to handle nonsequential processing of multiple days of logs spread over a large number of log files.

    1800000

    apics_analytics_log_replay_limit

    Maximum number of time periods to replay, starting from most recent, on Logstash restart. Smaller numbers help restart performance. Larger numbers provide data reliability on restart when processing partially sorted log files. Empty time periods are not counted. Out of order data belonging to time periods before the start of replay are lost.

    10

    apics_analytics_insecure_ssl

    Allow transmission of statistics to the management tier over insecure SSL. Transmission over insecure SSL is disabled when this value is false.

    Valid values include: false, logstash, and curl.

    false

    always_reconfig_restart_logstash

    Logstash conf/* files will be recreated from templates/* on Logstash restart if set to true.

    false
The configuration is checked about every 10 or 15 seconds. When changes are detected, Logstash restarts and the updated properties take effect. You don’t need to restart the node domain.

About Logstash Retry Logs

The Oracle API Platform Cloud Service uses retry logs with logstash to improve performance and reliability. If the network has a high load, bad connectivity, or goes up and down frequently, the retry logs prevents logstash from stopping and starting, which causes performance issues on the gateway.

In the case of processing failures in which a CSV cannot be sent or an EDR cannot be processed, events are written to separate log files which then feeds back into logstash. Multiple files prevent concurrency issues, since only one file can be written at a time. Each type of failure has its own log file:

  • When EDRs are consumed before logstash has been configured, the individual EDR log lines that failed are written to a Logs/RETRY_EDR_YYYY-MM-dd-HH-mm.%{edr_log_basename}.log file. Since tenant credentials can be updated dynamically, the config json file can be sent at any time while logstash is running. One effect of this dynamic update is that EDRs can be read before the configuration file is sent. In these cases, these early EDRs are sent back into the RETRY_EDR log, and picked up by a separate logstash file Input, with a slower poll interval. These EDRs are aggregated by log_file matching the RETRY_EDR name.

  • When the management tier does not send an HTTP 200 to the plugin because of bad credentials, HTTP timeouts, or other server errors, the retry events are written to a Logs/RETRY_HTTP_YYYY-MM-dd-HH-mm.log file. The CSV in these RETRY_HTTP events is still aggregated by the original log file name.

  • When there is an HTTP failure if the tenant credentials are missing, the retry events are written to a Logs/RETRY_CRED_YYYY-MM-dd-HH-mm.log file. The processing behavior is the same as the RETRY_HTTP logs. They go into a separate log to avoid concurrency issues. This type of retry should not happen in single tenant mode.

    In multi-tenant mode, it can happen between the time of tenant onboarding and the time logstash gets the updated configuration file containing the new credentials.

In some rare cases, it is possible for EDR totals in the database not to match the totals in the log files. This is possible when logstash failure overlaps with management tier failure. The mismatch should be relatively small.

Every retry creates a new line in one of the RETRY log files. If logstash is restarted, it may try to reprocess the RETRY log files. Since the logic uses ?increaseOnly=true, no data is lost or overwritten.

Retry log files should be purged by file age and sincedb status. Purging is done by the Analytics agent.