Oracle® Workspaces Web Services Application Developer's Guide 10g Release 1 (10.1.2.2) Part Number B28207-01 |
|
|
View PDF |
The service-to-service (S2S) authentication framework allows a trusted partner application to establish user sessions with a trusting provider application on behalf of its users. As a result, the partner application does not require the credentials of the end-user using it. Instead, the partner application itself supplies its credentials to establish a user session with the provider application.
The S2S Authentication service allows an application developed with Oracle Workspaces Web services (the partner application) to establish user sessions with Oracle Workspaces (the provider application). The partner application does not require the credentials of the end-user using it.
Follow these steps to integrate the S2S authentication framework with your partner application:
In some cases, you may not be able to use the S2S Authentication Web service. See Retrieving Authentication Cookie without S2S Authentication Service for more information.
The environment property "oracle.workspaces.ws.s2sEnabled" must be set to true. By default, this property is set to true. You may set this property in Oracle Enterprise Manager Application Server Control. Go to the Applications tier, OC4J_OCSClient system component, workspaces application, workspaces_ws Web module, and follow the link to Environment to access Oracle Workspaces environment entries.
The following steps describe how to register a partner application with the S2S authentication framework:
Create the following entry in Oracle Internet Directory:
dn: cn=MyApplicationProductName,cn=Products, cn=OracleContext
objectClass: orclContainer
objectClass: top
MyApplicationProductName is the product name (or category) of your application.
Create the following entry in Oracle Internet Directory:
dn: orclApplicationCommonName=MyAppName, cn=MyApplicationProductName,cn=Products, cn=OracleContext objectClass: orclApplicationEntity objectClass: top orclApplicationCommonName: MyAppName userpassword: ApplicationPassword
MyAppName is the name of your application. ApplicationPassword is the password to access your application.
To the MyAppName entity you have just added, find the property orcltrustedapplicationgroup
. Set the value of this property to the name of the Trusted Applications group, which should be the following:
cn=trusted applications,cn=groups,cn=oraclecontext
Find the following entry in Oracle Internet Directory:
dn: cn=Trusted Applications,cn=Groups,cn=OracleContext
To the entry that you have just found, add the following line to uniquemember (all in lower case, line breaks added for clarity):
orclapplicationcommonname=myappname, cn=myapplicationproductname,cn=products,cn=oraclecontext
Use Oracle Directory Manager or the command-line tools provided by Oracle Internet Directory to add and modify entries in Oracle Internet Directory. For more information about these tools, see Chapter 4, "Directory Administration Tools" in Oracle Internet Directory Administrator's Guide.
Your SOAP client must support HTTP digest authentication in order to use the S2S Authentication service. See Retrieving Authentication Cookie without S2S Authentication Service if you are using a client that does not support digest authentication such as Apache Axis.
If your SOAP client supports digest authentication, follow these steps to invoke the S2S Authentication service:
Obtain the S2SAuthenticationService.
Indicate the client's willingness to participate in a session by calling the method setMaintainSession(true).
Set the digest authentication HTTP headers that identify the partner service.
Set the Oracle-specific header ORA_S2S_PROXY_USER to the value of a nickname of an Oracle Collaboration Suite user. The S2S authentication framework will use this user to authenticate the partner application.
Invoke the login() method to authenticate the user.
Some Web services clients do not allow access to the underlying HTTP transport mechanism and thus prevent you from setting any HTTP headers. These clients are thus incapable of using the S2S Authentication service.
Oracle Workspaces Web services provides you with S2SAuthenticationServlet, a servlet from which an application can retrieve an authentication cookie without the credentials of an end-user. This cookie may then be used to invoke any other service from Oracle Workspaces Web services in the same way that the cookie retrieved from Authentication services is used.
The following code demonstrates how to use the S2SAuthenticationServlet. It calls the method getSessionCookes(), which takes the following parameters:
The nickname of the Oracle Collaboration Suite user with which the S2S authentication framework will authenticate the partner application
The distinguished name of the partner application, which has been registered in Oracle Internet Directory
The partner application's password, which also has been registered in Oracle Internet Directory
The realm of the partner application
The URL from which the S2SAuthenticationServlet is deployed
If you wish to use this code as-is, make sure that you have registered the string specified by the variable appName
with Oracle Internet Directory as described previously.
This sample requires the HTTPClient library as well as the JavaMail API mail.jar in your classpath.
See Also: For more information about the HTTPClient package, see the HTTPClient API Reference Javadoc in the Oracle Application Server Documentation Library.For more information about JavaMail, visit |
Example 4-1 S2SClientSample.java
package oracle.sample.workspaces.ws; import HTTPClient.Cookie; import HTTPClient.CookieModule; import HTTPClient.HTTPConnection; import HTTPClient.HTTPResponse; import HTTPClient.ModuleException; import HTTPClient.NVPair; import HTTPClient.ProtocolNotSuppException; import java.io.IOException; import java.io.UnsupportedEncodingException; import java.net.MalformedURLException; import java.net.URL; import javax.mail.internet.MimeUtility; import oracle.workspaces.ws.exceptions.CwWSException; public class S2SClientSample { public static String getSessionCookies( String szUsername, String szApplicationName, String szApplicationPassword, String szApplicationRealm, URL szApplicationURL) throws CwWSException { // Clear the default CookiePolicyHandler // so that it accepts all cookies CookieModule.setCookiePolicyHandler(null); // The application dn should be in lower case szApplicationName = szApplicationName.toLowerCase(); int status = 0; Cookie[] cookies = null; String cookieValues = ""; Object context = new Object(); try { try { // Get a HTTP connection for this context System.out.println("Connecting.."); HTTPConnection connection = new HTTPConnection(szApplicationURL); connection.setContext(context); connection.setAllowUserInteraction(false); // Set the digest authorization information System.out.println("Adding Digest Auth.."); connection.addDigestAuthorization( szApplicationRealm, szApplicationName, szApplicationPassword); // Mime encode the username System.out.println("Encoding username..:" + szUsername); String encodedUsername = MimeUtility.encodeWord(szUsername); // Set the ORA_S2S_PROXY_USER header NVPair[] headers = new NVPair[] { new NVPair("ORA_S2S_PROXY_USER", encodedUsername) }; // Send a request to the S2S servlet System.out.println("Retrieving response..."); HTTPResponse s2sResponse = connection.Get( szApplicationURL.getFile(), (NVPair[])null, headers); // Get the request status and cookies status = s2sResponse.getStatusCode(); System.out.println("Status from response: " + status); System.out.println("Reason line from response: " + s2sResponse.getReasonLine()); // Close out the sockets s2sResponse.getInputStream().close(); connection.stop(); } catch(UnsupportedEncodingException uee) { System.out.println("UnsupportedEncodingException caught: " + uee.toString()); CwWSException tdex = new CwWSException(); tdex.setErrorMessage(uee.getLocalizedMessage()); throw tdex; } catch(ProtocolNotSuppException pnse) { System.out.println("ProtocolNotSuppException caught: " + pnse.toString()); CwWSException tdex = new CwWSException(); tdex.setErrorMessage(pnse.getLocalizedMessage()); throw tdex; } catch(IOException ioe) { System.out.println("IOException caught: " + ioe.toString()); CwWSException tdex = new CwWSException(); tdex.setErrorMessage(ioe.getLocalizedMessage()); throw tdex; } catch(ModuleException me) { System.out.println("ModuleException caught: " + me.toString()); CwWSException tdex = new CwWSException(); tdex.setErrorMessage(me.getLocalizedMessage()); throw tdex; } // If the request succeeded then get the cookie values if (status == 200) { System.out.println("Cookies from context: " + cookies == null); cookies = CookieModule.listAllCookies(context); for(int i = 0 ; (cookies!=null) && (i<cookies.length) ; i++) { String value = cookies[i].getName() + "=" + cookies[i].getValue(); if (i == 0) { cookieValues = value; } else { cookieValues = cookieValues + "; " + value; } } } // else throw an exception else { CwWSException tdex = new CwWSException(); tdex.setErrorMessage("Response status returned was :" + status); throw tdex; } } finally { CookieModule.discardAllCookies(context) ; } return cookieValues; } public static void main(String[] args) { // Provide the application distinguished name that you // have registered in Oracle Internet Directory String appName = "orclApplicationCommonName=MyAppName," + "cn=MyApplicationProductName," + "cn=Products,cn=OracleContext"; // Provide the application password attribute. This is the value of // userpassword of the application in Oracle Internet Directory. String appPwd = "welcome1"; // Supply the URL where the S2SAuthenticationServlet is // deployed String appURL = "http://www.example.com:7777" + "/ocw/s2s/S2SAuthenticationServlet"; // Provide the user nickname on behalf of whom the caller application // is proxying. The user should be a valid Oracle Collaboration // Suite user. // The user orcladmin is used in this example String sessionCookies = ""; try { // Call the getSessionCookies method in this application sessionCookies = getSessionCookies("orcladmin", appName, appPwd, "", new URL(appURL)); } catch (MalformedURLException mue) { System.out.println("MalformedURLException caught: " + mue.toString()); } catch(CwWSException cwwse) { System.out.println("CwWSException caught: " + cwwse.getMessage()); } // Use the session cookies that you have retrieved for // future calls to Oracle Workspaces Web serivces System.out.println("Session cookies:"); System.out.println(sessionCookies); } }