Thursday 15 January 2009

Configuring a JDev 11g ADF Security app on standalone WLS against MS Active Directory

These notes describe my research and (finally successful) efforts to:
  • Build a standalone WebLogic Server (WLS) 10.3 server
  • Build an ADF Fusion Application using ADF Security
  • Deploy to a standalone WebLogic Server (WLS) 10.3 server
  • Configure WLS 10.3 to use MS-Active Directory (MS-AD) for user authentication
The following describes the numerous steps to get to this point, mainly for my documentation purposes, but possible useful to readers.  Usual caveat: your mileage may vary.

Build a standalone WebLogic Server (WLS) 10.13 server

Follow my instructions via my previous post: Configuring WebLogic Server Domain/Machine/Server instances with the JDeveloper 11g ADF installer

That post was inspired by:Duncan Mill's A Rough Guide To Installing and Setting up WebLogic 10.3 Production for Running ADF Applications

Configuring JDeveloper's connection to the WLS server

I'll assume it's fairly easy for readers to setup a connection in JDeveloper to your standalone WLS server.  Note that the WLS domain option must match the domain you created in the previous section (ie. ADFDomain), and the port number that of the AdminServer (ie. 7001).

Build an ADF Fusion Application

I wont bother to describe creating a basic ADF Fusion Application using ADF BC and ADF Faces RC.  The following screenshot of the Application Navigator shows the basic project files for my sample.  Note the 2 web pages: ViewClients.jspx and ViewClientNames.jspx.



Configuring your Fusion Application to run with ADF Security

A useful link for understanding this section: Frank Nimphius's ADF Security Part 2: Setup and Authentication

Via the Tools -> Configure ADF Security option invokes the ADF Security wizard.  The following screen shots show the configuration for my application.

Step 1 of 6 – Enable ADF Security page



Step 2 of 6 – Select authentication type page



Step 3 of 6 – Select identify store page



Step 4 of 6 – Enable automatic policy grants page



Step 5 of 6 – Specify authenticated welcome page



Step 6 of 6 – Summary page



Mapping MS-Active Directory roles against Application Roles

A useful link for understanding this section: Andrejus's Baranovskis's Practical ADF Security Deployment on WebLogic Server

Before completing this section you need to:

1) Think about the roles of your application – say, admin, hr, sales etc
2) Thing about how these will map to your MS-Active Directory (MS-AD) roles

We'll refer to #1 as Application Roles, and #2 as Enterprise Roles.

These could have the same names with a 1 to 1 mapping, or different names, or even a 1 to many mapping.

For purposes of this post we'll assume there is a single MS-AD enterprise role Corporate Services that we want to map against our single application role AppCorporateServices.

As per Andrejus's post above we configure Enterprise Roles to Application Role mappings in our application's jazn-data.xml file.  It is accessible via the jazn-data.xml file created by the ADF Security wizard, located in Application Navigator -> Application Resources -> Descriptors -> META-INF -> jazn-data.xml.

On opening the jazn-data.xml file, select the Overview tab at the bottom of the editor window, then the Manage Users and Roles button top right of the editor.  This invokes the Edit JPS Identity & Policy Store dialog.

We define our Enterprise Roles under the Identify Store -> jazn.com -> Roles section as follows:



We define our Application Roles under the Application Policy Store option.  You'll first need to create the store, then you define the individual Application Roles as follows:



Note that under the Member Roles tab we map the Enterprise Role against the Application Role:



Restricting access to web pages through the Application Roles

A useful link for understanding this section: Andrejus's Baranovskis's Practical ADF Security Deployment on WebLogic Server

Returning to the jazn-data.xml file's Overview tab, and selecting the Web Pages option, add the Application Role with View privileges against the ViewClientNames page:



Note that Andrejus's post goes on to tell you about configuring the weblogic.xml file.  This should have been done by default via the ADF Security wizard.

Deploying the app to a standalone WebLogic Server


Assuming you've created a connection to your standalone WLS server in JDeveloper and the WLS server is up and running, select the Application Navigator -> Application Menu (top right drop down) -> Deploy -> To -> (your connection name).

