Build Mobile Apps for Oracle E-Business Suite with Oracle Mobile Platform – Part 2 Bruce Bailey Principal Mobile / Social Solutions Consultant Srikant Subramaniam Director, FMW Product Management, AppAdvantage

Jagadeesh Shetty Senior FMW Sales Consultant

Introduction to Mobile Security and REST Services 2

Table of Contents 1 WORKSHOP OVERVIEW ..................................................................................................................... 3 2 GETTING STARTED ............................................................................................................................. 5

2.1 Environment Setup ................................................................................................................ 5 3 INVESTIGATE THE LOGIN AND REST SERVICES ............................................................................ 6 4 BUILD THE SECURED REST DATA CONTROL ................................................................................. 9

4.1 Start Oracle JDeveloper 12.1.3 ............................................................................................. 9 4.2 Open the ExpensesApproval App ......................................................................................... 9 4.3 Create REST Service Data Control ..................................................................................... 13 4.4 Use our REST Data Control to Generate a Pie Chart ......................................................... 23

5 ADD AUTHENTICATION ..................................................................................................................... 32 5.1 Secure the Application with a Login Page ........................................................................... 32 5.2 Create the Login Service Connection.................................................................................. 34 5.3 Configure REST Requests for Credential Injection ............................................................. 37

6 DEPLOY AND TEST THE APPLICATION .......................................................................................... 41

Introduction to Mobile Security and REST Services 3

1 Workshop Overview Oracle Mobile Development Platform enables you to build mobile applications for smart phones and tablets, via a visual and declarative framework. The framework provides all the services needed by an enterprise grade mobile application. Using Oracle JDeveloper, developers can develop one application that can be deployed to multiple mobile device platforms (Android, iOS). Oracle Fusion Middleware provides the necessary infrastructure (via SOA Oracle Service Bus and SOA Composites) to extend business processes and services to the mobile device, thus enabling the mobile user to access enterprise applications. When coupled with Oracle Mobile Platform, the combination can enable mobile execution of business transactions on Oracle E-Business Suite (or any Oracle Application). This is the second workshop in Oracle’s Mobile Reference Architecture Series. In the first workshop we walked through the construction of a Mobile Expense Approval application for E-Business Suite. The constructed application accessed some pre-staged SOA (SOAP) services, which allowed it to fetch a list of expense reports for a given manager, select the details for a given report, and then approve or reject the report. The mobile development involved the generation of a Web Service Data Control, which allowed us to generate application screens without knowledge of the data providers themselves (in that case the SOAP services). The first workshop then used the data controls in the construction of device independent .amx screens, which are converted to HTML5 and rendered on the given device. Page navigation was defined using drag-and-drop taskflow construction. The goal of this workshop is twofold; to add security functionality to the Expense Approval application through Oracle API Gateway (OAG), and to demonstrate REST services access through Oracle Service Bus (OSB). This will be achieved as follows: 1. We will add a login screen which will send the entered user credentials to an OAG Login service 2. We will maintain the provided OAG security token in our mobile application, and send it along with

successive requests to a secured OSB REST service which provides aggregated expense report results.

The security model used here is suitable for secure mobile B2C (Business to Customer) access. The lab itself uses HTTP-based communication for simplicity, though when implementing your own secure applications you should use HTTPS to encrypt all network traffic. Software Used:

Oracle SOA Suite 12c

Oracle Service Bus 12c

Oracle E-Business Suite 12.1.2

Oracle JDeveloper 12c + Latest MAF Patch

Introduction to Mobile Security and REST Services 4

Additional information:

Fusion Middleware Best Practice Centers on Oracle Technology Network http://www.oracle.com/technetwork/topics/index-096924.html

Whitepaper: Mobility for Oracle Applications with Fusion Middleware http://www.oracle.com/us/products/middleware/middleware-for-applications/mobility-for-oracle-apps-2098581.pdf

Questions:

Bruce Bailey (bruce.bailey@oracle.com)

Introduction to Mobile Security and REST Services 5

