(attached - NetIdentity-312.zip)

Introduction

The ability to single sign on (SSO) to NetIdentity aware Web applications was available with Novell's iChain product. Novell Access Manager, the successor to the iChain product, does not include any NetIdentity authentication profile or class. The attached jar file offers the ability to SSO to Access Manager from NetIdentity enabled workstations. This document describes the requirements and configuration steps required to get NetIdentity SSO to Access Manager, and describes the NetIdentity protocol exchange during authentication.

NetIdentity Overview

For NetIdentity to work with Novell Access Manager, the assumption is that you have an Access Gateway proxy service with a protected resource that is using a NetIdentity enabled contract. A workstation with the NetIdentity client needs to access a Web server through this NetIdentity enabled protected resource. When this happens, the Access Gateway generates a Liberty authentication request that includes the NetIdentity contract type, and redirects the browser to authenticate to the Novell Identity (IDP) server.

The browser sends a GET request to the NIDP server, which does not include a valid session cookie because the workstation is not yet authenticated to the Novell IDP server. Because the workstation has NetIdentity installed, the GET request includes a header with the value NovINet: v1.2.

When the IDP server receives the GET, replies with a 401 Unauthorized packet. This packet includes NetIdentity specific information such as NetIdentity Realm name and other information used by the NetIdentity protocol. When the NetIdentity client receives this information, if Strict Trust is enabled (default), NetIdentity verifies that the server and Certificate Authority (CA) are trusted (according to the list of trusted authorities in Internet Explorer). If the server and CA are trusted, NetIdentity checks its existing credential store (i.e. “wallet”) to see if authentication credentials already exist for that Realm name.

If they do exist, they are sent back to the IDP server in attempt to authenticate. If the wallet credentials do not exist for that realm name, and the NetIdentity registry setting called Try Local Credentials is enabled, the user's desktop login credentials are sent. If no entry exists in the wallet for this realm and Try Local Credentials is disabled or fails, the NetIdentity client provides a pop-up dialog prompting the user for login credentials. The NetIdentity pop-up dialog color scheme differs from that of the browser's pop-up dialog (as shown in Figure 1 below). As soon as the users credentials are entered and applied, the credentials are added to the NetIdentity wallet for future consumption.

Figure 1: NetIdentity pop up window

Click to view.

Access Manager NetIdentity Configuration:

# Configuration requirements

• Need to have Access Manager Support Pack 3 minimum installed
• Must copy the attached NetIdentity.jar into a classpath we are looking at (/opt/novell/nids/lib/webapp/WEB-INF/lib) on the IDP server(s)
• Must have NetIdentity client installed on workstation

# Configuration steps

1. Define a new NetIdentity custom class by going to the Administration Console and selecting the Access Manager –> Identity Servers –> Local (tab) –> Classes link as shown below

Figure 2: Creating a new authentication class

Click to view.

• Select the option 'Add new Class' and add the following parameters
  • Assign name (i.e. “Secure Name/Password – Form / NetIdentity”) - this is a logical name that will only be used to display the contract in the Administration Console UI
• Java class - “Other”
• Java class path - “com.novell.nidp.authentication.local.netidentity.ProtectedPasswordClass” in the case where SSL communications exists between the browser and IDP server.

The Administrator has the ability to specify the following class paths - BasicClass, PasswordClass (in the case of HTTP protocol between browser and proxy), ProtectedBasicClass, and ProtectedPasswordClass (in the case of SSL between browser and proxy) with Netidentity. In each case, the classes check for the presence of the NetIdentity client, and if present call the NetIdentityClass for authentication. In the case where no NetIdentity client exists, we perform the originally named authentication. In the example setting above with the ProtectedPasswordClass, the user would get prompted for their username and password in a login form over HTTP if no NetIdentity client was identified on the workstation.

Figure 3: Adding NetIdentity authentication classpath

Click to view.

• Under Properties Tab add new property “Realm” with value of authentication domain desired. This Realm would normally match the Realm of the back end Web server application that is being proxied through the Access Gateway (usually the NDS Tree name of the NetIdentity Server). Each set of credentials stored on the NetIdentity client is tied to a Realm - when a user is requested to authenticate, that request includes the Realm so that only the credentials associated with that Realm are sent.

Figure 4: Adding NetIdentity authentication class Realm details

Click to view.

• Configure Methods and Contracts to make use of this new Class. In order to use this class on an Access Gateway protected resource, one must initially define a NetIdentity method, and then a contract using that newly created method.
  
  When defining the method, the key involves selecting the NetIdentity class just added.
  
  When defining the contract, the URI can be anything you want, but the method selected must be the NetIdentity created method

Figure 5: Creating NetIdentity specific Method.

