------------------------------------------------------------------------------ DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. Copyright (c) 2006 Sun Microsystems Inc. All Rights Reserved The contents of this file are subject to the terms of the Common Development and Distribution License (the License). You may not use this file except in compliance with the License. You can obtain a copy of the License at https://opensso.dev.java.net/public/CDDLv1.0.html or opensso/legal/CDDLv1.0.txt See the License for the specific language governing permission and limitations under the License. When distributing Covered Code, include this CDDL Header Notice in each file and include the License file at opensso/legal/CDDLv1.0.txt. If applicable, add the following below the CDDL Header, with the fields enclosed by brackets [] replaced by your own identifying information: "Portions Copyrighted [year] [name of copyright owner]" $Id: README.txt,v 1.4 2009/09/08 08:31:53 hubertlvg Exp $ ------------------------------------------------------------------------------ Introduction ============ This OpenSSO extension implements an OpenID provider which supports both the OpenID Authentication 1.1 and OpenID Authentication 2.0 protocols, complete with full support for OpenID Simple Registration Extension 1.0 and Attribute Exchange Extension 1.0. It uses OpenID4Java for OpenID protocols and leverages OpenSSO for Authentication and retrieving a user's profile attributes. This extension also provides an LDAP implementation to persist a user's selected attributes per Relying Party to an LDAP v3 compliant backend, this backend could be the same as the OpenSSO user data store. A user can have a unique set of values of the attributes per Relying party. By implementing a required interface, developers can plug in their own implementation to persist the user's profile to their choice of a backend, like a database. Features ======== * Standalone web application as a deployable WAR file * OpenID message object model; supports future consumer implementation * Trust management user interface * Simple Registration Extension user interface * Attribute Exchange Extension user interface * LDAP implementation for persisting user's attribute per Relying Party * On-the-fly l10n and i18n (English, French and German included) * Integration with OpenSSO through servlet implementation Contents ======== This distribution includes the following the directories and files -README: This file -build.xml ant build file -build.properties instance specific properties --src --java java source files --conf properties files for OpenSSO and Provider --link sample html to provide OpenID links --web xhtml and images and style sheets --WEB-INF deployment descriptors, faces-config --classes i18n files --lib list-of-required-external-jars.txt [This file lists all the required jar files] - Installing dependencies ======================= 1. Download and extract the Facelets [1.1.14 ] binary archive from https://facelets.dev.java.net/. Copy the following files from the extracted archive root and lib/ directory to the provider/lib directory: * jsf-facelets.jar * el-api-1.0.jar * el-impl-1.0.jar * jsf-api-1.2_04-p02.jar * myfaces-all.jar 2. Build the OpenSSO client SDK inside of the OpenSSO amserver product by invoking the "clientsdk" target in the associated Ant project. Once built, copy the amclientsdk.jar file from the built/dist directory to the provider/lib directory. 3. Download the Java Enterprise Edition 5 SDK from http://java.sun.com/javaee/downloads/index.jsp. Replace the value of the j2ee.home in build.properties file with your javaee home directory 4. Download and build openid4java from http://code.google.com/p/openid4java/. For this build we have used 0.9.5-SNAPSHOT.566. copy build/openid4java.jar to provider/lib copy the following jars from /lib/ to provider/lib * commons-codec-1.3.jar * commons-httpclient-3.0.1.jar * commons-logging-1.03.jar * nekohtml-1.9.7.jar * xercesImpl-2.8.1.jar 5. Download jdom version 1.1 binary zipped archive from http://www.jdom.org extract the archive and copy jdom.jar from the /build directory to provider/lib Building ======== The supplied ant build file will compile and build the war file with its default target. The built war "openid.war" will be located in the build directory. Before running ant replace the value of the j2ee.home in build.properties file with your javaee home directory. For easier customizations, The built war does not include any of the property files located in the src/conf folder. Configuration ============= The WAR file does NOT contain the required configuration properties files for both the provider itself and the OpenSSO client SDK library. Prior to deployment, change these files located in the src-conf/ directory to suit your configuration: 1. Edit Provider.properties file 2. If you enable attribute exchange persistence, edit the ldap.properties file to provide host,port,binding credentials, attribute to persist a user's profile, search base dn etc. The property ldap.people.return.attribute defines the attribute that will be used to store and retrieve the users profile. This attribute should be of the type "DirectoryString" and "Single valued". It does not need to be indexed. You can: (a) choose an existing unused attribute from an existing Object Class of a user's entry, (b) add it to an Object Class which is already a part of the user's entry (c) add it to a new object class and mofify each users entry to include this object class This attribute will contain an XML string representing the attributes that the user selects to persist per relying party For example if you are creating a new attribute, you can add the following entry to the user99.ldif. attributeTypes: ( openid-attributes-oid NAME 'openid-attributes' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE X-ORIGIN 'user defined') You can then add it to a class like: objectClasses: ( openiduser-oid NAME 'openiduser' SUP inetorgperson STRUCTURAL MAY openid-attributes X-ORIGIN 'user defined' ) 3. Copy the AMClient.properties file from the OpenSSO client SDK resources directory (products/amserver/clientsdk/resources) to the provider/resources directory (renaming it AMConfig.properties). Configure: * Location of OpenSSO server (protocol, host, port) * Cookie name for OpenSSO session identifiers * Security credentials to access OpenSSO services * Encryption key to encrypt data to/from OpenSSO services * Naming URL in OpenSSO server 4. Create an agent identity in OpenSSO administration console with security credentials that match those set in AMConfig.properties file. 5. Create a directory and ensure that the application server user has read access to it Copy all the modified properties files from src/conf to this directory. Add this directory to the application server's classpath. Deploying the application ========================= Deploy the openid.war file on your application server. The usual context path is /openid, though others should work fine (e.g. /provider). Note: If your application server already has JavaServer Faces installed, then you must ensure you remove all JSF-related files from your WAR file, causing only the following JAR files to remain in the lib directory: * amclientsdk.jar * commons-codec-1.3.jar * jsf-facelets.jar Linking to your identity provider ================================= The main entry point to your identity provider is provided through the /service servlet. It dispatches to internal actions and Facelets as required. So, if you deployed the provider application in /openid on example.com, then the URL for the OpenID provider service would be: * http://example.com/openid/service This is what will be set in the tag in OpenID profile pages. or tags in XRD page. For example: or or http://example.com/openid/service A sample index.html is provided in the src/link directory which provides HTML links for both OpenID 1.1 and 2.0 support. Customization ============= * The user interface of this application is highly templated, facilitating easy customization. * Instead of using LDAP for attributes persistence, you can use a relational database or file system to persist user's attributes. To do so, you need to provide a class that implements the com.sun.identity.openid.persistence.AttributePersistor interface. Also the property openid.provider.pesistence.class.name in Provider.properties must then be changed to the full name of the custom class. ------------------------------------------------------------------------------