Configure API Gateway

This section describes how to configure API Gateway to work with Oracle Entitlements Server.

Complete the following tasks:

Modify the API Gateway classpath

API Gateway's classpath must be extended to include the OES client JAR. To achieve this, create a jvm.xml file at the following location:

INSTALL_DIR/apigateway/conf/jvm.xml

Edit this jvm.xml so that its contents are as follows, providing values for OES_CLIENT_HOME and SM_NAME that are based on the location where the OES client was installed and the SM name used when enrolling the OES client (MySM):

<ConfigurationFragment>
<!-- Change these ENV VARS to match the location where the OEM Client has
been installed and configured -->
<Environment name="OES_CLIENT_HOME" value="/home/oes/Oracle/Middleware/oes_client" />
<Environment name="SM_NAME" value="MySM" />
<Environment name="INSTANCE_HOME"
value="$OES_CLIENT_HOME/oes_sm_instances/$SM_NAME" />

<!-- Add OES Client JAR to the classpath -->
<ClassPath name="$OES_CLIENT_HOME/modules/oracle.oes.sm_11.1.1/oes-client.jar" />

<!-- Add OES JARs to the classpath →
<ClassPath name=”[PATH_TO_OES_JARS]/api.jar”/>
<ClassPath name=”[PATH_TO_OES_JARS]/asi_classes.jar”/>

<VMArg name="-Doracle.security.jps.config=$INSTANCE_HOME/config/jps-config.
xml"/>
<!-- Optional argument to add enhanced logging (via log4j) for the OES Client -->
<VMArg name=”-Djava.util.logging.config.file=$INSTANCE_HOME/logging.properties”/>
</ConfigurationFragment>

The following is an example jvm.xml file for Windows:

<ConfigurationFragment>
  <!-- Environment variables -->
  <!-- change these to match the location where the OEM Client has been installed and configured -->
<Environment name="OES_CLIENT_HOME" value="C:\Oracle\product\11.1.1\as_1" />
<Environment name="SM_NAME" value="MySSM" />
<Environment name="INSTANCE_HOME" value="$OES_CLIENT_HOME/oes_sm_instances/$SM_NAME" />
<!-- Add OES Client to classpath -->
<ClassPath name="$OES_CLIENT_HOME/modules/oracle.oes.sm_11.1.1/oes-client.jar" />
<VMArg name="-Doracle.security.jps.config=$INSTANCE_HOME/config/jps-config.xml"/>  
</ConfigurationFragment>

Start API Gateway

Start API Gateway so that it runs with the OES client classpath and the associated environment settings. Refer to the API Gateway Installation Guide for instructions on how to start API Gateway.

Command example:

> startinstance -n "APIGateway1" -g "Group1"

Configure API Gateway to delegate authorization to OES

This section explains how to configure API Gateway to delegate authorization decisions to Oracle Entitlements Server.

The following steps are required:

The resulting policy created in API Gateway will appear as follows:

Step 1 - Configure the authentication filter

In this example, it is assumed that the user profile to be authorized through OES is also stored in the local user store of API Gateway. API Gateway can also delegate authentication decisions to other systems (for example, LDAP directories, databases, and other third-party identity management systems, including CA SiteMinder, Oracle Access Manager, RSA Access Manager, and so on). For simplicity, API Gateway's local user store is used in this example.

Configure the authentication filter as follows:

  1. In Policy Studio, create a new policy called OES Authorization.
  2. Drag a HTTP Basic filter from the Authentication category in the palette onto the canvas and configure it as follows:
    • Name: Enter HTTP Basic Authentication in the field provided.
    • Credential Format: Select User Name from the drop-down list.
    • Allow Client Challenge: Select the Allow client challenge check box.
    • Repository Name: Select Local User Store from the drop-down list.
  3. The completed configuration for the filter appears as follows:
  4. Click OK.
  5. To set this authentication filter to be the starting filter of the policy, right-click the filter in the canvas and select Set as Start.

Step 2 - Configure the OES 11g authorization filter

Configure the OES 11g authorization filter as follows:

  1. From the Oracle Entitlements Server category in the palette on the right of Policy Studio, drag the 11g Authorization filter onto the canvas, and configure it as follows:
    • Resource: Enter a formatted string representing the resource that you created in OES and for which API Gateway will ask OES for authorization decisions. The resource you created earlier in OES can be represented with the string MyApplication/MyResourceType/MyResource.
    • Action: The rules created in the OES policy can permit/deny access to a resource based on the requested action, for example, POST, GET, DELETE, and so on. In this example, you will be POST-ing the request to the resource, so you must enter POST in the Action field. Remember, you configured POST access to the this resource earlier when configuring the OES policy.
    • You can optionally configure environment context attributes. However, for the purposes of this integration example it is not necessary to configure this section.
  2. The completed configuration appears as follows:
  3. Click OK.
  4. Set the success path from the HTTP Basic Authentication filter to point at the newly created OES 11g authorization filter.

Step 3 - Add the success message filter

Display a success message after successfully authorizing the user by adding a Set Message filter.

  1. Drag a Set Message filter from the Conversion category onto the canvas and configure it as follows:
    • Name: Enter Set Success Message in the text field.
    • Content-type: Enter text/plain as the content-type of the message to return to the client.
    • Message Body: Enter the following message to return to the client: User '${authentication.subject.id}' was authorized successfully!
  2. The configuration for the Set Success Message filter should now look like this:
  3. Click OK.
  4. Set the success path of the 11g authorization filter to the Set Success Message filter.

Step 4 - Add the failure message filter

If OES returns false for the authorization request you should return an appropriate error message to the client.

Display a failure message after an unsuccessful authorization event by adding another Set Message filter:

  1. Drag a Set Message filter from the Conversion category onto the canvas, and configure it as follows:
    • Name: Enter Set Failure Message in the text field.
    • Content-type: Enter text/plain as the content-type of the message to return to the client.
    • Message Body: Enter the following message to return the client: The user '${authentication.subject.id}' was NOT authorized to access the resource!
  2. The configuration for the Set Failure Message filter should now look like this:
  3. Click OK.
  4. Set the failure path of the 11g authorization filter to the Set Failure Message filter.

Step 5 - Add a relative path for the OES authorization policy

In order for API Gateway to invoke this policy for certain requests you must create a relative path and map it to the policy. All requests received on this path are automatically forwarded to the policy for processing.

To add a relative path for this policy click Add Relative Path in the toolbar beneath the policy canvas.

Enter the path on which to receive requests for this policy in the field provided in the Resolve path to Policies dialog:

For example, if you enter a relative path of /oes, you can see that this path is automatically mapped to the OES Authorization policy created earlier in this section.

Step 6 - Deploy the policy

To push the configuration changes to the live API Gateway instance you must deploy the new policy. You can do this by pressing the F6 button.

Related Links