During the deployment you'll see the following dialog offering you which server to deploy to, I'll assume you've setup 2 servers, so deploy to ADFServer:



Wait for a successful deployment.

Post deployment steps

Useful links in understanding this section:
As per Steve's article, as of JDev 11g build 5188 the JDeveloper deployment tools doesn't migrate your application's security completely to WLS.  As such you need to follow these further steps:

Follow Steve's steps 1, 2 and 3 on the WLS server.

Copy your application code to a directory accessible via the standalone WLS server.

Assuming you've configured the app with a database connection and jazn-data.xml entries, follow his step 3.4.  Note that:
  • The APPWORKSPACEDIR is where you copied the application code to in the previous step
  • The APPNAME is configured in JDeveloper as your Application name (ie. TestStandaloneWLSSecurity)
  • The DEPLOYAPPNAME is configured in JDev under Application Properties -> Deployment -> Edit -> General -> Application Name, and will be the enterprise application when the application is deployed to WLS (ie. TestStandaloneWLSSecurity_application1)
On your WLS server locate the file system-jazn-data.xml.  It's typically located under (WLS_HOME)\user_projects\domains\(your domain name)\config\oracle.

Follow Steve's step 3.5.  For the record I usually only have an instance of JpsXmlEnterpriseRoleImpl to replace, not JpsXmlUserImpl.

Restart the WLS server

Testing before configuring for MS-Active Directory

At this stage before configuring WLS to use MS-Active Directory for authentication, it's worth checking that your deployed application is correctly deployed and configured to use security.  As such we'll create a temporary role and user account to test access to our webpages.

Login to the WLS console.

Navigate to Security Realms -> myrealm -> User and Groups tab -> Groups, and create a group called Corporate Services.



Create 2 users test1 and test2.  Allocate user test1 to the new Corporate Services group.

As such, because test1 has the Corporate Services enterprise role, mapped to the AppCorporateServices application role, that grants access to the ViewClientNames page, only user test1 should be able to access that page.

On attempting to access the ViewClientNames page as test2 you should get a 403 forbidden if you logged in successfully.

On attempting to access the same page as test1, it should correctly show.

On attempting to access the ViewClients page, as either authenticated user, neither have access so you should get a 403 forbidden response.

Remove the test users and test group.

Configuring MS-Active Directory on your standalone WLS

Follow my instructions via my previous post: Configuring WLS With MS Active Directory

Other useful posts to aid understanding of configuring WLS authentication providers:
Note as per the following OTN post it is important to reorder the authenticators such that the AD authenticator comes first in the list, and it's control flag is set = SUFFICIENT.

At this point you should have everything in place.

Post note

Thanks to all parties above, in particular Andrejus, Frank, Steve and Edwin, who either posted blog entries or forums posts as well as talking to me offline, your assistance in getting this together is appreciated.

Q&A with Grant Ronald - UKOUG Oracle Scene mag Winter 2008

For those readers who are members of the UKOUG, check out in your Winter 2008 (Issue 36) edition of the UKOUG Oracle Scene mag the article "Q&A with Grant Ronald".  Grant was kind enough to have a chat to me about all things Forms & JDeveloper related.

The article blurb:

When talking about Oracle Forms and JDeveloper, one Oracle personality stands out among others - long time blogger Grant Ronald from Oracle Corporation UK.  Grant has for a long time "pimped" Oracle Forms and its big brother JDeveloper at Oracle events and user group events around the world.  His popularity is shown by his blog receiving on average 2000 hits per day.  Lately, to reassure Oracle customers that Oracle intends to keep on supporting Oracle Forms and show that Forms has a future inline with JDeveloper, Grant has been responsible for the Oracle's Forms Modernization message.

... hopefully you're a member of the UKOUG and can check this article out.


Tuesday 13 January 2009

JAX-WS Provider API based endpoints in JDev 11g

This post constitutes my notes on implementing JAX-WS Provider APIs for web service endpoints in JDeveloper 11g.  Usual caveat: your mileage may vary.  In particular I may have screwed up the terminology, so please do your own reading to back up my findings.

