4 Service-to-Service Authentication Service

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:

Setting Oracle Workspaces Environment Variables
Registering Partner Applications with Oracle Internet Directory
Setting Oracle-Specific and Digest Authentication HTTP Headers, and Invoking the S2S Authentication Service

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.

Setting Oracle Workspaces Environment Variables

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.

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

Setting Oracle-Specific and Digest Authentication HTTP Headers, and Invoking the S2S Authentication Service

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.

Retrieving Authentication Cookie without S2S Authentication Service

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 http://java.sun.com/products/javamail/

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