2 Getting Started

2.1 Environment Setup 1. If you are running JDeveloper on a Linux system then edit the /etc/hosts file to update the IP address

entry for the soabpm-vm server your instructor has provided specifically for you. On some lab systems this is already pre-configured. You can test whether the hosts file is configured already by trying to ping the soabpm-vm as shown below prior to editing your windows hosts file.

Note: On Windows the host file is located in the C:\WINDOWS\system32\drivers\etc folder. E.g.,

192.168.2.151 soabpm-vm.us.oracle.com soabpm-vm

2. Once you have saved your edits of the hosts file it is a good idea to try to ping the soabpm-vm in order to ensure that you can communicate with it. On Windows do this in a cmd (command) window. On Linux use a shell. The output from the ping command should look similar to the following:

3. Disable browser proxies:

FireFox: Tools > Options > Network > Settings, select No Proxy

IE: Tools > Internet Options > Connections > LAN Settings, uncheck all boxes

Introduction to Mobile Security and REST Services 6

3 Investigate the Login and REST Services During this lab we will be accessing services residing on OAG (Oracle API Gateway) and OSB (Oracle Service Bus). The purpose of OAG is to regulate service requests coming into the enterprise in order to prevent service attacks and ensure that only legitimate requests are accepted and forwarded back to virtualized services residing on Oracle Service Bus. Hence, the typical OAG deployment is within an enterprise’s DMZ (de-militarized zone), whereas OSB is integrated directly with back-end applications and other enterprise services. Extensive exploration of OAG and OSB is beyond the scope of this workshop, though Oracle offers other workshops that focus exclusively on the technical and operational aspects of those components. For our purposes OAG hosts an Authentication service and provides secure access to a REST service that resides on Oracle Service Bus. 1. The secured REST service returns a rolled-up list of expense reports for a manager. The service can

be accessed by typing the following URL (with the sample user “WTUCKER” provided as an input parameter) into a browser. http://soabpm-vm:8081/OAGSecureAPIs/ExpensesMisc/ChartingData?manager_name=WTUCKER

TIP: These URLs are provided in a text file called Lab2-URLs.txt in the top level project directory for the hands-on lab #2, e.g., C:\HOL9304\Lab2 2. Open up a browser and input the REST service URL. Notice that when you do you are prompted for

login credentials by OAG, and that OAG’s defined security realm is called “DefaultRealm”. We will specify this security realm later on in this workshop. Click Cancel.

Introduction to Mobile Security and REST Services 7

The other OAG service is the Login service which is located here:

http://soabpm-vm:8081/auth 3. Type the URL for the Login service into your browser. You will again be prompted for credentials.

Use the following credentials to log into the service:

User Name: demouser

Password: welcome1

Click OK

Upon successful authentication OAG passes a login token back to your browser in a cookie. Your browser window should display the following:

4. Now re-enter the URL for the secured REST service into your browser.

http://soabpm-vm:8081/OAGSecureAPIs/ExpensesMisc/ChartingData?manager_name=WTUCKER

Introduction to Mobile Security and REST Services 8

5. When you enter the URL, your browser will pass your credentials back to OAG along with the HTTP request. OAG will recognize the authenticated, established session and this time will forward the request to the OSB server hosting the REST Chart Service. The OSB REST service is a virtualized service in that OSB acts as a mediator by providing whatever client endpoint type is needed by the service consumer. In this case OSB provides REST access to a SOAP service endpoint running on a SOA server, which itself is integrated with the EBS back-end. The SOA Server will then interface with EBS in order to retrieve the aggregated list of expense reports, and will return the results via SOAP to OSB. OSB then converts this SOAP response to REST and returns the data back through the secured OAG interface to your browser.

The data returned by the service should look something like the following:

Close your browser window and proceed to the next section.

Introduction to Mobile Security and REST Services 9

4 Build the Secured REST Data Control

4.1 Start Oracle JDeveloper 12.1.3 1. Start > Oracle JDeveloper Studio. Alternately, locate the JDeveloper icon on the desktop and double-