My understanding is JDeveloper 11g has no inherit GUI facilities that support the JAX-WS Provider API, the JDev productivity features focus on the Service Endpoint Interface (SEI) JAX-WS approach, which is probably fine for 99% of the JAX-WS implementations.

As readers know the standard JAX-WS solution inheritly uses the JAXB XML binding style.  My understanding is JAXB binding is ideal in most uses of JAX-WS, particularly for small well defined XML payloads.  However for an upcoming project we're not sure of the size of our incoming payloads (we may have to use XBRL) so I wanted to explore other options over JAXB.  If you have a large and variable XML payload structure JAXB may be less than ideal thanks to the Java object structures JAXB creates, which at design time can be (dependent on your web service XML payload) large and complex to maintain, and at runtime possibly a large memory footprint.  The JAX-WS Provider API instead allows alternative binding styles such as DOM, SAX or StAX that have different advantages and disadvantages in parsing XML documents and retrieving results, which may be more suitable depending on your defined web services XML payload structures.

The following example demonstrates creating a Provider endpoint through JAX-WS in JDeveloper 11g.  The steps assume a JDeveloper 11g application "JaxWsProviderExample" based on the Generic Application template, and a single project "ProviderProject" with no project technologies initially.

1. Via the ProviderProject project properties, select Libraries and Classpath, and add the JAX-WS RI Web Services library:



2. For your web service define the XML schema with the incoming and outgoing payloads.  Create the XML schema in the project subdirectory /public_html/WEB-INF/wsdl.  In this example the XML schema is named sage.xsd:



The demonstrated XML schema in this example is nothing spectacular, just an incoming payload called Event demonstrating an embedded complexType BookingType, and a simple outgoing string payload named Response.

3. Create a WSDL for the web service and place it in the same /public_html/WEB-INF/wsdl subdirectory.

Refer to this previous blog entry for creating a WSDL step by step with JDeveloper 11g's GUI WSDL builder.  In addition check out the following viewlet from Oracle that not only shows you creating the WSDL via the JDev 11g builder, but uses drag n drop, and generates a JAX-WS SEI implementation with little hassle.

In this example the WSDL is named sageWsdl.wsdl:



Note from this WSDL example we're using SOAP v1.2.  Please, no laughing at my sophisticated service/port/porttype/message names! ;-)

4. Create our Java implementation of the Provider API.  In the following example I've created a class au.com.sagecomputing.ProviderImpl:



Note:
  • The getXMLFromSource method is not pivotal to this example (credit to Rahul Biswas for the source)
  • The @WebServiceProvider annotation maps back to port/service/namespace names in WSDL.
  • The @BindingType annotation is only necessary as we're using SOAP v1.2.  If you forget this line and you've specified SOAP v1.2 in your WSDL you'll receive a runtime exception about the wrong content-type header as follows (solution documented here):
SEVERE: Unsupported Content-Type: application/soap+xml; charset=UTF-8 Supported ones are: [text/xml]
com.sun.xml.ws.server.UnsupportedMediaException: Unsupported Content-Type: application/soap+xml; charset=UTF-8 Supported ones are: [text/xml]

  • Regardless of the number of operations defined in the WSDL, all will be passed to the chokepoint invoke method.  This means you need to interpret the incoming request using whichever binding style you've chosen (in this example javax.xml.transform.Source) and determine which operation the XML payload represents.
5. You'll note on creating the above class the @WebServiceProvider line will have a lightbulb code-insight hint in the JDeveloper Java editor.  Select the lightbulb and then select the single option to configure the web.xml file for your project.  This will result in a web.xml file as follows:

 

6. The JAX-WS RI implementation requires the file sun-jaxws.xml in your /public_html directory.  Create this file; example content based on the implementation shown in this post is as follows:



A handy reference for the sun-jaxws.xml file can be found here.

By careful to ensure the port name and url-pattern attributes match those specified in your WSDL and web.xml files respectively.

7. At the end of the above 6 steps you're application should look as follows:



