3 Securing Network Traffic

Authenticating Applications

To authenticate applications, you select a security method when you create the API. The choices depend on the type of API you creating, and include:

• None - In some cases you can create an API that does not require authentication.

• Text - Authenticates using a username and password.

• OAuth - Protects third-party resources using security tokens.

• Appkey - Authenticates using an application key.

See ”Securing Services Gatekeeper Methods and API Services” in Services Gatekeeper API Management Guide for more information on these options.

Authenticating Users

For authenticating users you configure one or more of the WebLogic server security providers by using the Administration Console. Follow these general steps to configure a WebLogic security provider:

1. Start the Administration Console.

   See ”Starting and Using the Administration Console” in Services Gatekeeper System Administrator's Guide for details

2. In the Domain Structure pane, navigate to Security Realms, then realm_name (myrealm by default), and click Providers.

   The Authentication tab displays the list of Authentication Providers (security providers).

3. Configure one or more provider to authenticate users.

   Note:

   If the provider has a Control Flag setting (JAAS flag), choose the Optional option, so Services Gatekeeper will also use the API application authorization setting (text, OAuth, or Appkey). That is, simply authorizing the user is insufficient protection; you also need to authorize the application using the API authorization method.

4. Save your changes and release the configuration.

For more information on WebLogic security providers and instructions on how to configure them in ”Configuring WebLogic Security Providers” in Fusion Middleware Securing Oracle WebLogic Server.

Configuration Events

The reporter and shield MBeans publish configuration to the reporter and shield actuators upon startup. On update, the MBeans publish changes from attribute or operation invocations. The actuators request a configuration push on startup so that it does not matter whether AT or NT is started first. The actuators get the configuration in either case.

Caches

Both reporters and shields use volatile caches, using the class com.tangosol.net.cache.LocalCache. The following example constructs a cache in which cUnits is the number of units that the cache manager will cache before pruning and cExpiryMillis is the number of milliseconds that each cache entry lives before being expired.

LocalCache
public LocalCache(int cUnits, int cExpiryMillis)

The caches used by reporters track the number of violations that an entity performs; the caches used by shields hold the blocked entities.

Reporter Interface

Services Gatekeeper sets FullThreadsConfiguration by default which supports the following operations:

• GetFullThreatConfiguration: Returns the full JSON configuration for s threat definition.

• UpdateThreatConfiguration: Update the configuration for a threat (in JSON format).

The Reporter interface allows you to define the following per threat type:

• How to define a threat - for example, x violations of type y over time z.

• What entity to track, for example IP or user account

  • If IP, from where to pull IP

• How to report the threat violation - that is, alarm, block or both

The following example shows the Reporter interface:

/* Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved. */
package oracle.ocsg.threat_protection;
 
import com.bea.wlcp.wlng.api.storage.configuration.ConfigurationException;
 
/**
 * MBean for reporter.
 */
public interface ReporterMBean {
  String INSTANCE_NAME = "ThreatProtection";
  String SHARED_STORE = "shared_config";
  String SERVICE_NAME = "Reporter";
  String MBEAN_CONFIG_CHANNEL = "reportermbean";
  String MBEAN_CONFIG_EVENT = "reporterconfig";
  String MBEAN_CONFIG_EVENT_REQUEST = "reporterconfigreq";
  String KEY_IP_HTTP_HEADER = "KEY_IP_HTTP_HEADER";
 
  void setIpHttpHeader(String header) throws ConfigurationException;
 
  /**
   * Read only CSV list of available actions that can be taken on threat
   * violations.
   */
  String availableActions = "";
  String getAvailableActions();
  /**
   * Read only CSV list of available entities that can be tracked on threat
   * violations.
   */
  String availableEntities = "";
  String getAvailableEntities();
 
  /**
   * Brief description of all threats (Name, Action, Description)
   */
  String briefThreatsConfiguration = "";
  String getBriefThreatsConfiguration();
 
  /**
   * Full Reporter configuration in JSON format.
   */
  String fullThreatsConfiguration = "";
  String getFullThreatsConfiguration();
 
 
  /**
   * When tracking violations based on originating IP the IP address will be taken
   * from this HTTP header.If empty string is configured the ip address will be
   * taken from HttpServletRequest.getRemoteAddr()
   *
   * Using a HTTP header can be suitable if there is a load balancer between
   * applications and OCSG.
   *
   * Note! OCSG makes no processing of the supplied value in the HTTP header.
   * eg, if we have X-Forwarded-For configured here and we get a  request
   * containing this
   *
   * X-Forwarded-For: 203.0.113.195, 70.41.3.18, 150.172.238.178
   * the full string (203...178) will be considered to be the offending "ip".
   * This will be fine as long as subsequent messages travel the same route.
   */
  String ipHttpHeader = "";
  String getIpHttpHeader() throws ConfigurationException;
 
