### OpenID4Java library offers support for OpenID-enabling a consumer site or implementing an OpenID Provider server.

#### Consumer Site / Relying Party:

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 usage pattern below.

#### OpenID Provider / Server:

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 usage pattern below.

#### Relying Party / Consumer Usage Pattern:

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

            // <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");

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

#### OpenID Provider / Server Usage Pattern:

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