8. Running the ProviderImpl via the JDeveloper web service tester tool (right click the ProviderImpl.java, select Test Web Service) shows the following results:

(Yes Gerard, I'm back to using HTTP Analyzer, not SoapUI! ;-)



Monday 12 January 2009

JDev 11g Business Component Browser new feature

Following is a little new feature in JDeveloper 11g, well, at least I think it's new as it was added to one of the Technical Preview releases, then removed, then, um, well I lost track.  So let's assume it's a new feature and leave it at that.  It wasn't in 10.1.3 if that's any help.

Anyway.........

This new feature can be found in the Business Component Browser.

As you know, from an ADF Business Component's Application Module you can create custom methods such as my distinctively complex someMethod() example below:



And within the Application Module editor's Java tab, you may expose the method to the UI layer via the Client Interface group:



Previously if you wanted to test this method you would have to create a JSF web page or similar with the appropriate bindings.

In JDeveloper 11g you can now test this by opening the Business Components Browser (right click your Application Module in the Application Navigator and select Run), then in the BCB double click your Application Module.  This reveals a neat little tester tool for calling your custom method and seeing the results:



I think I remember in one of the TP releases it was also possible to do this at the VO level in the BCB, but I can't see how to do it in 11g production.  If it's not there hopefully it'll return in a later release.

Pretty soon the BCB will replace ADF Faces RC as the GUI of choice ;-)

Monday 5 January 2009

Configuring WebLogic Server Domain/Machine/Server instances with the JDeveloper 11g ADF installer

(Post edit: An important addition to this post can be found in the following OTN forum thread)

These instructions were inspired by Duncan Mills's recent post A Rough Guide To Installing and Setting up WebLogic 10.3 Production for Running ADF Applications. This post constitutes my notes based around Duncan's post, and includes pictures. I've posted here as it may be useful to readers.

Preamble:

Readers tinkering with the latest JDeveloper 11g release will be aware that the predominate deployment platform for JDeveloper is now Oracle WebLogic Server (WLS) v10.3. For development purposes JDeveloper 11g comes with an integrated WLS 10.3 server. However for production purposes a standalone WLS is required.

The WLS architecture is somewhat different from Oracle Application Server and OC4J, with the WLS concepts of domains, machines and servers. The WLS installer can be used to set these up with minimal fuss for a new WLS instance.

The following are my notes on using the WLS installer under Windows to configure a WLS domain, machine and server for production purposes for use with JDeveloper 11g. As always readers should be aware that this post is provided as-is, will most likely be updated after the initial post as I discover issues and solutions, so be careful that your mileage may vary in using this post.

This post takes you through the following logical sections of work:
  • Running the WebLogic 10.3 installer
  • Configuring ADF to run on the new server
  • Running the post installer Configuration Wizard
  • Running the WLS console and sharing the ADF libraries with the new server
  • Starting the additional WLS server
  • Inspecting the WLS domain/server/machine setup
Running the WebLogic 10.3 installer

