Securing Applications With Identity Services, Part 1: Authentication

Print-friendly Version

The recent rapid advancements and adoption of Web services, service-oriented architecture (SOA), and Representational State Transfer (REST) architecture within enterprises have left the industry wanting more. Organizations and developers, such as those who focus on Web 2.0, are demanding interface support from identity and access management software. The Open Web SSO Project, called OpenSSO for short, answers those demands.

Through an example of a client application built with the NetBeans IDE and deployed on GlassFish Application Server, this article, Part 1 of a series, shows you how to configure OpenSSO so as to authenticate—by means of identity services—users who access protected resources.

Note: The procedures described in this article also apply to applications built with IDEs like Eclipse and deployed on servlet containers like Tomcat.

See also:
Part 2: Authorization
Part 3: User Attributes

OpenSSO contains client interfaces for authentication, authorization, session and identity management, and auditing (logging) in the Java, C, and C++ languages with proprietary XML and Simple Object Access Protocol (SOAP) over HTTP or HTTPS. Even though those interfaces are used by Policy Agents within the Web and the Java platform, Enterprise Edition (Java EE platform) and by custom applications, developing applications with the interfaces is labor-intensive. For example, to communicate with OpenSSO, you must correctly configure the client libraries for the Java, C, and C++ languages. Additionally, the interfaces cause dependencies on OpenSSO—an unacceptable scenario for developers.

As alternatives to vendor lock-in, open standards based on Web services include the following:

• Liberty Alliance Project and Security Assertion Markup Language (SAML) — For authentication and single-sign-on (SSO)
  
  
• XML Access Control Markup Language (XACML) — For authorization
  
  
• Service Provisioning Markup Language (SPML) — For identity management

However, many developers consider those standards to be overcomplex and appropriate only for achieving interoperability with partners and vendors. On the developers' wish list are simple interfaces for efficient development. Those offered by identity services in OpenSSO fulfill that wish with the following security-related capabilities:

• Authentication and Single Sign-on — Verification of user credentials
  
  
• Authorization — Permission for authenticated users to access secured resources
  
  
• Provisioning — Creation, deletion, search, and editing
  
  
• Log — Ability to audit and record operations

The interfaces enable Web services in two styles:

• The SOAP or Web Services Description Language (WSDL) style, which the SOA-business intelligence community prefers
  
  
• The REST style, which the Web 2.0 community prefers

Both styles are simple and robust. For example, WSDL defines all the input arguments and return values. You can consume Web services by simply pointing an IDE to the services and enabling the IDE to generate the stub code that wraps function calls to the services.

OpenSSO supports IDEs such as Eclipse, NetBeans, and Visual Studio. Recall that the example in this article is a client application built with the NetBeans IDE.

Figure 1 illustrates the basic architecture of identity services.

Figure 1: Basic Architecture of Identity Services

Here is the process:

1. The user interacts with the presentation logic of the application, for example, calendar, human resources applications, or banking.
   
   
2. The application authenticates, authorizes, audits, and finally creates personalized services for the user by calling either the SOAP/WSDL or REST identity services, as provided by OpenSSO.
   
   
3. OpenSSO calls the identity repository for authentication and obtains the user profile, the policy configuration (for authorization), and the audit repository (for log requests).

First, assemble the needed software and then configure OpenSSO.

Downloading the Software
Download the following software:

• NetBeans IDE 6.0 — Download the Web and Java EE bundle. Included are GlassFish, which is the open-source project for Sun Java System Application Server 9.1 (henceforth, Application Server), and Apache Tomcat.
  
  If you select the default option, Application Server is installed as follows:
  
  
  • On the Solaris Operating System and Linux: $HOME/glassfish-v2-b58g
  • On Windows: C:\Program Files\glassfish-v2-b58g
  
  The rest of this article refers to this default location as App_Server_install_dir.
  
  Note the following regarding Application Server:
  
  After installation, to start Application Server, type:
  App_Server_install_dir/bin/asadmin start-domain domain1
  
  To stop Application Server, type:
  App_Server_install_dir/bin/asadmin stop-domain domain1
  
  Once Application Server is up and running, you can log in to its Administration Console at http://localhost:4848 by entering the default credentials: admin as the user name and adminadmin as the password.
  
  
