4 Propagating Security Identity with RESTful Web Services

This chapter describes how to propagate security identity with RESTful web services.

Executive Summary

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
  • Oracle Fusion Middleware—includes Oracle Web Services Manager (OWSM)
  • Oracle JDeveloper

Required Documentation To complete this use case, see the following documentation resources:

This chapter contains the following sections:

4.1 Introduction to the Use Case

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.

4.2 Implementing the Use Case

This use case comprises the following tasks:

4.2.1 Task 1: Prerequisites

Before you begin, ensure that you have performed the following tasks:

  1. Download and install the following product components:

  2. Configure a WebLogic domain.

    For the complete procedure, see "Creating a WebLogic Domain" in Creating WebLogic Domains Using the Configuration Wizard.

  3. 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.

  4. 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
      

4.2.2 Create, Secure, and Deploy a RESTful Web Service

Perform the following tasks to create, secure and deploy a RESTful web service:

4.2.2.1 Task 2: Create 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.
  1. Start JDeveloper.

    For the complete procedure, see "Next Steps After Installing Oracle JDeveloper Studio" in Installing Oracle JDeveloper.

  2. 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.

  3. 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.

  4. 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";
        }
    }
    
  5. 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";
        }
    }
    

4.2.2.2 Task 3: Get the Authenticated User Using SecurityContext

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:

  1. 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;
        }
    }
    

4.2.2.3 Task 4: Modify the Servlet Name for the Web Project

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>

4.2.2.4 Task 5: Secure the RESTful Web Service

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.

4.2.2.5 Task 6: Deploy the RESTful Web Service

Deploy the RESTful web service application as a WAR file to WebLogic Server.

To deploy the RESTful web service:

  1. Create a deployment profile for the Web application:

    1. 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

    2. 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

  2. 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

  3. View the WAR file in your configured project directory. For example:

    c:\JDeveloper\mywork\rest-saml-idprop\service\deploy\helloworld.war
    
  4. 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
    
  5. 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.

4.2.2.6 Task 7: Test the RESTful Web Service

Test the RESTful web service application using Fusion Middleware Control.

To test the RESTful web service:

  1. Invoke Fusion Middleware Control.

    http://localhost:7001/em
    
  2. View the summary page for the RESTful web service application.

    1. 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.

    2. In the content pane, select Application Deployment, then Web Services.

    3. 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.

  3. 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).

  4. Configure the test client:

    1. On the Request tab, select OWSM Security Policies.

    2. Select oracle/wss_http_token_client_policy in the Client Policies list.

    3. Enter weblogic and welcome1 in the Configuration Properties Username and Password field.

  5. 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.

4.2.3 Create, Secure, and Deploy a RESTful Client

Perform the following tasks to create and secure a RESTful client:

4.2.3.1 Task 8: Create a RESTful Client

To create a simple RESTful client using JDeveloper:

  1. 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.

  2. 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.

  3. 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.

4.2.3.2 Task 9: Modify the HTTP Servlet to Call the RESTful Client

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();
   }
}

4.2.3.3 Task 10: Secure the Servlet Web Application

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:

  1. Under Servlets, add an entry for the HelloWorldServlet as follows:

    • Name: HelloWorldServlet

    • Type: Servlet Class

    • Servlet Class/JSP File: examples.wsm.helloworld.HelloWorldServlet

  2. 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>

4.2.3.4 Task 11: Create a weblogic.xml Deployment Descriptor

To create a weblogic.xml deployment descriptor:

  1. 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.

  2. 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>

4.2.3.5 Task 12: Deploy the RESTful Client

Deploy the RESTful client application as a WAR file to WebLogic Server.

To deploy the client:

  1. Create a deployment profile for the Web application:

    1. 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

    2. 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

  2. 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

  3. View the WAR file in your configured project directory. For example:

    c:\JDeveloper\mywork\rest-saml-idprop\rest-client\deploy\helloworld-restclient.war
    
  4. 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.

4.2.3.6 Task 13: Test Access to the RESTful Client

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.

4.2.4 Task 14: Set Up the Keystore Service (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.

Why Use KSS?

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.

Set Up KSS

To set up the KSS keystore:

  1. Invoke Fusion Middleware Control.

    http://localhost:7001/em
    
  2. Create a keystore from the Keystore page.

    To navigate to the Keystore page, select WebLogic Domain > Security > Keystore.

    1. Click Create Stripe and define the following characteristics:

      - Stripe Name: owsm

    2. 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.

  3. 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.

  4. 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.

    Figure 4-1 Certificate Details for Alias: orakey Dialog

    Surrounding text describes Figure 4-1 .

    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.

    1. 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.

    2. 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.

4.2.5 Task 15: Create a Test User

To create a test user:

  1. 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.

  2. Create a user named testuser, with the password welcome1.

    For the complete procedure, see "Create users" in Oracle WebLogic Server Administration Console Online Help.

  3. 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.

4.3 Verifying the Use Case

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.