click on it.

2. In JDeveloper disable any proxy settings, via Tools > Preferences > Web Browser and Proxy > uncheck Use HTTP Proxy Server (this may already be configured)

4.2 Open the ExpensesApproval App In the previous workshop we built the Expense Approval Mobile Application which fetches a list of outstanding expense reports for a given manager, and then allows the manager to select details for a specific report. In this workshop we will add a login screen to the application as well as a screen which fetches a rolled-up list of reports from the secured rest service (using the security token obtained during the login process) and displays them in a graphical chart. If you already have JDeveloper open with the ExpenseApproval application from the previous lab (Lab1) then you can skip the rest of this section and go to 4.3 Create REST Service Data Control section. If you did not complete Lab1 or are simply interested in how to add login and secure service access to the MAF app then you need to start with the Lab1 solution in order to begin Lab2. In this case: 1. Navigate back to the Lab1 directory and unzip the ExpensesApprovalApplication-Lab1-Solution.7z file

(or alternately, if the unzipped ExpensesApprovalApplication-Lab1-Solution folder already exists then don’t bother with the unzip). Copy the ExpensesApprovalApplication-Lab1-Solution folder.

Introduction to Mobile Security and REST Services 10

2. Now go back to the Lab2 folder and paste the copy of the Lab1 solutions folder there.

3. Finally, rename the ExpensesApprovalApplication-Lab1-Solution folder to

ExpensesApprovalApplication

Introduction to Mobile Security and REST Services 11

4. From the top menu bar of JDeveloper select File > Open… and navigate to your top Level

JDeveloper project directory for the 2nd

lab, e.g., C:\HOL9304\Lab2\ExpensesApprovalApplication\ExpensesApprovalApplication.jws Select the ExpensesApprovalApplication.jws project file and click Open.

5. Since the Lab1 solution that we are starting with here was generated on a different system, we need

to update a directory path in the project so that it matches the location where you copied the lab projects on your own machine.

In the Applications navigator expand the project structure as follows: ViewController > Application Sources > mobile Double-click on the DataControls.dcx file to open it up in the editor and click on the Source tab at the bottom to get to the data control definition source.

Introduction to Mobile Security and REST Services 12

6. Locate the line referencing the RetrieveExpenseListResponse.xsd file and modify it to reflect the location of the Lab1 directory and schema file on your own system. If you are on a Mac then use the corresponding unix directory path (remove the C: windows directory designation)

SchemaLocation="file:/C:/HOL9304/Lab1/RetrieveExpenseListResponse.xsd" ensureKeyAttribute="true" 7. Now do a File > Save All to save your work

8. Expand the RetrieveExpensesList data control in the Data Controls pane on the left side of

JDeveloper to verify that the new schema location is valid. If the directory path was not modified correctly in the previous step then you will not be able to see the data control structure shown in the screenshot below.

Introduction to Mobile Security and REST Services 13

4.3 Create REST Service Data Control 1. In JDeveloper navigate to the Application hierarchy view and right-mouse click on the

ViewController. In the context menu select New > From Gallery…

Introduction to Mobile Security and REST Services 14

2. On the left hand side set the Category to Data Controls and then click on Web Service Data Control (SOAP/REST) on the right. Click OK.

Introduction to Mobile Security and REST Services 15

3. In the Create Web Service Data Control wizard do the following:

Enter ExpensesChartData in the Name: field

Select the REST radio button

4. Add a REST service Connection by clicking the green + icon.

5. In the Create REST Connection Pop-up screen enter the following data. The URL Endpoint is the

same as what we accessed via the browser earlier.

Name: OAGSecureAPIsConnection

URL Endpoint: http://soabpm-vm:8081/OAGSecureAPIs/ExpensesMisc/ChartingData?manager_name=WTUCKER

Introduction to Mobile Security and REST Services 16

6. Click the Test Connection Button. Note that since the service is secured it asks you for your credentials. Input the same credentials you used for the auth service previously

