This chapter describes how to propagate security identity with RESTful web services.
Use Case | Propagate security identity with RESTful web services. For example, if a user is trying to access a web portal via the browser and is prompted to enter credentials, then these credentials may be propagated to a back-end service that the web portal needs to access to complete the user request. |
Implementation Summary | Develop a RESTful web service and client and secure them using Oracle Web Services Manager (OWSM) SAML policy. |
Components |
|
Required Documentation | To complete this use case, see the following documentation resources:
|
This chapter contains the following sections:
This use case demonstrates the steps required to:
Create a simple HelloWorld
RESTful web service using JDeveloper.
Display the name of the authenticated user in the output message using javax.ws.rs.core.SecurityContext
.
Deploy the RESTful web service as a WAR file to WebLogic Server.
Test the HelloWorld
RESTful web service.
Build and secure a RESTful client proxy for the RESTful web service using JDeveloper.
Set up the keystore and certificates required for SAML security.
Verify the RESTful client proxy.
This use case comprises the following tasks:
Before you begin, ensure that you have performed the following tasks:
Download and install the following product components:
Oracle Fusion Middleware—includes OWSM
For more information, see "Preparing for Oracle Fusion Middleware Installation" in Planning an Installation of Oracle Fusion Middleware.
Oracle JDeveloper
This is required only for a subset of use cases in this document.
For more information about locating and downloading Oracle Fusion Middleware products, see the Oracle Fusion Middleware Download, Installation, and Configuration Readme Files on OTN.
Configure a WebLogic domain.
For the complete procedure, see "Creating a WebLogic Domain" in Creating WebLogic Domains Using the Configuration Wizard.
Start the Administration Server in the domain.
For the complete procedure, see "Starting and Stopping Servers" in Administering Server Startup and Shutdown for Oracle WebLogic Server.
Ensure that you can access the following administration tools:
Oracle Enterprise Manager Fusion Middleware Control:
http://localhost:7001/em
Oracle WebLogic Server Administration Console
http://localhost:7001/console
Perform the following tasks to create, secure and deploy a RESTful web service:
To create a simple helloworld RESTful web service using JDeveloper:
Note:
For assistance at anytime when using JDeveloper, press F1 or click Help.Start JDeveloper.
For the complete procedure, see "Next Steps After Installing Oracle JDeveloper Studio" in Installing Oracle JDeveloper.
Create an application and project using the Java Desktop Application wizard.
Invoke the Java Desktop Application wizard by selecting File > New > Application and then General > Applications > Java Desktop Application.
Define the following characteristics:
Application Name: rest-saml-idprop
Application Package Prefix: examples.wsm.helloworld
Project Name: service
Default Package: examples.wsm.helloworld
For all other values, use the defaults.
For the complete procedure, see "Creating Applications and Projects" in Developing Applications with Oracle JDeveloper.
Create a new Java class under the service
project using the Create Java Class wizard.
Invoke the Create Java Class wizard by right-clicking the service project and selecting New > Java Class.
Define the following characteristics:
Name: HelloWorldIdPropSample
Package: examples.wsm.helloworld
For all other values, use the defaults.
The HelloWorldIdPropSample.java
file is created and opened in JDeveloper.
For the complete procedure, see "How to Create a New Java Class or Interface" in Developing Applications with Oracle JDeveloper.
Add the hello()
method to the Java class, as shown in bold below.
package examples.wsm.helloworld; public class HelloWorldIdPropSample { public HelloWorldIdPropSample() { super(); } public String hello() { return "Hello"; } }
Create a RESTful service from the Java class using the Create RESTful Service from Java Class wizard.
Invoke the Create RESTful Service from Java Class wizard by right-clicking HelloWorldIdPropSample.java and selecting Create RESTful Service.
Define the following characteristics:
Platform: JAX-RS 1.x Style
Root Path: helloworld
Configure HTTP Methods: hello
Method: GET
Produces: text/plain
Path: user
For the complete procedure, see "Creating a RESTful Web Service" in Developing Applications with Oracle JDeveloper.
The code is updated as follows:
package examples.wsm.helloworld; import javax.ws.rs.GET; import javax.ws.rs.Path; import javax.ws.rs.Produces; @Path("helloworld") public class HelloWorldIdPropSample { public HelloWorldIdPropSample() { super(); } @GET @Produces("text/plain") @Path("user") public String hello() { return "Hello"; } }
The following procedure illustrates how to get the authenticated user using javax.ws.rs.core.SecurityContext
. For more information, see "Securing RESTful Web Services Using SecurityContext" in Developing and Securing RESTful Web Services for Oracle WebLogic Server.
To get the authenticated user using SecurityContext
:
Access the SecurityContext
by injecting an instance into a class field, setter method, or method parameter using the javax.ws.rs.core.Context
annotation.
Update the hello()
method, created in the previous step, to print the authenticated user name obtained using the SecurityContext
, as follows:
package examples.wsm.helloworld; import javax.ws.rs.GET; import javax.ws.rs.Path; import javax.ws.rs.Produces; import javax.ws.rs.core.SecurityContext; import javax.ws.rs.core.Context; import java.security.Principal; @Path("helloworld") public class HelloWorldIdPropSample { public HelloWorldIdPropSample() { super(); } @GET @Produces("text/plain") @Path("user") public String hello(@Context SecurityContext sc) { String user = "No user"; if (sc != null) { Principal p = sc.getUserPrincipal(); if (p != null) { user = p.getName(); } } return "Hello " + user; } }
When you created the RESTful web service using the Create RESTful Service from Java Class wizard, as described in "Task 2: Create a RESTful Web Service", JDeveloper automatically changed the project to a web project and added the web.xml
file. By default, the servlet name for the web project is jersey
.
Edit the web.xml
file located in the Web Content/WEB-INF
folder to specify a more user-friendly name, such as helloworld. For example:
<?xml version = '1.0' encoding = 'windows-1252'?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
version="3.0">
<servlet>
<servlet-name>helloworld</servlet-name>
<servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>helloworld</servlet-name>
<url-pattern>/resources/*</url-pattern>
</servlet-mapping>
</web-app>
To secure RESTful web services, you can attach one of the OWSM predefined security policies described in ”Which OWSM Policies Are Supported for RESTful Web Services?” in Securing Web Services and Managing Policies with Oracle Web Services Manager.
Secure the RESTful web service by attaching the following policy using the Policy wizard: oracle/multi_token_rest_service_policy
Invoke the Policy wizard by right-clicking on the web.xml
file and selecting Secure RESTful Application.
The security policy configuration is saved to the wsm-assembly.xml
deployment descriptor file, shown below, in the Web Content/WEB-INF
folder. If the wsm-assembly.xml
file does not exist, it will be created.
<orawsp:wsm-assembly xmlns:orawsp="http://schemas.oracle.com/ws/2006/01/policy"> <sca11:policySet xmlns:sca11="http://docs.oasis-open.org/ns/opencsa/sca/200912" name="policySet" appliesTo="REST-RESOURCE()" attachTo="SERVICE('helloworld')" orawsp:highId="1"> <wsp:PolicyReference xmlns:wsp="http://www.w3.org/ns/ws-policy" DigestAlgorithm="http://www.w3.org/ns/ws-policy/Sha1Exc" URI="oracle/multi_token_rest_service_policy" orawsp:status="enabled" orawsp:id="1"/> </sca11:policySet> </orawsp:wsm-assembly>
For the complete procedure, see "Attaching Policies to RESTful Services" in Developing Applications with Oracle JDeveloper.
Deploy the RESTful web service application as a WAR file to WebLogic Server.
To deploy the RESTful web service:
Create a deployment profile for the Web application:
Define the profile type and name using the Create Deployment Profile wizard:
Invoke the Create Deployment Profile wizard by right-clicking on the service project and selecting Deploy > New Deployment Profile.
Define the following characteristics:
- Profile Type: WAR File
- Deployment Profile Name: helloworld
Define the context root for the Web application using the Edit WAR Deployment Profile Properties wizard.
The Edit WAR Deployment Profile Properties wizard is invoked automatically when you click OK in the Create Deployment Profile wizard.
Define the following characteristics:
- Specify Java EE Web Context Root: rest-saml-idprop
Deploy the web application using the Deploy <application> wizard.
Invoke the Deploy <application> wizard by right-clicking the service application and selecting Deploy > helloworld.
Define the following characteristics:
Deployment Action: Deploy to WAR
View the WAR file in your configured project directory. For example:
c:\JDeveloper\mywork\rest-saml-idprop\service\deploy\helloworld.war
Ensure that you have started WebLogic Server to which you want to deploy the RESTful web service.
Invoke Fusion Middleware Control and deploy the WAR file.
http://localhost:7001/em
Deploy the WAR file using the Deploy Java EE Application Assistant.
Access the Deploy Java EE Application Assistant, by selecting WebLogic Domain > domainname > AdminServer in the navigation pane, selecting WebLogic Server > Deployments in the content pane, and clicking Deploy.
For more information, see "Deploying Java EE Applications" in Administering Oracle Fusion Middleware.
Test the RESTful web service application using Fusion Middleware Control.
To test the RESTful web service:
Invoke Fusion Middleware Control.
http://localhost:7001/em
View the summary page for the RESTful web service application.
In the navigation pane, expand the Application Deployments folder to expose the applications in the domain, expand the application deployment, and select the helloworld (AdminServer) application name.
In the content pane, select Application Deployment, then Web Services.
In the Web Service Details section of the page, click the RESTful Services tab and click the application name helloworld to navigate to the RESTful Service Application page.
For the complete procedure, see "Viewing the Details for a RESTful Service Application" in Administering Web Services.
Click Test RESTful Service.
The RESTful web service application WADL file is parsed automatically. By default, the GET(hello)
method is selected (since this is the only method available in the application).
Configure the test client:
On the Request tab, select OWSM Security Policies.
Select oracle/wss_http_token_client_policy in the Client Policies list.
Enter weblogic and welcome1 in the Configuration Properties Username and Password field.
Click Test Web Service.
The following information is returned on the Response tab:
Hello weblogic
For more information, see "Testing Web Services" in Administering Web Services.
Perform the following tasks to create and secure a RESTful client:
To create a simple RESTful client using JDeveloper:
Create a new web project using the Create Web Project wizard.
Invoke the Java Desktop Application wizard by selecting File > New > Project and then Web Project.
Define the following characteristics:
Location
Project Name: rest-client
Web Application
Servlet 3.0/JSP 2.2 (Java EE 6)
Web Project Profile
Java EE Web Application Name: rest-saml-idprop-client
Java EE Context Root: rest-saml-idprop-client
For all other values, use the defaults.
For the complete procedure, see "Creating Applications and Projects" in Developing Applications with Oracle JDeveloper.
Create an HTTP servlet that will serve as the RESTful client using the Create HTTP Servlet wizard.
Invoke the Create HTTP Servlet wizard by right-clicking the rest-client project and selecting New > From Gallery and then Web Tier > Servlets > HTTP Servlet.
Define the following characteristics:
Servlet Information
Class: HelloWorldServlet
Servlet Mapping
URL Pattern: /hellorestclient
For all other values, use the defaults.
The HelloWorldServlet.java
file is created within the project directory and opened automatically in JDeveloper.
For the complete procedure, see "How to Generate an HTTP Servlet" in Developing Applications with Oracle JDeveloper.
Create a RESTful client proxy using the Create RESTful Client and Proxy wizard.
Invoke the Create RESTful Client and Proxy wizard by right-clicking the rest-client project and selecting New > From Gallery and then Business Tier > Web Services > RESTful Client and Proxy.
Define the following characteristics:
Select Deployment Platform
Jersey 1.x Style
Select WADL
URL: http://localhost:7001/rest-saml-idprop/resources/application.wadl
Customize Proxy Names
Class Name: HelloWorldRestClient
Client Policy Configuration
Security Policy: oracle/http_saml20_token_bearer_client_policy
For all other values, use the defaults.
For the complete procedure, see "How to Create RESTful Web Service Clients" in Developing Applications with Oracle JDeveloper.
Modify the HelloWorldServlet
HTTP servlet to call the RESTful client, as shown in bold below:
package examples.wsm.helloworld; ... import com.sun.jersey.api.client.Client; import examples.wsm.helloworld.HelloWorldRestClient.Helloworld; ... public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { response.setContentType(CONTENT_TYPE); Client client = HelloWorldRestClient.createClient(); HelloWorldRestClient.Helloworld hello = HelloWorldRestClient.helloworld(client); String output = hello.user().getAsTextPlain(String.class); PrintWriter out = response.getWriter(); out.println("<html>"); out.println("<head><title>HelloWorldServlet</title></head>"); out.println("<body>"); out.println("<p>The servlet has received a GET. This is the reply.</p>"); out.println("<p>Output from RESTful service:" + output + "</p>"); out.println("</body></html>"); out.close(); } }
Secure the servlet web application by editing the web.xml
file for the rest-client project, located in the Web Content/WEB-INF
folder, as follows:
Under Servlets, add an entry for the HelloWorldServlet as follows:
Name: HelloWorldServlet
Type: Servlet Class
Servlet Class/JSP File: examples.wsm.helloworld.HelloWorldServlet
Under Security, configure the following values:
Login Authentication
Http Basic Authentication
Security Roles
webuser
Security Constraints: Web Resource Collection
Web Resource Name: Success
Applies to: All HTTP Methods
URL Patterns: /hellorestclient
Security Constraints: Authorization
Authorize: Enabled
Security Role: webuser
The web.xml
is updated as follows:
<?xml version = '1.0' encoding = 'windows-1252'?> <web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" version="3.0"> <servlet> <servlet-name>HelloWorldServlet</servlet-name> <servlet-class>examples.wsm.helloworld.HelloWorldServlet</servlet-class> </servlet> <security-constraint> <web-resource-collection> <web-resource-name>Success</web-resource-name> <url-pattern>/hellorestclient</url-pattern> </web-resource-collection> <auth-constraint> <role-name>webuser</role-name> </auth-constraint> </security-constraint> <login-config> <auth-method>BASIC</auth-method> </login-config> <security-role> <role-name>webuser</role-name> </security-role> </web-app>
To create a weblogic.xml
deployment descriptor:
Create a weblogic.xml
deployment descriptor using the Create WebLogic Deployment Descriptor wizard.
Invoke the Create WebLogic Deployment Descriptor wizard by right-clicking the rest-client project and selecting New > From Gallery, and then General > Deployment Descriptors > WebLogic Deployment Descriptor.
Define the following characteristics:
Select Descriptor
Descriptor: weblogic.xml
Select Version
Version: 12.1.2
The weblogic.xml
file is created in the WebContent/WEB-INF
folder and opened automatically in JDeveloper.
Under Security, configure the following values:
Run-As Role Assignments
Role Name: webuser
Principals: weblogic
The weblogic.xml
file is created, as follows:
<?xml version = '1.0' encoding = 'windows-1252'?> <weblogic-web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.oracle.com/weblogic/weblogic-web-app http://xmlns.oracle.com/weblogic/weblogic-web-app/1.5/weblogic-web-app.xsd" xmlns="http://xmlns.oracle.com/weblogic/weblogic-web-app"> <security-role-assignment> <role-name>webuser</role-name> <principal-name>weblogic</principal-name> </security-role-assignment> </weblogic-web-app>
Deploy the RESTful client application as a WAR file to WebLogic Server.
To deploy the client:
Create a deployment profile for the Web application:
Define the profile type and name using the Create Deployment Profile wizard.
Invoke the Create Deployment Profile wizard by right-clicking on the rest-client project and selecting Deploy > New Deployment Profile.
Define the following characteristics:
- Profile Type: WAR File
- Deployment Profile Name: helloworld-restclient
Define the context root for the Web application using the Edit WAR Deployment Profile Properties wizard.
The Edit WAR Deployment Profile Properties wizard is invoked automatically when you click OK in the Create Deployment Profile wizard.
Define the following characteristics:
- General: Specify Java EE Web Context Root: rest-saml-idprop-client
Deploy the web application using the Deploy <application> wizard:
Invoke the Deploy <application> wizard by right-clicking the rest-client application and selecting Deploy > helloworld-restclient.
Define the following characteristics:
Deployment Action: Deploy to WAR
View the WAR file in your configured project directory. For example:
c:\JDeveloper\mywork\rest-saml-idprop\rest-client\deploy\helloworld-restclient.war
Invoke Fusion Middleware Control and deploy the WAR file.
http://localhost:7001/em
For more information, see "Deploying Java EE Applications" in Administering Oracle Fusion Middleware.
Until the keystore service (KSS) is configured, as described in the next step, "Task 14: Set Up the Keystore Service (KSS)", access to the RESTful web service client will fail.
To access the RESTful web service client in a browser, enter the following URL in a browser to test the RESTful web service:
http://<host>:<port>/rest-saml-idprop-client/hellorestclient
Enter the WebLogic Server username and password when prompted. For example, weblogic and welcome1.
Note that the following error is returned: Error 500--Internal Server Error.
Next, set up KSS.
OWSM uses public key cryptography to sign the SAML bearer token and requires you to set up a keystore. Keys and the keystore provide the basis for configuring message protection.
KSS is a service provided by Oracle Platform Security Services (OPSS). KSS offers the following benefits over JKS:
Integrated tooling
Use Fusion Middleware Control or WLST to perform CRUD operations on KSS keys and certificates.
Internal CA for generating CA-signed keys and certificates.
Improved lifecycle management
Ability for multiple domains to share the same keystore is simplified with centralized storage (for example, database storage).
Ability to segregate keystores (for example, OWSM can have its own keystore via the concept of a "stripe".
Simplified management as passwords are not required for accessing private keys in the keystore.
To set up the KSS keystore:
Invoke Fusion Middleware Control.
http://localhost:7001/em
Create a keystore from the Keystore page.
To navigate to the Keystore page, select WebLogic Domain > Security > Keystore.
Click Create Stripe and define the following characteristics:
- Stripe Name: owsm
Select owsm in the list, and click Create Keystore and define the following characteristics:
- Keystore Name: keystore
- Protection: Policy
- Grant Permission: Disabled
For the complete procedure, see "Using the OPSS Keystore Service for Message Protection" in Securing Web Services and Managing Policies with Oracle Web Services Manager.
Generate a key-pair using the Generate Keypair dialog.
To navigate to the Generate Keypair dialog, select owsm > keystore on the Keystore page, click Manage, and click Generate Keypair.
Define the following characteristics:
Alias: orakey
Common Name: orakey
Organization Unit: us
Country: United States
RSA Key Size: 1024
For the complete procedure, see "Using the OPSS Keystore Service for Message Protection" in Securing Web Services and Managing Policies with Oracle Web Services Manager.
Import the democa
CA certificate into the owsm
stripe.
By default, the keypair is signed by the democa
CA that ships with KSS.
To view the certificate in use, select owsm > keystore on the Keystore page, click Manage, and click the orakey alias to display the Certificate Details for Alias: orakey dialog.
Validation of the certificate on the service side will fail until you import the CA into the owsm
keystore, as the OWSM Agent is unable to validate the certificate path for the signing certificate.
Export the democa
CA certificate from the castore
keystore in the system
stripe and import it into the orakey
keystore in the owsm
stripe.
To export the democa
CA certificate, select system > castore on the Keystore page, click Manage, select the democa alias, and click Export.
In the Certificate dialog, click Export Certificate to save it to a local file (or copy and paste the contents into a file of your choice).
For the complete procedure, see "Exporting a Certificate or Trusted Certificate with Fusion Middleware Control" in Securing Applications with Oracle Platform Security Services.
To import the democa
CA certificate, select owsm > keystore on the Keystore page, click Manage, and click Import.
Define the following characteristics:
- Certificate Type: Trusted Certificate
- Alias: democa
- Select a file that contains the Certificate or Certificate Chain: Enabled
Click Choose File, navigate to the exported certificate file, click Open, and click OK to import the certificate.
For the complete procedure, see "Importing a Certificate or Trusted Certificate with Fusion Middleware Control" in Securing Applications with Oracle Platform Security Services.
To create a test user:
Invoke the WebLogic Server Administration Console. For example:
http://localhost:7001/console
For the complete procedure, see "Starting the Administration Console" in Oracle WebLogic Server Administration Console Online Help.
Create a user named testuser, with the password welcome1.
For the complete procedure, see "Create users" in Oracle WebLogic Server Administration Console Online Help.
In JDeveloper, edit the weblogic.xml
file for the rest-client
project, located in the Web Content/WEB-INF
folder, to map testuser
to the webuser
role.
Under Security > Security Role Assignments, select webuser and add testuser as a valid principal.
To access the RESTful web service client in a browser, enter the following URL in a browser to test the RESTful web service:
http://<host>:<port>/rest-saml-idprop-client/hellorestclient
Enter the WebLogic Server username and password when prompted. For example, weblogic and welcome1 or testuser and welcome1.
The following message is returned in the browser:
The servlet has received a GET. This is the reply. Output from RESTful service: Hello testuser
You can test basic and advanced features of your web service using the Web Services Test Client or Test Web Service page in Fusion Middleware Control. For more information, see "Testing Web Services" in Administering Web Services.