• OpenSSO — Download the stable build of opensso.zip. Then do the following:

1. Unzip opensso.zip and extract the opensso.war file in the deployable_war directory.
   
   
2. Deploy opensso.war in Application Server:
   
   
   1. Log in to the Application Server Administration Console at http://localhost:4848.
      
      
   2. Under Common Tasks on the right pane, click Deploy Web Application (.war).
      
      The Deploy Enterprise Applications/Modules pane is displayed on the left.
      
      
   3. Choose Web Application (.war) from the Type pull-down menu. Under Location, select "Packaged file to be uploaded to the server" and fill in the text field with the location of the opensso.war file. Click OK. See Figure 2.

Figure 2: Deploying the WAR File

Configuring OpenSSO
Now configure OpenSSO:

1. Go to the Configuration page at http://localhost:8080/opensso.
   
   Alternatively, click Launch under Deployed Web Applications in the Application Server Administration Console.
   
   The Configurator page is displayed.
   
   
2. Follow the prompts to configure OpenSSO: Select the default options and Embedded DS as the identity store.

The login page for the Access Manager Administration Console is displayed. Do the following:

1. Log in with amadmin as the user name and with the password you just specified in the Configurator page.
   
   
2. Create a couple of users, for example, jsmith and jondoe, and a group called adminGroup for the exercises that follow. Assign that group to a user.
   
   It is recommended that you create a normal policy that enables access to sample resources such as http://localhost:8080/private for adminGroup. For details on the procedures, see Chapter 5, Managing Policies and Chapter 6, Managing Subjects in the Access Manager Administration Guide.

You're now ready to work with identity services, accessible through either of these two interfaces:

• SOAP with WSDL
  http://localhost:8080/opensso/identityservices/IdentityServices
http://localhost:8080/opensso/identityservices?WSDL
  
  
• REST
  http://localhost:8080/opensso/identity
  
  The following table lists the URLs for the REST operations and their parameters.
  
  

  REST Operation	URL	Parameters	Response
  Authentication	http://localhost:8080/ opensso/identity/authenticate	username password uri1	subjectid
  Token validation	http://localhost:8080/ opensso/identity/isTokenValid	tokenid	boolean
  Logout	http://localhost:8080/ opensso/identity/logout	subjectid	void
  Authorization	http://localhost:8080/ opensso/identity/authorize	uri action subjectid	boolean
  Log	http://localhost:8080/ opensso/identity/log	appid subjectid logname message1	void
  Search	http://localhost:8080/ opensso/identity/search	filter attributes_names1 attribute_values_attributename1	identitydetails
  Attributes	http://localhost:8080/ opensso/identity/attributes	attributes_names1 subjectid	userdetails
  Read	http://localhost:8080/ opensso/identity/read	name attributes_names1 admin	identitydetails
  Creation	http://localhost:8080/ opensso/identity/create	identity_name identity_attribute_names identity_attribute_values_attributename admin	void
  Update	http://localhost:8080/ opensso/identity/update	identity_name identity_attribute_names identity_attribute_values_attributename admin	void
  Deletion	http://localhost:8080/ opensso/identity/delete	identity_name admin	void

   
  ¹ Optional parameter

Importing the WSDL
First, create in the NetBeans IDE a Web application project called IdSvcsClient. To use the Web-service interface, the IDE must obtain the WSDL of the identity services and generate the client stubs. Follow these steps:

Note: You need not perform these steps for the REST interfaces.

1. Right-click IdSvcsClient and choose New > Web Service Client from the context menu. See Figure 3.
   
   

   Figure 3: Creating a Web Service

    
   
   The New Web Service Client wizard is displayed.
   
   
