6 Understanding Service To Service Authentication

The Service to Service (S2S) authentication framework provides a means for a trusted partner application to establish user sessions with a trusting provider application on behalf of its users, without having to supply any credentials for the users individually. The trusting partner application is any application (registered or configured with Oracle Internet Directory) that is capable of establishing a client SOAP over HTTP Web Service connection with authentication headers.

Registering Partner Applications with Oracle Internet Directory

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=OracleContextobjectClass: orclApplicationEntityobjectClass: toporclApplicationCommonName: MyAppNameuserpassword: 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 proper 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
```
Only application entities listed in uniquemember are allowed to authenticate using S2S. To complete the authentication, the application entity must have the member orcltrustedapplicationgroup in its Oracle Internet Directory entry containing the location of the trusted applications group. The password in the application entity entry will be used to authenticate.

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.

Setting Oracle-Specific Headers

On an HTTP response object, 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.Remember to set any other headers required by the HTTP authentication method that you are using. Oracle HTTP Server provides the HTTPClient package with which you can set this header. For more information about this package, see the HTTPClient API Reference Javadoc.

Logging in with S2S Authentication Service

Call the login() method of S2SAuthentication Service. The following code extract demonstrates how to do this:

Example 6-1 Logging In

   // Initialize the service locator for the S2SAuthentication service.   // The service locator contains the Web service endpoint URL   // in the form of   // http://<midtier instance name>:<port>/   // ocw/services/S2SAuthenticationService    S2SAuthenticationServiceServiceLocator s2sassl =                  new S2SAuthenticationServiceServiceLocator();

   // Retrieve a reference to the Web service's remote interface   // from the service locator
                   S2SAuthenticationService s2sas = s2sassl.getS2SAuthenticationService();

   // Indicate the client's willingness to participate in the session.
   // Unless it is set to true, the server assumes that client is not
   // participating in the session.
  
  // As HTTP is stateless, each Web service invocation will be
  // different and the user's state will not be
  // maintained across different Web service invocations.
  ((S2SAuthenticationServiceSoapBindingStub)s2sas).
                         setMaintainSession(true);
  // Invoke the login method to authenticate the user.
  // User nickname and password are sent as plain text.
   s2sas.login();

Retrieve the authentication cookie from the service as follows:

String cookie = (String)((S2SAuthenticationServiceSoapBindingStub)as)._getCall().getMessageContext().getProperty(HTTPConstants.HEADER_COOKIE);

Your partner application may now invoke any Oracle Discussions Web Service (with the authentication cookie) until the user session expires or the logout() method of S2S Authentication Service is called.

Using S2SAuthenticationServiceClient

A number of Web Service clients provide no published means to access the underlying HTTP transport to allow setting of the HTTP headers and so forth. Therefore, these clients are incapable of invoking the S2S Authentication Service directly by setting PROXY HEADER into the request. As a workaround, Oracle ships a S2S servlet that can be accessed through a regular HTTP client library, such as HttpClient. The Web Services client can invoke S2SAuthenticationServletClient, which can be configured to connect to the S2SServlet and obtain the cookie. For further Web Services, the Web Services client can then use the session cookie returned through authentication to the S2SServlet.

S2SAuthenticationServiceClient connects to the servlet on a HTTP connection. In the following sample code, the code in bold is to be replaced with appropriate text according to the environment on which the program is being tested:

import java.net.URL;
import oracle.discussions.ws.client.S2SAuthenticationServiceClient;

public class S2STest
{
  public static void main(String args[]) throws Exception
  {
     try
     {
        //Retrieve the caller application distinguished name from Oracle Internet
        //Directory
         String appName = "orclApplicationCommonName = om4c.stacx01.us.oracle.com,
                   cn=MidtierInstances,cn=CollaborativeWorkspaces,cn=Products,
                                                   cn=OracleContext";
        //appName should be in lowercase
         appName = appName.toLowercase();
         System.out.println("Using the distinguished name:"+appName);
         String appPwd = "I886TG5UVFjP";
        //Provide the relevant application server URL on whicn the Authentication
        //Service is deployed
         String appURL = 
               "http://host:port/discussions/ws/S2SAuthenticationServlet";
        //Provide the user nickname, on behalf of whom the caller application
        //proxies. The user should be a valid Oracle Collaboration Suite user.
        //td_superuser is a sample user nickname.
         String userNickname = "td_superuser";
        //Invoke the init method on the Client program, to set the cookie
        // handling mechanism
              S2SAuthenticationServiceClient.init();
             //Invoke the method to connect to the http endpoint servlet and
             //retrieve the cookies
             String cookie = S2SAuthenticationServiceClient.getSessionCookies("td_
                              superuser",appName,appPwd,"",new URL(appURL));
             System.out.println("Got cookies :" + cookies);
           }
          catch
          {
             System.out.println("Error Message:"+tdex.getMessage());
           }
      }
}

To locate the Oracle Internet Directory node from which the appName and appPwd are to be taken, select Entry Management, Oracle Context, Products, Collaborative Workspaces, MidtierInstances. The appName should be taken from the first node in the Midtier Instances tab. The appPwd should be picked from the node (orclResourceName = OIDProperties), that is, beneath the first node. The realm is an empty string.

Note:

Ensure that Axis related jars and javax mail.jar are in the classpath for executing the client.