Overview (OpenID4Java Library)

Packages
Package	Description
org.openid4java
org.openid4java.association
org.openid4java.consumer	Provides functionality for OpenID-enabling Consumer (Relying Party) sites.
org.openid4java.discovery
org.openid4java.discovery.html
org.openid4java.discovery.xrds
org.openid4java.discovery.xri
org.openid4java.discovery.yadis
org.openid4java.infocard	Provides support for OpenID-InforCards.
org.openid4java.infocard.rp
org.openid4java.infocard.sts
org.openid4java.message
org.openid4java.message.ax
org.openid4java.message.pape
org.openid4java.message.sreg
org.openid4java.server	Offers support for implementing an OpenID Provider server.
org.openid4java.util

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 ConsumerManager and Discovery classes. A reference 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 ServerManager class. A reference 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;