Click to view.

Figure 6: Creating NetIdentity specific Contract

Click to view.

• Finally, the administrator must go to the Access Gateway protected resource that you want to single sign on to with NetIdentity and assign the newly created NetIdentity contract to that protected resource, just as we have done with the sales protected resource in the example below.

Figure 7: Assigning NetIdentity contract to Access Gateway protected resource

Click to view.

Once all the changes have been applied at both the IDP and Access Gateway servers, all that is required is to hit this protected resource from a workstation running the NetIdentity client.

Communication flow:

The following flow shows the HTTP requests and responses when authenticating directly to the IDP server from a workstation running the NetIdentity client.

// 1. Request from browser to IDP server login page - NetIdentity X-NovINET header included

GET /nidp/app HTTP/1.1
Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, application/x-shockwave-flash, */*
Accept-Language: en-gb
UA-CPU: x86
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1)
Host: idpcluster.lab.novell.com:8443
Connection: Keep-Alive
X-NovINet: v1.2

				// 2. Response from IDP server requesting NetIdentity credentials for LINUXLAB5_TREE realm

				HTTP/1.1 401 Unauthorized
				Set-Cookie: JSESSIONID=5845143E924D4FF3EEC1514A5ECF0E4B; Path=/nidp; Secure
				WWW-Authenticate: Novell realm="LINUXLAB5_TREE", nonce=iaKI2Gub0Q8=, guid=pWwy/tKI8tL/wuczG1pmKQ==
				Content-Length: 1590
				Date: Tue, 20 May 2008 14:25:08 GMT
				Server: Apache-Coyote/1.1

// 3. Assuming the NetIdentity credentials available on client (from the NetIdentity wallet), we send them via the Authorization header in response. If credentials not available, we submit them via the popup and save them to be used next time around.

GET /nidp/app HTTP/1.1
Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, application/x-shockwave-flash, */*
Accept-Language: en-gb
UA-CPU: x86
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1)
Host: idpcluster.lab.novell.com:8443
Connection: Keep-Alive
Authorization: Novell realm="LINUXLAB5_TREE", novellsession1=AQABAQEAAQQ=, response=MYTNlMzteJqT2e5QBrqx6TOKB8M5Joy14vIOcuG79F4xGadI8QO1  QHRmJzn77nzk7fORkgDOQ=:Dib1GZd5LL wPB4gib0oUPEySwdRPHJ2YjsYaXUxqAdBHknjca pd3 B9Ns4RklySImBY3Ny4c9q3zkupUMNspfDTtrmbRXl02RUci C0g /6UdgCTV1ZLBke45N3pjZ09uK ILfkmjG2rYDj8VtIFvATyysXt7w2cRGrJJYsvM=, hmac=Pwon7foxaiMdJ GZJIP6ET9TYQM=, nonce=qaWvOvAC zw=
Cookie: JSESSIONID=5845143E924D4FF3EEC1514A5ECF0E4B
X-NovINet: v1.2

				// 4. Response from IDP server redirecting browser back to origin URL after validating the credentials

				HTTP/1.1 302 Moved Temporarily
				Authentication-Info: Novell realm="LINUXLAB5_TREE", challenge=odWog7BIuHXlDW2A2/ZvGA==, novellsession1=AQABAQEAAQQ=, novellsession2=AQABAQ==, hmac=iWhd/Ft5Y47DQs/cSF8KCAULRPw=
				Location: https://idpcluster.lab.novell.com:8443/nidp/app
				Content-Length: 0
				Date: Tue, 20 May 2008 14:25:08 GMT
				Server: Apache-Coyote/1.1

// 5. Request from browser for the origin URL. Includes Authorization header with credentials and X-NovlNET NetIdentity headers.

GET /nidp/app HTTP/1.1
Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, application/x-shockwave-flash, */*
Accept-Language: en-gb
UA-CPU: x86
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1)
Host: idpcluster.lab.novell.com:8443
Connection: Keep-Alive
Cookie: JSESSIONID=5845143E924D4FF3EEC1514A5ECF0E4B
X-NovINet: v1.2
Authorization: Novell realm="LINUXLAB5_TREE", hmac=h1vw2pSpSVPk8O4U8ZeCQ8coGxw=, novellsession1=AQABAQEAAQQ=, novellsession2=AQABAQ==, nonce=kDZ6ohCr6b4=

				// 6. Successful response from IDP server.

				HTTP/1.1 200 OK
				Pragma: No-cache
				Cache-Control: no-cache
				Content-Type: text/html;charset=utf-8
				Content-Length: 785
				Date: Tue, 20 May 2008 14:25:08 GMT
				Server: Apache-Coyote/1.1