2. Under WSDL and Client Location, select WSDL URL and type the URL http://localhost:8080/opensso/identityservices?wsdl in its text field.
   
   
3. Type any namespace, for example, com.idsvcsclient, in the Package text field. Click Finish. See Figure 4.
   
   

   Figure 4: Importing the WSDL and Generating Client Stubs

    
   
   The NetBeans IDE imports the WSDL of the identity services and generates the client stubs. Once they are loaded, expand IdSvcsClient > Web Service References > identityservices. Further expanding the identityservices node shows the Web-service port and its operations: log, attributes, authenticate, and authorize. See Figure 5.
   
   

   Figure 5: Displaying the Identity Services Port and Its Operations

    
   

Setting Up Authentication
The authentication services include a SOAP (Web-service) interface and a REST interface for authenticating users with the user-name/password approach. You can also expand the authentication mechanism for other approaches.

Setting Up the JSP Pages
First, set up two JavaServer Pages (JSP) pages:

1. In the NetBeans IDE, edit the default index.jsp file to accept the user-name and password values and to perform a POST operation to the authenticate.jsp page, which does the authentication. Below is the code segment in question:
   
   

   <form name="authn" action="authenticate.jsp" method="POST"> Username: <input type="text" name="username" value="" size="25" /><br><br> Password: <input type="password" name="password" value="" size="25" /><br><br><br> Authenticate using Web Service (SOAP/WSDL) <input type="submit" value="WS" name="auth" /><br><br> Authenticate using REST <input type="submit" value="REST" name="auth" /><br> Enter REST URL: <input type="text" name="url" value="http://localhost:8080/opensso/identity" size="100" /> </form>

    
   Here, two options apply for the submit input type for authentication, one with WS (Web services) and the other with REST. In the case of REST, the URL that connects to the REST service defaults to the local host; you can specify another URL, if desired.
   
   Here is the full content of index.jsp.
   
   
2. Create another JSP file, authenticate.jsp, by right-clicking Web Pages in the IdSvcsClient project and then choosing New > JSP in the context menu.
   
   
3. In the dialog box, type authenticate as the JSP name.
   
   
4. Add the following code as the content for authenticate.jsp to retrieve the form parameters and obtain the user name, password, and authentication type:
   
   

   <% String username = request.getParameter("username"); String password = request.getParameter("password"); String type = request.getParameter("auth"); String ourl = request.getParameter("url"); String token = null; %>

    
   Here is the full content of authenticate.jsp.

Making Authentication Calls With SOAP
Next, make the authentication calls with SOAP from authenticate.jsp:

1. In the NetBeans IDE, double-click authenticate.jsp on the left pane to load its content into the Editor pane on the right.
   
   
2. Right-click in the Editor pane and choose Web Service Client Resources > Call Web Service Operation from the context menu, as shown in Figure 6.
   
   

   Figure 6: Calling a Web-Service Operation

    
   
   The Select Operation to Invoke dialog box is displayed.
   
   
3. Select authenticate under IdentityServicesImplPort. See Figure 7.
   
   

   Figure 7: Selecting the Authenticate Operation

    
   
   The NetBeans IDE adds the stub code to the authenticate.jsp file.
   
   Note: This step for invoking Web-service calls is important. Do not skip it and manually add the stub code; otherwise the calls will not work.

The following code segment shows the rearranged stub code to be executed when you choose WS for authentication (see the next section). This code also passes the input parameters.

<%
    try {
	if (type.equals("WS")) {
	    com.idsvcsclient.IdentityServicesImplService service =
		new com.idsvcsclient.IdentityServicesImplService();
	    com.idsvcsclient.IdentityServicesImpl port =
		service.getIdentityServicesImplPort();
	    com.idsvcsclient.Token result =
		port.authenticate(username, password, "");
	    out.println("<h2>Successful Authentication using " +
		"Web Services (SOAP/WSDL)</h2>");
	    token = result.getId();
	    out.println("Token="+ token);
	}
    } catch (Exception e) {
	try {
	    e.printStackTrace(new java.io.PrintWriter(out));
	} catch (Exception ex) {
    	    // Ignore
	}
    }