User Name: demouser

Password: welcome1

Click OK and observer that the connection test succeeds as shown below, however don’t click OK on the Create REST Connection screen just yet.

Introduction to Mobile Security and REST Services 17

7. Now go back and edit the URL Endpoint to remove the “/ChartingData?manager_name=WTUCKER” part of the URL that you used for the test. The final URL Endpoint should look like the following

http://soabpm-vm:8081/OAGSecureAPIs/ExpensesMisc

Click OK

8. Click the Next Button in the Data Control screen to move onto the next step.

Introduction to Mobile Security and REST Services 18

9. Now, on the Resource screen click the green + icon to add a resource path.

Introduction to Mobile Security and REST Services 19

10. Double-click on “/path0” in order edit the newly added resources path value. Change it to the value shown below. NOTE: Use the following Resource Path literally, e.g., DO NOT modify this to include your assigned user ID. This has the effect of parameterizing the part of the URL that we stripped off in the previous step.

Resource Paths: /ChartingData?manager_name=##managerName##

11. Now select the “GET” method checkbox and type in “chartingData” for the Method Display Name.

Click Next

Introduction to Mobile Security and REST Services 20

12. Under the Resource Methods: heading select the chartingData Resource Method that you specified

in the previous step.

13. REST services can return different typs of payloads, such as JSON or XML. This particular service

returns XML, so we need to provide a schema file describing the payload format. Click on the

magnifying glass to the right of the Response XSD: field and browse to the Response XSD file,

RetrieveChartDataResponse.xsd

e.g., C:\HOL9304\Lab2\RetrieveChartDataResponse.xsd Once you have selected the schema file click on Open

Introduction to Mobile Security and REST Services 21

14. Click Next to move to the last screen.

15. Click Finish button on the last screen to complete the generation of the data control.

Click on File > Save All or alternatively click on the icon that looks like a stack of floppy disks in order

to save all of your work.

Introduction to Mobile Security and REST Services 22

16. Navigate to connections.xml, the file where your mobile application’s service connections are

maintained. Double-click on the connections.xml file and scroll to the bottom when it is displayed in

the main editor window.

17. You should see your new OAGSecureAPIsConnection defined near the bottom of the file.

18. Save your work by going to the top menu and clicking File -> Save All or by clicking on the “stack-of-

floppy-disks” icon.

Introduction to Mobile Security and REST Services 23

4.4 Use our REST Data Control to Generate a Pie Chart 1. On the left hand side of JDeveloper click on the ‘+’ Plus sign to expand the Data Controls accordion

2. The complete list of Data Controls is now displayed. You may have to click on the blue, circular

arrows in order to refresh the display.

3. Expand the ExpensesChartData Data Control.

Introduction to Mobile Security and REST Services 24

4. Next, expand the ViewController node in the Application Navigator (upper left hand side of JDeveloper) as follows: ViewController > Web Content > ExpensesApproval. Double click on the ExpensesApproval.xml TaskFlow file. You should see the application taskflow open up in the main window as shown below. The task flow represents the state of the application that was completed at the end of the first workshop. Our next job will be to complete the ShowGraph screen with data coming from our secured REST service.

5. Double click on the ShowGraph View in the TaskFlow editor. This will bring up the ShowGraph.amx

file in the editor. To make things simple, add a blank line (<carriage return>) before the </amx:panelPage> tag as shown in the next picture. If you want, you can also drag the small vertical bar (highlighted below) to the left, about ½ way across the screen to split the editor into 2 halves.

Introduction to Mobile Security and REST Services 25

6. If you have split the editor screen you can then click on the Preview tab at the bottom of the right-

hand view in order to see a rendered view of the AMX page that you are working on.

Introduction to Mobile Security and REST Services 26

7. In this next step we will “bind” the output from our REST data control to the ShowGraph page. From the Data Control accordion view on the left, drag the P_EXP_AMOUNT_LINES_ITEM node and drop it in the blank space we created above the </amx:panelPage> amx tag. A context menu will pop-up when you release the mouse button. Select MAF Chart… from the context menu.

