Wednesday Jul 30, 2014

Exploring the OIM API Wrapper (Part 2 of 2)

This is part 2 of a 2 part series. In part 1, we discussed developing these web service wrappers and handling security for both the OIM credentials and web service endpoints. In part 2, we'll demonstrate how to invoke these web services from your BPEL Approval Workflow (and even how to store your web service user credentials in the CSF).

We wanted to pass along a suggestion to use Fault Policies around your web service calls to retry the operation in the event of network issues. We won't cover the use of Fault Policies in this series of posts, but may discuss it in a future post. For more information about Fault Handling in BPEL specifically, check out this document from Oracle Documents Online

Invoking the Web Service
Now that you have deployed your web service and protected it with an OWSM policy, you will need to configure your BPEL Approval workflow to invoke the web service. This is actually quite simple and JDeveloper does most of the work for you.

To start, we will assume you already have created a workflow (if not, see Oracle's How-To document for more information).

Once you have a new workflow, you must create a new partner link. To do this, open the bpel file for your workflow (such as ApprovalProcess.bpel) and drag the Partner Link activity from the Component Palette onto the Partner Links swim lane section of your workflow screen.

The Create Partner Link window will appear. Here you will specify the name of the Partner Link, as well as the WSDL URL. After typing in the WSDL URL, click the Parse WSDL button. You will see a prompt notifying you that there are no Partner Link Types defined in the current WSDL. Click Yes. This prompt may appear twice, so click Yes both times. You will see the Partner Link Type field has been populated. Finally, under Partner Role, choose the role listed and then click OK. You will see the new Partner Link appear in the Partner Links swim lane.



Now that you have a Partner Link defined, you must define an Invoke activity by dragging and dropping it from the Component Palette into the main swim lane. Double click the new Invoke activity and the properties window will appear.

Type in a name for the Invoke activity, and then choose a Partner Link using the Partner Link Chooser (select the one you just created). You will see a list of operations to choose from. In our case, we’ll select Disable User.

For Input and Output variables, you will have to create these by clicking the + icon, starting with the Input variable. When the Create Variable dialog box appears, click OK to accept the defaults.  Repeat this process to create the Output variable.



Finally, click OK to close the Invoke properties box. You will see a line connecting the Invoke activity you just created to the Partner Link you created previously. Make sure you save the bpel file in JDeveloper.


Now that you have defined an Invoke activity for the new Partner Link, you must use the Assign activity to assign the proper input values to the Input variable you created in the previous step. Drag and drop an Assign activity from the Component Palette onto the BPEL workflow. As with any other BPEL assignment, simply choose the source value on the left side of the Copy Rules screen, and drag to a corresponding variable element on the right side, then click OK.



Repeat this process for the Output variable, if necessary. You have now successfully configured your BPEL workflow to invoke the custom web service. In the next section, we will cover how to pass credentials to the web service using the OWSM Client Policy.

Configure OWSM Client Policy
Previously we protected the Web Service endpoint with an OWSM Policy that required a username and password be provided along with the SOAP request, so we will have to configure our Partner Link to provide these credentials when the service is invoked. This is actually quite easy in JDeveloper. You could also this do in Enterprise Manager at runtime, but it will not persist if you redeploy the BPEL Approval workflow.

In your BPEL Workflow project, open the composite.xml file. On the right under the External Service swim lane, right click on your Partner Link and click Configure WS Policies. Beside Security, click the + sign to add a Security policy.





Choose oracle/wss_username_token_client_policy and click OK. Back on the Configure SOA WS Policies screen, select the policy under Security and click the pencil icon to edit the policy settings. For the csf-key row, you can specify a csf key name under Override Value or use the default value (basic.credentials). Here you must use a CSF key that has been defined in the oracle.wsm.security CSF map. This is very important – only keys defined in oracle.wsm.security will work. In our case, we defined a custom key called owsmUserCred that contains a valid username and password. At runtime, Weblogic will retrieve this CSF credential and use it to authenticate.



Click OK, and then click OK again to close the Configure SOA WS Policies window. Save the composite.xml file, then deploy your web service to the SOA server and associate it to an OIM Approval Policy as needed.

You now have successfully configured your BPEL Approval workflow to use the custom Web Service and to pass the credentials necessary to satisfy the OWSM policy assigned to the endpoint.

Justin Hinerman is an Identity and Access Management Engineer with IDMWORKS.  As a key Oracle Partner, IDMWORKS takes a focused approach to the implementation of a Service Oriented Architecture and Identity Management-based solutions.

Thursday Jul 17, 2014

Exploring the OIM API Wrapper (Part 1 of 2) - IDMWORKS

The need for custom OIM API operations within BPEL approval workflows happens more often than one might think. While there exists a capability to embed Java code within a BPEL workflow (with the Java Embedding activity), this is far from ideal, as anyone who has tried this will understand. In fact, the Java Embedding activity is designed to provide easy access to some basic utility code, not hundreds of lines worth of functionality. Therefore, we recommend that clients deploy custom Web Service wrappers for the OIM API calls.

This is part 1 of a 2 part series. In part 1, we will discuss developing these web service wrappers and handling security for both the OIM credentials and web service endpoints. In part 2, we'll demonstrate how to invoke these web services from your BPEL Approval Workflow (and even how to store your web service user credentials in the CSF).

Development

We’re not going to dig deep into the detail of developing these web services, mostly because it is outside the scope of this post, and there are several other fine resources out there that can walk you through creating JAX-WS web services. Refer to Oracle's documentation at the Oracle JDeveloper Tutorial page for more information.

At a high level, you can create a dynamic web project in Eclipse, and then create your classes and methods however you want. For every class that contains a web service, it must be annotated with @WebService, and every method you want to expose as an operation must be annotated with @WebMethod. Note there are some limitations on input and return parameters with web services created in this way, notably collections. For example, if you wish to return a HashMap<String, String> from a web service, you can’t do it. But if you wrap the HashMap in a wrapper class, it will work fine.

For example:

public class Response() {

public HashMap<String, String> items;

HashMap<String, String> getResponse() {};

public void setResponse(HashMap<String, String> items) {};

}

@WebMethod

public Response webOperation(String input) { … }

OIM Authentication

When invoking the API calls to OIM, you will need to authenticate with a user who has certain Administrative rights within OIM, such as xelsysadm. Creating a new OIMClient instance requires the username, password, and OIM t3 URL. In this case, the Credential Store Framework is perfectly suited to store these credentials. In our case, we store the OIM credentials using a Password key type in CSF, and the OIM t3 URL using a Generic key type.



Once the credentials were in place in the CSF, we simply invoked the CSF API (reference documentation) to retrieve the credentials. Note that the OOTB JPS policy should allow access to a key stored in the OIM map by default if your application is deployed on the Weblogic server and your classpath contains the jps-api.jar file located in the $MW_HOME/oracle_common/modules/oracle.jps_11.1.1/ directory. Otherwise, you will have to define an explicit policy (in Enterprise Manager, the System Policies screen).

Configure Web Service Policy In Owsm

Obviously exposing web service without any authentication that could create and modify users, provision accounts, etc. would be a huge risk from a security standpoint. Fortunately, you can use the Oracle Web Services Manager (OWSM) to require authentication when invoking the web services. If you use JDeveloper or the Oracle Enterprise Pack for Eclipse, you can define OWSM policies locally in your IDE. You can also do this via WLST. In our case, we’ll show you how to use Enterprise Manager to define these policies after you deploy your application.

To do this, login to Enterprise Manager and navigate Weblogic Domain -> Domain Name -> Server Name (for example, IDMDomain -> AdminServer). Right click on the server and click Web Services. You will see a list of Web Services deployed on your server.


Choose the Endpoint Name you wish to protect. The Web Service Endpoint screen will appear. Choose the OWSM Policies tab, and then click Attach/Detach. On the Attach/Detatch Policies screen, select the “oracle/wss_username_token_service_policy” policy. This will enforce a username and password for authentication on the web service call. You will see the policy appear in the “Attached Policies” section of the screen at the top.


Click OK. You will be returned to the Web Service Endpoint screen and the attached policy will be listed in the OWSM Policies list.

If you click Web Services Test (or use something similar such as SoapUI), you can validate that the policy has been applied. Click to expand the Security tab, then select the OWSM Security Policies radio button, and choose oracle/wss_username_token_client_policy from the list of available client policies. Provide the users for any user in the Weblogic domain security realm (such as the weblogic user), and click Test Web Service. Depending on your implementation, you may have to provide parameters in the Input Arguments tab, but in our case if we pass no input we just get back an error. This validates the security policy enforcement.


One important point here is that if you redeploy the web services application, you must re-apply the policies using the steps above.

That covers it for Part 1, and we hope you will check back next week for Part 2 in this blog series. 

About

Oracle Identity Management is a complete and integrated next-generation identity management platform that provides breakthrough scalability; enables organizations to achieve rapid compliance with regulatory mandates; secures sensitive applications and data regardless of whether they are hosted on-premise or in a cloud; and reduces operational costs. Oracle Identity Management enables secure user access to resources anytime on any device.

Search

Archives
« May 2015
SunMonTueWedThuFriSat
     
1
2
3
4
5
6
8
9
10
11
12
13
14
15
16
17
18
20
21
22
23
24
25
26
27
28
29
30
31
      
Today