%>

Subsequently, the NetBeans IDE submits the Web-service call with the user name and password and displays the resulting token on the browser. In case of exceptions, the NetBeans IDE displays the stack trace.

Making Authentication Calls With REST
Alternatively, make the calls with REST, whose authentication service is triggered by the URI authenticate. REST expects three query parameters: username, password, and uri. Here is the code segment in question:

<%
if ((type.equals("WS")) {
... // Code from above
} else {
    url += "/authenticate";
    java.net.URL iurl = new java.net.URL(url);
    java.net.URLConnection connection = iurl.openConnection();
    connection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
    // Send POST output.
    connection.setRequestMethod("POST");
    java.io.DataOutputStream printout = new java.io.DataOutputStream(connection.getOutputStream ());
    String content = "username=" + java.net.URLEncoder.encode (username) +
	"&password=" + java.net.URLEncoder.encode (password);
    printout.writeBytes (content);
    printout.flush (); printout.close ();
    java.io.BufferedReader reader = new java.io.BufferedReader(new java.io.InputStreamReader(
	(java.io.InputStream) connection.getContent()));
    out.println("<h2>Successful Authentication using REST</h2>");
    String line;
    while ((line = reader.readLine()) != null) {
	out.println(line + "<br>");
	int index = line.indexOf("token");
	if (index != -1) {
	    token = line.substring(9);
	}
    }
}
%>

This code opens an HTTP URL connection and performs a POST operation with the user name and password before displaying the response in the browser.

The request on the wire reads as follows:

POST /opensso/authenticate HTTP/1.1
Host: localhost
User-Agent: Mozilla/4.0
Content-Length: 27
Content-Type: application/x-www-form-urlencoded

username=jsmith&password=jsmith

token.id=AQIC5wM2LY4SfcykUxffyyVGC6k9vHhe7JcyrhHbmlpVZPI=@AAJTSQACMDE=#f

Apply the response value of token.id as the subjectid parameter for the other REST operations, that is, authorize, attributes and log.

You are now ready to compile, deploy, and run IdSvcsClient.

Deploying and Running the Application
To deploy and run IdSvcsClient in the NetBeans IDE, right-click the IdSvcsClient project and choose Undeploy and Deploy from the context menu. The NetBeans IDE then compiles the necessary classes, builds the WAR file, and deploys it to Application Server. Afterward, you can access the client application at http://localhost:8080/IdSvcsClient.

Figure 8 shows the application's index page.

Figure 8: Viewing the Client Application's Index page

Typing a valid user name and password and clicking WS displays the authenticated token of the user identity, as shown in Figure 9.

Figure 9: Authenticating With SOAP/WSDL

Clicking REST displays the same token, as shown in Figure 10.

Figure 10: Authenticating With REST

You can download the example cited in this article as a NetBeans project:

1. Download the IdSvcsClient.zip file.
   
   
2. Unzip the file as the IdSvcsClient directory, which is a NetBeans project.
   
   
3. Load the project in the NetBeans IDE.

Within the IDE, the JSP pages reside under Web Pages on the left pane. In the file system, they are in the web directory.

The upcoming parts of this series will show you how to perform other tasks—authorize, profile, audit, and so forth—with identity services. Stay tuned!

• Sun Java System Access Manager
  • Main page
  • Developer home
  • Software Forum
  
  
• OpenSSO Project
  
  
• Liberty Alliance Project
  
  
• Security Assertion Markup Language (SAML)
  
  
• XML Access Control Markup Language (XACML)
  
  
• Service Provisioning Markup Language (SPML)
  
  
• Sun developer services
  • Support
  • Training and certification