Introduction to Mobile Security and REST Services 27

8. Select the Pie Chart from the Component Gallery and click OK.

Introduction to Mobile Security and REST Services 28

9. For the input Value type in the name WTUCKER and click OK. This is the parameter that will be passed to the REST Service via the data control upon invocation. Recall that this was the input parameter that we used to test the REST connection we created earlier when we built the data control. Although we are hard-coding the value of WTUCKER here, in a real application we would typically fetch this from an application property that is dynamically updated when the user logs into the application.

10. For the value represented by the complete Pie select TOTAL from the Pie: drop-down menu.

Introduction to Mobile Security and REST Services 29

11. For the individual Slices: drag USER_NAME from the Available data list on the left over to the empty Slices: text input box on the right.

12. Our Pie Chart definition is complete. Click OK.

Introduction to Mobile Security and REST Services 30

13. Select Pie Data Item in the Structure panel.

Introduction to Mobile Security and REST Services 31

14. Enter #{row.USER_NAME} for the Short Desc, Label, and Slice Label Properties (you can copy and paste this from the Slice ID field)

15. A rendered view of the ShowGraph.amx page is now displayed.

Save your work either via File > Save All, or by clicking on the “stack-of-floppy-disks” icon as before.

Introduction to Mobile Security and REST Services 32

5 Add Authentication The final thing that we need to do is add the Login screen to our application and associate it with the OAG Login service that we experimented with earlier. Upon successful login the Oracle Mobile Platform will store the authentication token in a local credential store so that it can be injected into the header of successive service calls we make to our secured services after login (in our case the REST ExpensesChart service). The first step is to select the mobile feature that we want to secure. In this case we want to secure the entire ExpensesApproval taskflow.

5.1 Secure the Application with a Login Page 1. Go back to the Application Navigator and expand the META-INF node underneath Application

Sources. ViewController > Application Sources > META-INF

Introduction to Mobile Security and REST Services 33

2. Double-click on the maf-feature.xml file to open it up in the main editor window.

3. Select the ExpensesApproval feature in the top list, and then click on the Enable Security checkbox.

Save your work either via File > Save All, or by clicking on the “stack-of-floppy-disks” icon as before.

Introduction to Mobile Security and REST Services 34

5.2 Create the Login Service Connection

1. Expand the Application Resources accordion menu (below the Application Navigator). Expand the Descriptors node as follows: Descriptors > ADF META-INF and double-click on the maf-application.xml file to bring it up in the main editor window.

2. When the maf-application editor displays click on the Security tab on the left and then click on the

green + sign to create a Login Server connection

Introduction to Mobile Security and REST Services 35

3. In the Create MAF Login Connection Name Connection Screen make sure the General tab is selected and specify a of “OAGLoginService”. Click on the Authentication Server Type: dropdown menu and notice the different types of login servers that are supported such as HTTP Basic (what we are using in this lab), Mobile-Social, Oauth, and Web-SSO. Make sure you leave the type set to HTTP Basic when you are done inspecting the different values

4. Un-check the box to the left of Include basic authentication header in HTTP requests, and leave the other settings on this tab as default. Notice that the checkbox next to the Include login server cookie in REST calls remains checked. This will allow MAF to automatically inject the proper security token into calls to secured services.

Introduction to Mobile Security and REST Services 36

5. Click on the HTTP Basic tab and enter the URL to the authentication service we accessed earlier during this lab. Use the same URL for both the Login URL and Logout URL values

Login URL: http://soabpm-vm:8081/auth

Logout URL: http://soabpm-vm:8081/auth

Click the Test Connection button to make sure your Login/Logout connection URLs are correct and then click OK to complete the connection definition

Save your work as before and then continue to the next section.

Introduction to Mobile Security and REST Services 37

5.3 Configure REST Requests for Credential Injection 1. Go back under the Application Resources accordion menu and double-click on the connections.xml