  /**
   * Update the configuration for one threat in JSON format.
   *
   *
   * <ul>
   * <li><strong>Scope</strong>: Cluster</li>
   * </ul>
 
   * Example JSON content:
   * {
   *   "name":"AppKeyLoginFail",
   *   "actions":[
   *     "ALARM",
   *     "BLOCK"
   *   ],
   *   "trackedEntities":[
   *     "IP"
   *   ],
   *   "maxTrackedEntities":10000,
   *   "maxViolations":10,
   *   "violationClearTime":30,
   *   "description":"APPKEY login failure, only applicable for IP entity."
   * }
   *
   * Attributes explained:
   *
   * name - The name of the threat, see getBriefThreatsConfiguration() to see
   * which are available.
   *
   * actions - Empty array if no action should be taken.
   *           see getAvailableActions() to see which actions are available.
   *
   * trackedEntities - Empty array if no entities should be tracked (ie same
   * effect as haveing no actions enabled)
   *                   see getAvailableEntities() to see which entities are
   * available
   *
   * maxTrackedEntities - Per tracked entity type, the maximum number of entities
   * to track violations for.
   * Each tracked entity reside in volatile memory on each AT server and is
   * cleared on restart.
   * If more violations are coming from more entities than we can track, the
   * entity  that has the oldest violation will be removed from tracked entity.
   *
   * maxViolations - The maximum allowed violations (eg failed APPKEY logins).
   *                 If maximum allowed violations is reached, the next violation
   *                 will trigger configured actions.
   *
   * violationClearTime - The number of seconds that need to elapse before an
   * entity violations are cleared.
   * This timer is reset each time a violation happens.
   *
   * description - Textual description of this configuration, eg explains what
   * would cause this protection to trigger.
   *
   * Note! Violations can be cleared by time (violationClearTime), or other threat
   * specific situation, for example APPKEY violations are cleared if a successful
   * login is performed.
   * Note! Once a block action has been triggered violations cannot be cleared by
   * violationClearTime. Block will be in effect for as long as the shield is
   * configured.
   * Note! Violations are tracked separately on each server, but once shield is
   * raised it is raised on all nodes.
   * Note! The maxTrackedEntities isn't an exact value, real value can be bigger
   * depending on internal purge algorithm.
   * Note! All entities might not be supported for all threats, ie protections
   * prior to authentication can not track APP_INST_ACCOUNT for example, as no
   * account has been authenticated yet.
   *
   * @param json configuration in JSON format.
   * @throws ConfigurationException if there is an issue when storing.
   */
  void updateThreatConfiguration(String json) throws ConfigurationException;
}

Shield Interface

The following example shows the Shield interface:

/* Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved. */
package oracle.ocsg.threat_protection;
 
import com.bea.wlcp.wlng.api.storage.configuration.ConfigurationException;
 
/**
 * Shield MBean interface.
 * A shield is raised in order to block a specific entity, eg. IP:130.243.31.1.
 * The MBean keeps the common configuration shared by all Shields.
 */
public interface ShieldMBean {
  String SERVICE_NAME = "Shield";
  String MBEAN_CONFIG_CHANNEL = "shieldmbean";
  String MBEAN_CONFIG_EVENT = "shieldconfig";
  String MBEAN_CONFIG_EVENT_REQUEST = "shieldconfigreq";
 
  /**
   * The time to keep the shield up in minutes.
   * <ul>
   * <li><strong>Scope</strong>: Cluster</li>
   * <li><strong>Default value</strong>: Integer: 30 minutes</li>
   * </ul>
   */
  int shieldUpTime = 30;
  int getShieldUpTime() throws ConfigurationException;
  void setShieldUpTime(int minutes) throws ConfigurationException;
 
  /**
   * The maximum number of endpoints that can be blocked at the same time.
   * Note! This isn't an exact value, real value can be bigger depending on purge
   * timers.
   *
   * <ul>
   * <li><strong>Scope</strong>: Cluster</li>
   * <li><strong>Default value</strong>: Integer: 100 endpoints</li>
   * </ul>
   */
  int maximumEntitiesToBlock = 100;
  int getMaximumEntitiesToBlock() throws ConfigurationException;
  void setMaximumEntitiesToBlock(int entities) throws ConfigurationException;
 