(This section encompasses steps 1 to 6 in Duncan's post)

Download the WLS 10.3 "package installer" from http://www.oracle.com/technology/software/products/ias/htdocs/wls_main.html

Once downloaded turn off your virus scanner, in particular McAfee as it's a Java killer.

Run the WLS exe.

The WLS installer dialog will display, skip the Welcome page by pressing next.

Choose BEA Home Directory page - select the Create a new BEA Home option, and enter an appropriate directory your happy with in the BEA Home Directory field. I've chosen "c:\oracle\WlsStandalone". Click Next:


Choose Install Type page - select Custom then next:


Choose Product and Components page - unselect the following options:

(as per Duncan's post referenced above)
  • Web 2.0 HTTP Pub-Sub Server
  • WebLogic Web Server Plugins
  • UDDI and Xquery Support
  • Server Examples
  • Workshop (including Workshop for WebLogic and Workshop Runtime Framework)


(I suspect that the WebLogic Web Server Plugins option is required for production purposes if you use WLS clustering)

JDK Selection page - select one of the JDKs. By default I pick the JRockit option:


Choose Product Installation Directories page - leave the defaults:


Install Windows Service page – as per Duncan's post he suggests not installing the node manager because of a classpath issue.


I suspect WLS users interested in clustering will want the node manager option, so best log an SR with Oracle Support to see how to configure it with a JDev production install.

Choose Shortcut Location page – leave defaults:


Installation Summary page – just press next:


The installer will now install the appropriate files onto your computer. Note if you're virus scanner is running this is where it will cause performance problems.

Once completed you'll see this page. Unselect Run Quickstart and then select the Done button.


(This section concludes step 6 in Duncan's notes)

Configuring ADF to run on the new server

(This section encompasses steps 7 to 10 in Duncan's post)

The JDev 11g installer has additional libraries that are required to run an ADF application. These must be installed in to the WLS server and are installed from the JDev 11g installer.

As per the OTN post here and here, there appears to be a catch in configuring the WLS server for running JDeveloper ADF applications. You need to install the ADF runtime libraries *and* JDeveloper on the WLS box. The following instructions will hopefully setup your server to avoid this problem.

Download the studio edition Windows JDeveloper 11g installer from http://www.oracle.com/technology/software/products/jdev/htdocs/soft11.html

Remember to turn your virus scanner off.

Run the JDeveloper 11g installation exe.

Skip the Welcome page.

Choose BEA Home Directory page – select the Use an existing BEA Home option and select the directory you previously installed WLS (e.g. c:\oracle\WlsStandalone):


Choose Products and Components page – it's important in this option to pick both the JDeveloper Studio option *and* the Application Development Framework Runtime. This seems counter intuitive as it would be expected the Runtime libraries are enough, but as per the OTN posts above, it appears we need both:


For the rest of the wizard accept the defaults.

(JDK Selection page – I'm unsure at this page if we wish to pick the Sun JDK that displays by default as an option or pick the pre-installed WLS JRocket SDK (which you browse for)? I assume as WLS is already installed and configured it will use JRocket, and the choice on this screen is for the JDeveloper IDE JDK version which we probably want to leave as the default Sun JDK).

(This section concludes step 10 in Duncan's notes)

Running the post installer Configuration Wizard

(This section encompasses steps 11 to 23 in Duncan's post)

Under your Windows start menu (I'm using Vista), there should be a new program group Oracle WebLogic. Select Oracle WebLogic -> WebLogic Server 10gR3 -> Tools -> Configuration Wizard:


The Configuration Wizard should then appear with the Welcome page. Select Create a new WebLogic domain then next:


Select Domain Source page – select Generate a domain configured automatically to support the following products, and in addition select the Application Development Framework option:


Configure Administrator Username and Password page – enter a user name and password for the default WebLogic Server administrator:


Configure Server Start Mode and JDK page – as Duncan's original post, if the server is being configured for production purposes, select the Production Mode option. In addition select the JDK for the Domain to use. If you picked JRocket previously for the WLS install this should be your choice here:


Customize Environment and Services Settings page – selecting No on this page bypasses the ability to setup the WLS machines and servers which isn't the point of this post. As such select Yes to customize the environment.


Configure RDBMS Security Store Database page – I've no idea what this page does but Duncan says skip it so we will, leaving the I don't want to change anything here option selected:


Configure the Administration Server page – each WLS domain includes 1 administration server by default referred to as the AdminServer. The AdminServer's job is to configure and maintain the other server instances under WLS. While it's possible to install JDev apps into the AdminServer, it's not ideal as the AdminServer is really for administration only. As such we wish to create a separate server to install our applications.

This page allows you to configure that separate server. You can override these settings but I'll run with the default:


Note that Duncan overrides the Listen port with 81, but we'll keep 7001.

Configure Managed Servers page – here we configure the new server. You can keep the default settings, but you'll need to change the port number to something different from the AdminServer, say 7002. In my example I also rename the new server to ADFServer:


Configure Clusters page – this post assumes no clusters, so skip this page:


Configure Machines page – the machine represents the hardware that the server runs on. We create the following entries:


Assign Servers to Machines page – on this page we assign our ADFServer to the ADFMachine. I'm currently unsure if it's wise to assign the AdminServer to the same machine, or leave it as is, so I'll leave as is for the moment:


Review WebLogic Domain page – usual summary page. Ignore and press next ;-):


Create WebLogic Domain page – enter the name of the domain and accept the default directory. I'll take the domain name adf_domain, then click Create:


At this point your additional server and machine are correctly installed and configured, but not running. The following steps show you under the WLS console to check where the new domain, server and machine are located.

(This section concludes step 23 in Duncan's notes)

Running the WLS console and sharing the ADF libraries with the new server

(This section encompasses steps 24 to 32 in Duncan's post)

Within the Oracle WebLogic Windows group, you'll have the new sub group User Projects -> adf_domain with entries for starting and stopping the AdminServer. You can click the Start Admin Server for WebLogic option, or alternatively as Duncan suggests, you can run the following script via a command prompt:

<wls_home_dir>\user_projects\domains\<your domain name>\bin\startWebLogic.cmd

....where wls_home_dir is where you installed WLS (e.g. c:\oracle\WlsStandalone), and your domain name is the domain name you configured in the Create WebLogic Domain page of the Configuration Wizard (e.g. adf_domain).

If you selected the Production Mode installation option back on the Configure Server Start Mode and JDK page within the Configuration Wizard, you'll be prompted for the administrator username and password you entered on the Configure Administrator Username and Password page.

Once successfully running within the command prompt window you should see the message <Server started in RUNNING mode>. Wait until you see that message.

Login to the WebLogic AdminServer console by clicking on the Oracle WebLogic -> User Projects -> adf_domain -> Admin Server Console option under you Windows start menu:


This will launch your browser opening the console at the following URL:

http://localhost:<port>/console

....where <port> is what you configured for the AdminServer on the Configure the Administration Server page of the Configuration Wizard. The login screen again requires your WLS admin username and password:


Once logged into the console, the Domain Structure portlet on the left side of the screen shows your new domain, in my case adf_domain:


Within the Domain Structure portlet click the Deployments node. Under the Summary of Deployments page you'll see the 3 new ADF Runtime Libraries installed:


Currently the libraries are only configured for the ADFServer. Optionally we may share them with the AdminServer.

If you're running your WLS server in production mode, first select the Lock and Edit option top left of your screen. This is unnecessary if your server is in deployment mode.

For each library, select the library, followed by the Targets tab, and select the AdminServer. Press save for each.

If running under production mode, you need to press the Activate Changes button top left of the console to make the changes permanent. This steps is unnecessary if your WLS server is running in deployment mode.

(This section concludes step 32 in Duncan's notes)

Starting the additional WLS server

(This section encompasses steps 33 and 34 in Duncan's post)

To start the ADFServer, via the command line execute the following command:

<wls_home_dir>\user_projects\domains\(your domain name)\bin\startManagedWeblogic.cmd <your server name> http://localhost:<port>

....where your server name is the name of new server you created in the Configure Managed Servers page of the Configuration Wizard (e.g. ADFServer), and the port is that you configured for the AdminServer (not the new server).

Again you'll need to enter the administrator username and password, and wait for the message <Server started in RUNNING mode>.

Returning to the console, selecting the Servers node you should see the additional server running:


To shut down both the new server and the AdminServer, simply Ctrl-C them in the command prompts, they will gracefully shut down.

(This section concludes step 34 in Duncan's notes)

Inspecting the WLS domain/server/machine setup

(This section is not included in Duncan's post)

As we saw in the previous step, in the Domain Structure portlet selecting the Environment node Servers reveals the Summary of Servers page, with a status for each:


Again in the Domain Structure portlet selecting the Environment -> Machine node reveals the Summary of Machines page, listing the new machine you just created, in my case ADFMachine:


If you select the ADFMachine link, this displays the Settings for ADFMachine page. In turn select the Configuration tab followed by the Serves tab, you'll see the ADFServer is installed for the machine: