src/overview.html

<!--
  ~ Copyright 2006-2008 Sxip Identity Corporation
  -->

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
</head>
<body bgcolor="white">

<h3>
OpenID4Java library offers support for OpenID-enabling a consumer site or
implementing an OpenID Provider server.
</h3>

<h4>Consumer Site / Relying Party:</h4>
<p>
The main interaction points between a web application acting as a
Relying Party (Consumer) and the library are the
{@link org.openid4java.consumer.ConsumerManager ConsumerManager} and
{@link org.openid4java.discovery.Discovery Discovery} classes.
A reference {@link org.openid4java.consumer.SampleConsumer SampleConsumer}
implementation is provided in the consumer package.
See the general <a href="#RelyingParty-usage"> usage pattern </a> below.
</p>

<h4>OpenID Provider / Server:</h4>
<p>
The main interaction point between a web application acting as a
OpenID Provider (Server) and the library is the
{@link org.openid4java.server.ServerManager ServerManager} class.
A reference {@link org.openid4java.server.SampleServer SampleServer}
implementation is provided in the server package.
See the general <a href="#OpenID-Provider-usage"> usage pattern</a> below.
</p>

<a name="RelyingParty-usage" />
<h4>Relying Party / Consumer Usage Pattern:</h4>
<pre>
    // 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";

    // build an Identifier instance from the user-supplied identifier
    Identifier identifier = Discovery.parseIdentifier(userSuppliedString);

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

    // 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

        // &lt;FORM action=&quot;OpenID Provider's service endpoint&quot;&gt;
        // 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");

    // extract the receiving URL from the HTTP request
    StringBuffer receivingURL = httpReq.getRequestURL();
    String queryString = httpReq.getQueryString();
    if (queryString != null && queryString.length() > 0)
        receivingURL.append("?").append(httpReq.getQueryString());

    // verify the response; ConsumerManager needs to be the same
    // (static) instance used to place the authentication request
    VerificationResult verification = manager.verify(
            receivingURL.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
    }

</pre>

<a name="OpenID-Provider-usage" />
<h4>OpenID Provider / Server Usage Pattern:</h4>
<pre>
    // 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;

</pre>

</body>
</html>