You can 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.
This chapter contains the following sections:
You can refer to the use case description, solution summary, components involved, and the linked documentation resources to propagate security identity with RESTful web services.
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.
Develop a RESTful web service and client and secure them using Oracle Web Services Manager (OWSM) SAML policy.
Oracle Fusion Middleware—includes Oracle Web Services Manager (OWSM)
Oracle JDeveloper
To complete this use case, see the following documentation resources:
Developing and Securing RESTful Web Services for Oracle WebLogic Server
"Developing and Securing RESTful Web Services" in Developing Applications with Oracle JDeveloper
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.
To implement the Propagating Security Identity with RESTful Web Services use case, you need to perform the following tasks in sequence: create, secure, and deploy a RESTful web service and a RESTful client, create a test user, and set up the Keystore Service (KSS).
Before implementing the use case, download and install product components, configure WebLogic domain, start the Administration Server, and get the access to Oracle Enterprise Manager Fusion Middleware Control and Oracle WebLogic Server Administration Console.
Before you begin, ensure that you have performed the following tasks:
To create, secure, and deploy a RESTful web service, perform the following tasks in sequence: create a RESTful web service, authenticate the user by using SecurityContext, modify the servlet name for the web project, and secure and deploy the 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.
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 "Creating 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 "OWSM Policies Supported for RESTful Web Services and Clients" 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 password 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.
After deploying a RESTful web service, you should create, secure, and deploy a RESTful client to implement the use case of propagating security identity.
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:
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:
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, "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 password.
Note that the following error is returned: Error 500--Internal Server Error.
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.
Figure 4-1 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.
You can verify the Propagating Security Identity with RESTful Web Services use case from a browser. You can test basic and advanced features of your web service by using the Web Services Test Client or Test Web Service page in Fusion Middleware Control.
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 password or testuser and password.
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.