Integrating Oracle API Gateway 11gR2 (11.1.2.4.0) with Microsoft Azure AD [Article]

Version 9

    Oracle API Gateway (OAG) integrates, accelerates, governs, and secures Web APIs and SOA-based systems.To demonstrate the integration between API Gateway and Azure, author Ricardo Guiterrez provides the technical details of a scenario in which a company exposes on-premise web services with a partner company.


     

    By Ricardo Gutierrez

     

    Oracle API Gateway Overview

     

    Oracle API Gateway (OAG) is a product that integrates, accelerates, governs, and secures Web APIs and SOA-based systems. It routes traffic based on content and sender and performs message content screening. The API Gateway applies policies to incoming messages by running message filters on requests, supporting a wide range of message transports, protocols, and formats, including XML, JSON, SOAP, REST, HTTP, JMS, TIBCO, FTP, SMTP, POP among others.

     

    In a typical deployment scenario, Oracle API Gateway is deployed in the demilitarized zone (DMZ). The connection between the client and the API Gateway is protected by a perimeter firewall, and the connection between the API Gateway and the back-end service by a Network Address Translation (NAT) firewall.

     

    The following figure depicts the use of API Gateway across different scenarios.

     

    01-oag-deployment.jpg

     

    Figure 1. Deployment across Different Scenarios

     


     

    The Oracle API Gateway does for APIs what the application server does for applications, and can be seen as the API runtime environment providing services such as:

     

    • Security (for example, authentication and authorization)
    • Connectivity with a range of different protocols
    • Virtualization
    • Scalability and elasticity
    • High availability
    • Manageability (for example, using API Gateway Manager)
    • Development simplicity

     

    02-oag-core-infra.jpg

     

    Figure 2. API Gateway as Core Infrastructure

     

    Because the API Gateway provides a core API infrastructure, developers can focus on providing the application logic. They no longer need to build these services into their applications, and can leverage the core infrastructure provided by the API Gateway.

     

    Oracle API Gateway provides powerful tools (see Figure 3) that enable the development, deployment, and management of API solutions:

     

    • API Gateway, is the core component that manages, delivers, and secures APIs. Provides services such as API transformation, control and governance, security and monitoring.
    • Policy Studio, is a graphical tool used to virtualize APIs and develop policies.
    • API Explorer, is a graphical tool to assist with testing API performance, scalability, and security.
    • Configuration Studio, is a graphical tool to promote API Gateway configurations from development environments to upstream environments (e.g. testing or production).
    • API Gateway Manager, is a web-based administration console to manage one or more API Gateway instances.
    • Analytics Console, is a web-based monitoring and reporting console.
    • Key Property Store, is used to store configuration parameters that are dynamically passed into policies at runtime.
    • Client Application Registry, is a web-based interface for managing client applications.

     

    03-oag-tools.jpg

     

    Figure 3. API Gateway Tools

     


     

    System Architecture

     

    Figure 4, depicts the system architecture of the API Gateway. A node manager must exist in each host machine where one or more API Gateway instance is running. A node manager can play the role of central administration if designated as the primary node within a domain of multiple API Gateway instances. Moreover, each API Gateway instance consist of several components providing different services.

     

    04-oag-system.jpg

     

    Figure 4. API Gateway - System Architecture

     


     

    Extensibility and Customization

     

    Among the integration features of the API Gateway, a pluggable pipeline provides extensibility, enabling extra access control and filter rules to be added easily. Moreover, API Gateway enables identity mediation between different identity schemas, for example by authenticating external client user name and password and then issuing SAML tokens that can be used for identity propagation to application servers.

     

    Custom Filters

     

    Custom filters provide extended functionality to the API Gateway. The following options are available when building a custom filter:

     

    • Write custom code in Java and invoke it using the Scripting Language filter. In this case you develop the code using a standard IDE like JDeveloper or Eclipse to test and debug it in standalone mode before integrating with API Gateway. This approach is suitable for enterprise integration.
    • Write custom code in JavaScript or Groovy using the Scripting Language filter alone. This approach allows a quick and easy way to reuse some functionality exposed in Java
    • Write a custom filter using API Gateway developer extension kit. Using this option, a fully integrated filter is created that has the API Gateway runtime capability and is available in the filter palette in Policy Studio.

     

    For the integration described in the next sections, we have chosen the first option which allows the development of a custom filter in Java using Microsoft ADAL and Graph API interfaces to communicate with Azure AD.

     

    Important Note:

     

    The integration described in this article has been tested with the following versions of Oracle API Gateway:

     

    • Release 11.1.2.4.0 and 11.1.2.4.0 SP1
    • Release 11.1.2.3.0

     

    About Microsoft Azure AD

     

    Microsoft Azure Active Directory (AD) is a multi-tenant cloud based directory and identity management service for applications running in Microsoft Azure and on-premises. It’s important to highlight that Azure is not Windows Server Active Directory running in the cloud and therefore does not support technologies like Windows NTLM, Kerberos or LDAP. Instead Azure AD relies on common protocols like OAuth 2.0, WS-Federation, SAML-P, OpenID Connect and REST API interfaces to communicate with applications.

     

    Applications must be registered to an Azure AD tenant when you want users in an organization to be authenticated against an Azure directory before accessing the application. Azure uses this configuration as a way to identify an application and issue authentication tokens when authenticating users.

     

    Azure AD Authentication Library (ADAL)

     

    ADAL is a Microsoft library that aims to facilitate the development of client applications that need to authenticate users and acquire security tokens (JWT) that can be used when calling APIs. The ADAL library is available for several programing languages including Java which can be downloaded from this link.

     

    Azure AD Graph API

     

    The Azure AD Graph API is a REST API interface that Azure Active Directory makes available for each tenant. You can programmatically access the directory and query users, groups and tenant information among other details. In addition, Graph API can be used to create, update or delete entities (e.g. users or groups) in the directory.

     

    Integration Scenario

     

    To demonstrate the integration between API Gateway and Azure, we will consider a scenario where a company Acme Enterprises would like to expose on-premise web services with a partner company. The partner stores and maintains its employee directory in cloud directory service Azure AD, however Acme will like to define the level of access that the partner should manage with their employees when accessing the web services. For example, Acme Enterprises has two services “Service Product Catalog” and “Service Product Price”, these should be available to the partner based on group membership. Employees in the   partner directory who belong to group “ProductCatalog” will have access to the product catalog service while members of “ProductPrice” group will have access to the product price service. The partner controls the employee access based on these groups while Acme Enterprises dictates the group names that the partner must create and assign to access the services.

     

    In addition, Acme Enterprises will like to make its SOAP web services available as REST services to cope with partner’s demands for an "easy to use" interface.

     

    The following figure depicts the scenario using API Gateway, generally referred as a hybrid cloud approach.

     

    05-oag-integration.jpg

     

    Figure 5. Integration with Azure AD

     

    To accomplish Acme’s requirements we are going to use a custom filter that will rely on ADAL and Graph REST API interfaces to communicate with Azure AD. The diagram in Figure 6 describes in detail a sample use case.

     

    1. Partner invokes REST web service “Service Product Catalog” thru API Gateway. To make this possible, API Gateway has been configured to virtualize Acme SOAP web services.
    2. API Gateway, extract the user credentials (username and password) from the service request, and send an authentication request via a custom filter to Azure AD. The custom filter leverages Microsoft ADAL and REST API interfaces to communicate with Azure.
    3. Azure AD authenticates the user credentials and generates a bearer token which includes in the response send to the custom filter.
    4. The custom filter uses the bearer token to invoke a Graph API operation requesting group membership information for the user in question.
    5. Azure AD returns the requested group information back to the custom filter.
    6. API Gateway evaluates the group information provided by the filter and determines if the user belongs to “ProductCatalog” group, if so proceeds to transform the REST request into a SOAP request which then uses to invoke Acme web service “Service Product Catalog”.
    7. Acme web service process the request and returns the result back to API Gateway.
    8. API Gateways transform the resulting XML data into JSON format and forwards the result back to the partner.

     

    06-oag-sequence.jpg

     

    Figure 6. Sample Authentication and Authorization Use Case

     


     

    Developing a Custom Filter Class

     

    This section describe the steps to build and test a custom filter class in Java to integrate API Gateway with Azure AD. The high level steps are:

     

    1. Register a native application in the partner’s directory (Azure AD)
    2. Create a Java class using your favorite IDE (e.g. JDeveloper or Eclipse)
    3. Build the class using the ADAL for Java library
    4. Deploy the class in API Gateway
    5. Define an API Gateway policy to transform REST to SOAP web services
    6. Define an API Gateway policy to invoke the filter class
    7. Define a listener and URL path to virtualize the web services
    8. Invoke the REST web services to test the integration

     

    Figure 7, depicts the solution based on a custom filter class that integrates with Azure AD. As indicated previously, API Gateway relies on policies and a pipeline processing model that uses filters for processing of data. An out-of-the-box (1) Scripting Filter is used to invoke a custom filter class that uses (2) ADAL and Graph API interfaces to communicate with Azure AD and perform (3) authentication and CRUD operations against the tenant’s directory.

     

    07-oag-policy.jpg

     

    Figure 7. Solution Based on Custom Filter

     


     

    1. Register a Native Application in Azure AD

     

    Azure AD generates a client ID for each application that is registered in a tenant’s directory, this is further needed by the application to identify itself when performing operations like authentication. Two application types are available: Web and Native, for our case a native application is needed to represent the filter class that will communicate with Azure. To register an application, the partner administrator needs to sign-in to the Azure portal to register the new application. The following instructions detail the procedure:

     

    1. Login as partner administrator to Azure portal https://manage.windowsazure.com. Select the directory and then choose ADD to register the new application. For our scenario, we use the following values:

     

    Name: Acme Integration

     

    Type: Native Client Application

     

    Redirect URI: http://AcmeIntegration

     

    Noted that the URI does not need to be an actual address but a unique identifier for the application. Figures 8 shows the registration process.

     

    08-aad-create-app.jpg

     

    Figure 8. Registering a Native Application

     


     

    2. Once, the application is registered, we edit the application configuration to obtain the CLIENT ID. To so, within the partner directory, select APPLICATIONS, click on Acme Integration to show the configuration.

     

    09-aad-app-config.jpg

     

    Figure 9. Application Configuration

     

    Further, we will need the CLIENT ID in the custom filter class to perform the authentication with Azure. Figure 9 shows the configuration of the new application and client ID.

     

    3. Another information that is needed is the partner’s tenant ID for the directory. This value is displayed in the URL field of the browser anytime we navigate to the directory in Azure portal. For our scenario, this value is highlighted in Figure 10.

     

    Figure 10, shows the partner’s tenant ID in the URL string.

     

    10-aad-tenant-id.jpg

     

    Figure 10. Partner’s Tenant ID

     


     

    4. Finally, we need to define the permissions. To do so, within the directory select APPLICATIONS, click on Acme Integration and at the bottom of the page add permissions to other applications as listed in Figure 11.

     

    11-aad-permissions.jpg

     

    Figure 11. Permissions to Other Applications

     


     

    The permission for each application are:

     

    Windows Azure Active Directory

     

    • Access the directory as the signed-in user
    • Read directory data
    • Sign in and read user profile

     

    Windows Azure Service Manager API

     

    • Access Azure Service Management (preview)

     

    The permissions defined in step 4 are need so the filter class that is represent by “Acme Integration” in Azure can access the tenant’s directory (Windows Azure Active Directory) and Graph API (Windows Azure Service Manager), authenticate users and retrieve group information from the user profile. Figure 12, shows the application once the registration and permissions has been completed.

     

    12-aad-application.jpg

     

    Figure 12. Registered Application in Partner’s Directory

     


     

    2. Creating the Java Class

     

    Custom filters in API Gateway are Java classes that can be developed using a standard Java IDE. In our case we use JDeveloper 11.1.2.1.0 and Java SDK 1.7.0_79 to create a Java application project. Figures 13 and 14 shows the project structure and settings, Listing 1 shows the complete code for the main class ADAL4Java. An additional class extHTTPRequest extend the HTTPRequest class in the ADAL library to avoid using another external library when making REST API calls.

     

    The sample code in Listing 1 is self-explanatory, the class expose the authenticate method which accepts two parameters: username and password, these values along with the tenant ID and client application ID are used to submit an authentication request to the Azure endpoint and acquire a token that can be used to call Graph API operations. Noted that we use ADAL to invoke the acquireToken method from the AuthenticationContext class, and use the resulting token to later send a request to Graph using the memberOf operation. Finally, the logic converts the   resulting group information to a string that can be consumed by the Scripting Filter in API Gateway. ADAL hides the complexity of having to programmatically deal with OAuth 2.0, and for the ones wondering which OAuth 2.0 flow is being used, in this case the “Resource Owner Password Credentials” flow is used by ADAL to perform the authentication.

     

    13-jd-project.jpg

     

    Figure 13. JDeveloper Application Project

     

    14-jd-settings.jpg

     

    Figure 14. Project Settings

     


         

    package oagazurelib;
          
    import com.microsoft.aad.adal4j.AuthenticationContext;
          
    import com.microsoft.aad.adal4j.AuthenticationResult;
          
    import com.nimbusds.oauth2.sdk.http.HTTPRequest;
          
    import com.nimbusds.oauth2.sdk.http.HTTPResponse;
          
    import java.net.URL;
          
    import java.util.concurrent.ExecutorService;
          
    import java.util.concurrent.Executors;
          
    import java.util.concurrent.Future;
          
    import org.json.JSONObject;
          
    import org.json.JSONArray;
          
    import org.json.JSONException;
          
    public class ADAL4Java {
          
    // Azure endpoints
          
    private final static String AUTHORIZATION_ENDPOINT = "https://login.microsoftonline.com/";
          
    private final static String ARM_ENDPOINT = "https://management.azure.com/";
          
    private final static String GRAPH_ENDPOINT = "https://graph.windows.net/";
          
    public ADAL4Java() {
          
    super();
          
    }
          
    public String authenticate (String username, String password) {
          
    // Tenant directory ID and client application ID
          
    String tenantId = "XXXXXXXX-29f2-4ed5-a9d5-101cf97afb49";
          
    String clientId = "XXXXXXXX-1fdb-4a7c-8029-1f01f1965732";
          
    String Rgroups = "";
          
    // Using ADAL for authentication
          
    AuthenticationContext authContext = null;
          
    AuthenticationResult authResult = null;
          
    ExecutorService service = null;
          
    
          
    try {
          
    service = Executors.newFixedThreadPool(1);
          
    String url = AUTHORIZATION_ENDPOINT + tenantId + "/oauth2/authorize";
          
    
          
    // Set new authentication context
          
    authContext = new AuthenticationContext(url, false, service);
          
    
          
    // If successful authentication, acquire token
          
    Future<AuthenticationResult> future = authContext.acquireToken(GRAPH_ENDPOINT, clientId, username, password, null);
          
    authResult = future.get();
          
    } catch (Exception e) {
          
    System.out.println("EXCEPTION: " + e.getLocalizedMessage());
          
    return Rgroups;
          
    } finally {
          
    service.shutdown();
          
    }
          
    
          
    if (authResult == null) {
          
    System.out.println("EXCEPTION: Authentication result was null");
          
    return Rgroups;
          
    }
          
    
          
    // Extract token from result
          
    String BearerToken = authResult.getAccessToken();
          
    
          
    // Call Graph REST API requesting group information
          
    String url2 = GRAPH_ENDPOINT + tenantId + "/users/" + username + "/memberOf?api-version=2013-04-05";
          
    String body2 = null;
          
    
          
    try {
          
    // Set new request
          
    URL url = new URL(url2);
          
    HTTPRequest request = new extHTTPRequest(HTTPRequest.Method.GET, url);
          
    request.setAuthorization("Bearer " + BearerToken);
          
    ((extHTTPRequest)request).setAcceptType("application/json");
          
    request.setConnectTimeout(10000);
          
    
          
    // Submit request and get response
          
    HTTPResponse response = request.send();
          
    body2 = response.getContent();
          
    } catch (Exception e) {
          
    System.out.println("EXCEPTION: " + e.toString());
          
    return Rgroups;
          
    }
          
    
          
    // Extract JSON response
          
    JSONArray groups = null;
          
    
          
    try {
          
    groups = (new JSONObject(body2)).getJSONArray("value");
          
    } catch (JSONException e) {
          
    System.out.println("EXCEPTION: " + e.toString());
          
    return Rgroups;
          
    }
          
    
          
    // Tranform JSON values into a string
          
    if (groups.length() > 0) {
          
    
          
    for(int i = 0; i < groups.length(); i++){
          
    Rgroups = Rgroups + groups.optJSONObject(i).optString("displayName");
          
    if ((i+1) < groups.length()) Rgroups = Rgroups + ",";
          
    }
          
    }
          
    else {
          
    System.out.println("No groups found.");
          
    }
          
    
          
    return Rgroups;
          
    }
          
    }
    
    

    Listing 1. Custom Filter Class

     


     

    3. Building the Filter Class

     

    Building the class is a straightforward process as long as the right libraries are included in the classpath of the project. Figure 14 shows the libraries that are needed to successful compile the class. You can download the ADAL for Java library here and the dependent libraries from the Maven repository. The project must be compiled using Java 1.7 which is the version used by the Java runtime environment in API Gateway 11.1.2.3.0 and 11.1.2.4.0, trying to run the class with previous versions of the API   Gateway will trigger a runtime exception. After building the project, a jar file is generated containing two classes: ADAL4Java.class and extHTTPRequest.class.

     

    Figure 15 show the structure and content of the resulting jar file.

     

    15-jar-file.jpg

     

    Figure 15. Jar File

     

    Although all the dependent libraries are need to compile the class, not all libraries will need to be copied to API Gateway, this is detailed in the next section.

     

     

     

    4. Deploying the Class in API Gateway

     

    You can deploy the filter class by copying the jar file to INSTALL_DIR/ext/lib directory in all API Gateway instances. Additionally, you must import the jar file in Policy Studio. The following instructions detail the procedure:

     

    1. Let’s assume you have one API Gateway instance installed in the /opt/OAG-11.1.2.3.0 folder, then you must copy the jar file OAGAzureLib.jar and all dependent libraries listed in Figure 10 (with the exception of slf4j-jdk14-1.7.5.jar) to /opt/OAG-11.1.2.3.0/gateway/ext/lib folder.
    2. Open Policy Studio and connect to your API Gateway instance. Select Windows > Preferences > Runtime Dependencies and click Add to import OAGAzureLib.jar and all dependent libraries listed in Figure 10 (with the exception of slf4j-jdk14-1.7.5.jar).
    3. Re-start Node Manager and the API Gateway instance. Re-start Policy Studio from a command line with the “-clean” option (this is needed only once).

     

     

     

    Figure 16 shows the filter class along with the dependent libraries imported in Policy Studio. Once deployed, you can start defining new policies that use the new filter class.

     

    16-oag-import.jpg

     

    Figure 16. Imported Filter Class

     


     

    5. Defining a Policy to Transform REST to SOAP

     

    Since, this article focus in the integration with Azure we will briefly describe this step, please refer to the resources section at the bottom of this article to download all the sample policies used in this article. API Gateway includes out-of-the-box filters to facilitate protocol and payload transformation, Figure 17 shows a sample policy to transform requests and responses between REST and SOAP protocols, the Set the Message and Set HTTP Verb filters are used to build the SOAP message and the Connect URL filter to submit the request to the SOAP web service endpoint. The   response is converted to JSON using the XML to JSON filter. Additionally, expression filters are used to determine the type of web service (Product Catalog or Product Price) and the permissions based on group membership.

     

    Figure 17, shows the final policy in Policy Studio.

     

    17-oag-rest-soap.jpg

     

    Figure 17. Policy to Transform REST to SOAP Web Service

     


     

    6. Defining a Policy to Invoke the Filter Class

     

    This policy is the first to be trigger on each partner request submitted thru API Gateway. Uses the Extract REST Request Attributes filter to extract the credentials (username and password) from the request, do some validation using validation filters and perform the authentication against Azure AD using the Scripting Language filter which in turn invokes the custom filter class. The group information in the response is validated (authorized group ProductCatalog or ProductPrice) and a call made to the previous policy that performs REST to SOAP transformation with the back-end web service and   handles the result back to the partner. The following instructions detail the procedure to build the policy:

     

     

     

    1. Open Policy Studio and connect to the API Gateway instance.

     

     

     

    2. Select Policies from the let panel. The Policies page will be displayed in the right panel, click on Add Policy link to create a new policy. Enter the following information:

     

    Name: Access Control

     

    Click OK. An empty canvas is displayed for the new policy.

     

     

     

    3. Type “extract” in the filter text field located at the top of the tool palette in the right side of the window.

     

     

     

    4. Click on the Extract REST Request Attributes filter located in the palette and then click again in the policy canvas. A dialog is displayed showing the filter properties, since we are using the default values, click Finish to close the dialog.

     

     

     

    5. Right click in the filter and select Set as Start from the pop-up menu.

     

     

     

    6. Now, type “validate” in the filter text field located at the top of the tool palette and add to the canvas the Validate HTTP Headers filter. Enter the following information:

     

    Name: Validate HTTP Headers

     

    Proceed to add the following regular expressions.

     

    Name Type Regular Expression

     

    username Required ^[a-zA-Z0-9@.#\s]*$

     

    password Required ^[a-zA-Z0-9@.#\s]*$

     

    Click Finish to close the dialog.

     

     

     

    7. Proceed to repeat step #6 but this time add to the canvas the Validate Query String filter. Enter following information:

     

    Name: Validate Query String

     

    Proceed to add the following regular expressions.

     

    Name Type Regular Expression

     

    operation Required ^(getprice|getcatalog)$

     

    Cloe Finish to close the dialog.

     

     

     

    8. Type “script” in the filter text field located at the top of the tool palette and add to the canvas the Scripting Language filter. Enter the following information:

     

    Language: JavaScript

     

    Script

         

    importPackage(Packages.oagazurelib);
                   
    function invoke(msg)
          
    {
          
    var user = msg.get("http.header.username");
          
    var pass = msg.get("http.header.password");
                   
    var adal = new ADAL4Java();
          
    var groups = adal.authenticate(user, pass);
          
    msg.put("groups", groups);
          
    if (groups != "") return true;
          
    else return false;
          
    }
    
    

     

    In the Filter Attributes tab, enter the following information:

     

    Required

     

    http.header.username

     

    http.header.password

     

    Generated

     

    groups

     

    Click Finish to close the dialog.

     

    9. Type “compare” in the filter text field located at the top of the tool palette and add to the canvas the Compare Attribute filter. Enter the following information:

     

    Filter will pass if: one

     

    Proceed to add the following conditions.

     

    Name Condition Value

     

    groups contains ProductCatalog

     

    groups contains ProductPrice

     

    Click Finish to close the dialog.

     

    10. Type “shortcut” in the filter text field located at the top of the tool palette and add to the canvas the Policy Shortcut filter. Enter the following information:

     

    Name: Call 'Transform REST to SOAP'

     

    Check the following policy from the list available:

     

    Transform REST to SOAP

     

    Click Finish to close the dialog.

     

    11. Type “set” in the filter text field located at the top of the tool palette and add to the canvas the Set Message filter. Enter the following information:

     

    Name: Send Validation Error

     

    Content-Type: application/json

     

    Message Body: {"Error":"Please try again"}

     

    Click Finish to close the dialog.

     

    12. Now, using the Success Path and Failure Path connectors in the palette connect all the filters as displayed in Figure 18.

     

    Figure 18, shows the final policy in Policy Studio.

     

    18-oag-invoke-filter.jpg

     

    Figure 18. Policy to Invoke Custom Filter Class

     


     

    7. Defining a Listener and URL Path

     

    API Gateway protect back-end services by virtualizing these services. This means that instead of connecting to the service directly, clients connect through the API Gateway. The API Gateway can then apply policies to messages sent to the destination service (for example, to enable security, routing, monitoring, or acceleration). When the virtualized service is deployed to the API Gateway, the published URL now uses the host and port of the API Gateway.

     

    In our scenario, we will expose Acme SOAP web services thru API Gateway as REST services using the following URL path:

     

    http://localhost:8080/acmeservices

     

    The following instructions detail how this is accomplished in API Gateway:

     

    1. Open Policy Studio and connect to the API Gateway instance.

     

    2. Expand Listeners from the let panel. Select API Gateway > Default Services > Paths. In the right panel Default Services - Paths, click on the Add button and select Relative Path to add a new path. Enter the following information:

     

    When a request arrives that matches the path: /acmeservices

     

    Make sure to check only Path Specific Policy and click on the ellipsis button to select the Access Control policy created previously.

     

    3. Click OK to save the changes

     

    4. Now, we proceed to deploy all changes to the API Gateway instance. To do so, click on the deploy icon (below the menu bar top right, alternatively press F6) to open the Deploy dialog. Select the API Gateway instance and click on Deploy button to deploy the changes, then click Finish to close the dialog window.

     

    Default Services is the default HTTP listener in API Gateway and uses port 8080 by default, since we have defined a new relative path now API Gateway will invoke our Access Control policy each time a new requests is submitted thru the published URL path.

     

    Figure 19, shows the listener and URL path in Policy Studio.

     

    19-oag-listener.jpg

     

    Figure 19. HTTP Listener and URL Path

     

    Figure 20, shows the deployment results once all changes has been deployed.

     

    20-oag-deployment.jpg

     

    Figure 20. Deploying Changes to API Gateway

     


     

    8. Invoking the Web Services to Test the Integration

     

    To test the integration we are going to use Soap UI, an open source tool for API testing that supports REST and SOAP among other protocols. We considered the following test cases:

     

    • Test case 1: Partner’s application invoking REST service to obtain a list of products. The partner request includes a user credential that belongs to group ProductCatalog.
    • Test case 2: Partner’s application invoking REST service to obtain a product price. The partner request includes a user credential that belongs to group ProductPrice.
    • Test case 3: Partner’s application invoking REST service to obtain a product price. The partner request includes a user credential that does not belong to group ProductPrice.
    • Test case 4: Partner’s application invoking REST service using an unsupported operation in the query string

     

    Test Case 1

     

    Figure 21 shows Soap UI invoking the REST service with operation “getcatalog” to obtain a list of products using the following information:

     

    REST Service : http://localhost:8080/acmeservice?operation=getcatalog

     

    Azure User Password Group Membership

     

    sbrown@acmepartner.onmicrosoft.com ******** ProductCatalog

     

    21-soap-ui-test.jpg

     

    Figure 21. Invoking REST Web Service “Get Catalog”

     


     

    Figure 22 shows the execution path of the policy in API Gateway.

     

    22-oag-execution.jpg

     

    Figure 22. Filter Execution Path

     


     

    Test Case 2

     

    Figure 23 shows Soap UI invoking the REST service with operation “getprice” to obtain a product price using the following information:

     

    REST Service : http://localhost:8080/acmeservice?operation=getprice&code=0001

     

    Azure User Password Group Membership

     

    msmith@acmepartner.onmicrosoft.com ******** ProductPrice

     

    23-soap-ui-test.jpg

     

    Figure 23. Invoking REST Web Service “Get Price”

     


     

    Test Case 3

     

    Figure 24 shows Soap UI invoking the REST service with operation “getprice” to obtain a product price using the following information:

     

    REST Service : http://localhost:8080/acmeservice?operation=getprice&code=0001

     

    Azure User Password Group Membership

     

    jdoe@acmepartner.onmicrosoft.com ******** OtherGroup

     

    24-soap-ui-test.jpg

     

    Figure 24. Invoking REST Web Service with Unauthorized Group

     

    Since the user credential does not belong to one of the authorized groups, the request is rejected.

     

    Test Case 4

     

    Figure 25 shows Soap UI invoking the REST service with operation “getall” using the following information:

     

    REST Service : http://localhost:8080/acmeservice?operation=getall

     

    Azure User Password Group Membership

     

    sbrown@acmepartner.onmicrosoft.com ******** ProductCatalog

     

    25-soap-ui-test.jpg

     

    Figure 25. Invoking REST Web Service with Invalid Operation

     

    Although the request includes a valid user, the request is rejected because the operation "getall" is not supported by the REST service.

     

    Conclusion

     

    The sample policies and source code in this article have been simplified to facilitate the understanding of the integration, however in a production environment policies can be optimized and further enhanced with entitlement systems like Oracle Entitlement Server to support the centralized definition of complex application entitlements and the distributed runtime enforcement of those entitlements. Moreover, Oracle API Gateway 11gR2 brings in its latest revision 11.1.2.4.0 a new set of features, including new and enhanced OAuth 2.0 client/server services that augments the integration capabilities reviewed in this article.

     

    Resources

     

    • Visit the Oracle API Gateway online documentation center for a complete reference of all Oracle API Gateway components
    • Find out about Oracle API Gateway Policies on Oracle API Gateway Policy Developer Guide 11g Release 2 (11.1.2.4.0)
    • Find more about Installing and Upgrading API Gateway on Oracle API Gateway Installation Guide 11g Release 2 (11.1.2.4.0)
    • The JDeveloper project and sample code for the filter class described in this article can be downloaded from here.
    • The sample API Gateway policies and relative path described in this article can be downloaded from here.

     

    Sample Code

     

    • The JDeveloper project and source code for the filter class can be downloaded from here.
    • The sample API Gateway policies and relative path can be downloaded from here.

     


     

    This article has been reviewed by the relevant Oracle product team and found to be in compliance with standards and practices for the use of Oracle products.