  /**
   * Unblock a blocked entity.
   * @param entity the entity type, see ReporterMBean for available types.
   * @param name The entity to unblock.
   */
  void unBlock(String entity, String name);
}

Usage

Alarm 921004 occurs when a request is blocked. In the following example, a request from application instance account appkey_Password1 was blocked as indicated by the APP_INST_ACCOUNT attribute.

{
  "DenyCode":"200",
  "Position":"after",
  "Method":"",
  "TransactionId":"b1aa38c7-67a3-497a-8a75-feb350a6d81c",
  "Class":"ErrorServlet",
  "Processors":"\"seq=0, name=TrafficThrottler, status=Success, new_principals=0\", \"seq=1, name=ShieldHttpProcessor, status=Success, new_principals=0\", \"seq=2, name=CORSProcessor, status=Success, new_principals=0\", \"seq=3, name=AppKeyHttpProcessor, status=Deny, code=200\"",
  "APP_INST_ACCOUNT":"appkey_Password1",
  "Timestamp":"1507977661843",
  "URL":"",
  "Source":"Exception",
  "TagAlarm":"921004",
  "ServerName":"Server1"
}

In this example, a request from IP address 130.243.31.1 was blocked as indicated by the IP attribute.

{
  "DenyCode":"200",
  "Position":"after",
  "IP":"130.243.31.1",
  "Method":"",
  "TransactionId":"d4e018af-acd9-4c36-b0d0-0a581561d818",
  "Class":"ErrorServlet",
  "Processors":"\"seq=0, name=TrafficThrottler, status=Success, new_principals=0\", \"seq=1, name=ShieldHttpProcessor, status=Deny, code=200\"",
  "Timestamp":"1507977772755",
  "URL":"",
  "Source":"Exception",
  "TagAlarm":"921004",
  "ServerName":"Server1"
}

Alarm 921001 occurs when the number of violations has reached maxViolations + 1 and as a result the violator is blocked. The time between two violations never exceeded violationClearTime. The following example shows the alarm where attribute Threat holds the violation AppKeyLoginFail.

{
  "Shielded":"true",
  "IP":"130.243.31.1",
  "Class":"ViolationHelper",
  "Timestamp":"1507977772393",
  "TagAlarm":"921001",
  "ServerName":"Server1",
  "Threat":"AppKeyLoginFail"
}

Alarm 921002 occurs when the number of violations has reached maxViolations + 1 and the time between two violations never exceeded violationClearTime but the violator is not blocked. alarm where we can see that attribute Threat holds the violation AppKeyLoginFail.

{
  "Shielded":"false",
  "DenyCode":"44",
  "ReqAction":"[\"seq=1, name=OAuth2Validator, status=Success\"]",
  "Position":"before",
  "ServiceProviderId":"partner",
  "TransactionId":"e09ecf72-0610-4154-829d-658a4f580b0f_IDX_3",
  "ServiceName":"/ECHOServer/1",
  "State":"ENTER_NT",
  "Class":"ViolationHelper",
  "ApplicationId":"weather",
  "Processors":"\"seq=0, name=TrafficThrottler, status=Success, new_principals=0\", \"seq=1, name=ShieldHttpProcessor, status=Success, new_principals=0\", \"seq=2, name=CORSProcessor, status=Success, new_principals=0\", \"seq=3, name=AppKeyHttpProcessor, status=Success, new_principals=2\"",
  "TsBeAT":"1508158225153",
  "HttpMethod":"POST",
  "APP_INST_ACCOUNT":"appkey_Password1",
  "TsBeNT":"1508158225153",
  "Timestamp":"1508158225153",
  "Direction":"south",
  "Source":"method",
  "URL":"/ECHOServer/1/echo",
  "ServiceProviderGroup":"gold",
  "AppInstanceId":"appkey_Password1",
  "TagAlarm":"921002",
  "APPEnforcers":"\"seq=0, name=RequestContextParamsEnforcer, status=Success\", \"seq=1, name=BlacklistedMethodsEnforcer, status=Success\", \"seq=2, name=MethodParametersEnforcer, status=Success\", \"seq=3, name=FilterResultEnforcer, status=Success\", \"seq=4, name=MethodEnforcer, status=Success\", \"seq=5, name=BudgetEnforcer, status=Deny, code=44\"",
  "ServerName":"Server1",
  "ApiId":"ECHOServer",
  "ReqMsgSize":"36",
  "Threat":"SlaViolation"
}