file. This will pull up the connections.xml file in the main editor window. The connections file contains information about all of the connections required by our mobile application.

2. Scroll down to the bottom of the connections.xml file and you will see both our OAGSecureAPIsConnection and OAGLoginService connection. Notice that the name of the adfCredentialStoreKey property is “OAGLoginService”. This is the name of our mobile application’s credential store, a logical name our application uses to access credentials that are needed for secured service access. connections.xml …

Introduction to Mobile Security and REST Services 38

3. Now select the OAGSecureAPIsConnection name as shown and you will notice that the properties for the connection are displayed in the Properties editor. connections.xml …

4. In the Properties editor input the name “OAGLoginService” for the adfCredentialStoreKey and then

do a File > Save.

Introduction to Mobile Security and REST Services 39

5. Notice that in the connections.xml file the adfCrendentialStoreKey property has now been added to the OAGSecureAPIsConnection definition as shown next.

connections.xml …

Introduction to Mobile Security and REST Services 40

6. Now we need to go through the connections.xml file and substitute the IP address of soabpm-vm for every occurrence of “soabpm-vm” in the file. This is required because although JDeveloper was able to utilize the /etc/hosts file we configured in Section 2, once the application is deployed to a mobile device that device will not have the luxury of the hostname resolution which is available on our development system.

Go to the main menu and click on Search -> Replace in Files… Update the fields as follows:

Search Text: soabpm-vm

Replace With: < IP address for the SOA server that you used in Section 2 > Note that this address may be different than what is shown in the screenshot below.

Click on OK to perform the substitution.

7. Click the green ‘play’ button in the Replace in Files output window (below the main, editor window) to perform the string substitution throughout the application. Inspect the connections.xml file to ensure that the SOA server’s hostname is replaced as desired.

Do a Save All to save all of your work as done previously

Introduction to Mobile Security and REST Services 41

6 Deploy and Test the Application

1. Make sure the Android Emulator is running first so that you are ready to deploy the mobile application. If you already did this in the previous lab you can skip over the next few steps where we create a new Deployment Profile.

Click Application > Deploy > New Deployment Profile … from the main menu.

2. Select “MAF for Android” from the dropdown menu in the Create Deployment Profile wizard here. When JDeveloper is configured for mobile development specifying the target platform (e.g., iOS or Android) specifying an Android or iOS target is as easy as selecting the desired result in the drop-down menu here. Name the profile “MyAndroidProfile” and click OK.

Introduction to Mobile Security and REST Services 42

3. Stick with the defaults and click OK.

Introduction to Mobile Security and REST Services 43

4. Now we’re finally ready to deploy our mobile application! Go back to the main menu and choose Application > Deploy > (Substitute the name of the profile you just created here)

5. From the Deployment Action wizard click on the drop-down menu and select Deploy Application to Emulator and then click Finish. The deployment may take a while (the Google emulator is very slow).

Introduction to Mobile Security and REST Services 44

6. Once the Deployment Tab says that the deployment is completed, open up the Android Emulator window on your system. Use a “sweep” gesture with your mouse to sweep the lock off of the emulator screen. This has the effect of “unlocking” the screen lock on the device.

7. In the bottom center of the screen, click on the white circle with the 6 dots inside to bring up the applications installed into the emulator. When the applications screen comes up click on your newly deployed “ExpensesApprovalApplication”. Again, due to the emulator’s performance, it will take several minutes for the application to build and launch.

Introduction to Mobile Security and REST Services 45

8. When the application launches you should be presented with a Login screen. Try inputting an incorrect user ID and password to see what happens. Then, input your assigned userid and password to access the application (e.g., demouser / welcome1) and then click Login

9. Upon successful login you should see the expense reports listed. Click on one of the reports to go

to the Details screen.

Introduction to Mobile Security and REST Services 46

10. From the details screen click on the Graph button to navigate to the ShowGraph screen. This screen will access the secured REST service by passing the security token obtained when we logged into the application.

Congratulations – you have completed the Mobile Security Lab!