.... OpenID4Java Library - INSTALL

========================================================================

INSTALLATION AND USAGE INSTRUCTIONS

Introduction:

This document describes how to install and use the OpenID4Java library. 
For general information about the package please see the README document.


Requirements:

   - Java 1.5 JVM (or higher)

   - Ant (optional: needed for building the package and running the tests)
   - Maven (optional: alternative to Ant)
   - JUnit (optional: needed for running the tests)


Installation:

  1. Installing the package

    => To make the OpenID4Java library available to a (web) application
       the following JAR files need to be copied to the application's
       classpath:
                        - openid4java-*.jar
                        - library dependencies (see below)

    => Library dependencies:

      lib/*jar       : Required. Core OpenID4Java library dependencies.
      lib/optional/  : Optional. Libraries supporting alternative deployments.
                          - spring-*.jar        : JdbcServerAssociationStore
                          - ehcache-1.2.4.jar   : EhcacheNonceVerifier
                          - log4j-1.2.8.jar

      lib/extra/     : Extra/development libraries, not needed for deployments.
                       (JUnit tests, Jetty servlet container, SVN/Ant utilities)

      lib/xri/       : Optional. Local OpenXRI resolver dependencies.
                       Included only in the "openid4java-xri" and
                       "openid4java-full" packages. (A dependency-less
                       proxy XRI resolver is included in the standard package)

      lib/infocard/  : Optional. OpenID-Infocards/Higgins STS dependencies.
                       Included only in the "openid4java-infocard" and
                       "openid4java-full" packages.


    => Relying Party Discovery:

      Relying Parties must publish their endpoints in order for the OpenID
      Providers to be able to verify authentication requests and prevent
      proxy attacks. The Yadis protocol and realm verification mechanisms
      are used for this purpose. See the section "Discovering OpenID
      Relying Parties" of the OpenID Authentication specification for
      details.

      Example:

        <Service xmlns="xri://$xrd*($v*2.0)">
          <Type>http://specs.openid.net/auth/2.0/return_to</Type>
          <URI>http://consumer.example.com/return</URI>
        </Service>

      The RP should publish the above <Service> element at their realm URL.
      All OpenID Authentication request sent by this RP should contain
      openid.return_to values matching the http://consumer.example.com/return
      realm.

      OpenID Providers:

      Validation of openid.return_to values against Relying Party Discovery
      endpoints is enabled by default. This feature can be disabled with
      ServerManager.setEnforceRpId(false).


    => Java 1.4 compatibility

      The official OpenID4Java distribution is compiled with a Java 1.5 
      compiler. The source, however, can be compiled with Java 1.4. 
      See the "Building the package" section below.

  2. OPTIONAL: Configuring logging

    OpenID4Java uses Apache's commons-logging API. This allows the
    application developers to choose (or change) their preferred logging
    implementations, without the need to modify or recompile the library.

    http://commons.apache.org/logging/guide.html#Configuration

    => Log4J configuration

      Log4J v1.2 is used as the logging implementation for the sample
      projects included with the OpenID4Java library. Commons-logging
      uses Log4J as the primary default and automatically detects if
      Log4J is available when discoverying available logging 
      implementations.

      A typical way to configure Log4J is using a log4j.properties file
      in the classpath which should contain the following (adjust log
      levels as desired):

        log4j.rootLogger=INFO, A1
        log4j.logger.org.openid4java=DEBUG, A1
        log4j.appender.A1=org.apache.log4j.ConsoleAppender
        log4j.appender.A1.layout=org.apache.log4j.PatternLayout

      http://logging.apache.org/log4j/1.2/


  3. OPTIONAL: Enabling 256bit cryptographic support

    => Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy

      Download and install (under JAVA_HOME/jre/lib/security) the JCE
      unlimited strength policy files, usually distributed along with JVMs
      (but not included in standard packages). SUN's Java JCE policy files
      can be found as separate downloads at the following URLs:

      http://java.sun.com/javase/downloads/index_jdk5.jsp

    => Third party libraries

      Third party libraries that provide unlimited strength JCE
      implementations can also be used. One such library is provided by
      Bouncy Castle:

      http://www.bouncycastle.org/java.html


  4. OPTIONAL: Building the package

    To build the package from source Ant is also needed. The following
    build targets are provided:

    - Packages compiled class files into a JAR archive

        ant jar

    - Builds official distributable archive

        ant dist


  5. OPTIONAL: Testing the package

    JUnit test classes and data files are found under the test/ folder.
    JUnit and Ant are needed for running the tests:

    A servlet is provided for generating custom OpenID URIs and the HTTP
    responses needed during discovery. The servlet is run inside the
    lightweight Jetty servlet container.

    - To run the tests execute the following Ant target:

        ant test

    Alternatively, if Ant is not used, the following need to be configured:

    - The port on which the servlet will listen
        SERVLET_PORT system property

    - The path where the test data is available to the servlet
        TEST_DATA system property

    The test data files need to be updated with the actual servlet port,
    which is part of the YadisURLs


API Usage and Examples:

  Following is the general usage pattern of the library.

  => NOTE: For extended usage see the JavaDoc API documentation
           under apidoc/


  The main interaction points between a web application acting as a
  Relying Party (Consumer) and the library are the Discovery and
  ConsumerManager classes.
  See also the SampleConsumer.java implementation in the consumer package.

        // instantiate a ConsumerManager object
        public static manager = new ConsumerManager();

        // --- placing the authentication request ---

        // determine a return_to URL where your application will receive
        // the authentication responses from the OpenID provider
        String returnToUrl = "http://example.com/openid";

        // perform discovery on the user-supplied identifier
        List discoveries = manager.discover(userSuppliedString);

        // attempt to associate with an OpenID provider
        // and retrieve one service endpoint for authentication
        DiscoveryInformation discovered = manager.associate(discoveries);

        // store the discovery information in the user's session
        session.setAttribute("openid-disco", discovered);

        // Attribute Exchange example: fetching the 'email' attribute
        FetchRequest fetch = new FetchRequest();
        fetch.addAttribute("email",                         // attribute alias
                "http://schema.openid.net/contact/email",   // type URI
                true);                                      // required

        // obtain a AuthRequest message to be sent to the OpenID provider
        AuthRequest authReq = manager.authenticate(discovered, returnToUrl);

        // attach the extension to the authentication request
        authReq.addExtensionParams(fetch);

        if (! discovered.isVersion2() )
        {
            // Option 1: GET HTTP-redirect to the OpenID Provider endpoint
            // The only method supported in OpenID 1.x
            // redirect-URL usually limited to 255 bytes
            return authReq.getRedirectUrl();
        }
        else
        {
            // Option 2: HTML FORM Redirection
            // Allows payloads > 255 bytes

            // <FORM action="OpenID Provider's service endpoint">
            // see samples/formredirection.jsp for a JSP example
            authReq.getOPEndpoint();

            // build a HTML FORM with the message parameters
            authReq.getParameterMap();
        }

        // --- processing the authentication response

        // extract the parameters from the authentication response
        // (which comes in as a HTTP request from the OpenID provider)
        ParameterList response = new ParameterList(httpReq.getParameterMap());

        // retrieve the previously stored discovery information
        DiscoveryInformation discovered
                = (DiscoveryInformation) session.getAttribute("openid-disco");

        // verify the response; ConsumerManager needs to be the same
        // (static) instance used to place the authentication request
        VerificationResult verification = manager.verify(
                httpReq.getRequestURL().toString(),
                response, discovered);

        // examine the verification result and extract the verified identifier
        Identifier verified = verification.getVerifiedId();
        if (verified != null)
        {
            // Attribute Exchange: retrieving the fetched "email" attribute
            AuthSuccess authSuccess = AuthSuccess.createAuthSuccess(response);
            MessageExtension ext =
                    authSuccess.getExtension(AxMessage.OPENID_NS_AX);
            if (ext != null)
            {
                FetchResponse fetchResp =
                        new FetchResponse(ext.getParameters());
                String email = fetchResp.getParameter("email");
            }

            return verified;  // success
        }

  The main interaction point between a web application acting as a
  OpenID Provider (Server) and the library is the ServerManager class.
  See also the SampleServer.java implementation in the server package.

        // instantiate a ServerManager object
        public static ServerManager manager = new ServerManager();

        // configure the OpenID Provider's endpoint URL
        static
        {
            manager.setOPEndpointUrl("Http://my.openidprovider.com/server");
        }

        // extract the parameters from the request
        ParameterList request = new ParameterList(httpReq.getParameterMap());

        String mode = request.hasParameter("openid.mode") ?
                request.getParameterValue("openid.mode") : null;

        Message response;
        String responseText;

        if ("associate".equals(mode))
        {
            // --- process an association request ---
            response = manager.associationResponse(request);
            responseText = response.keyValueFormEncoding();
        }
        else if ("checkid_setup".equals(mode)
                || "checkid_immediate".equals(mode))
        {
            // interact with the user and obtain data needed to continue
            List userData = userInteraction(request);

            String userSelectedId = (String) userData.get(0);
            String userSelectedClaimedId = (String) userData.get(1);
            Boolean authenticatedAndApproved = (Boolean) userData.get(2);

            // --- process an authentication request ---
            response = manager.authResponse(request,
                    userSelectedId,
                    userSelectedClaimedId,
                    authenticatedAndApproved.booleanValue());

            // caller will need to decide which of the following to use:
            // - GET HTTP-redirect to the return_to URL
            // - HTML FORM Redirection
            responseText = response.wwwFormEncoding();
        }
        else if ("check_authentication".equals(mode))
        {
            // --- processing a verification request ---
            response = manager.verify(request);
            responseText = response.keyValueFormEncoding();
        }
        else
        {
            // --- error response ---
            response = DirectError.createDirectError("Unknown request");
            responseText = response.keyValueFormEncoding();
        }

        // return the result to the user
        return responseText;


Contacts:

  If you want freely available support, to participate in active
  development, and to be informed about new code releases, bug fixes,
  security fixes, general news and information about the OpenID4Java
  Library, subscribe to the Google Group at:

        http://groups.google.com/group/openid4java

  If you find a bug in the OpenID4Java Library please submit a defect
  in the tracking database after verifying that it hasn't already been
  submitted.

        http://code.google.com/p/openid4java/issues/list


Thanks for running OpenID!


========================================================================
Copyright 2006-2008 Sxip Identity Corporation

Project home page and package distribution:
  => http://code.google.com/p/openid4java
  => http://code.google.com/p/openid4java/downloads/

For support, please visit the wiki and join the Google Groups!
  => http://groups.google.com/group/openid4java/
  => http://code.google.com/p/openid4java/w/

OpenID
  => http://openid.net/

Released under the Apache License 2.0
  => see LICENSE