File: INSTALL

package info (click to toggle)
openid4java 1.0.0-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 1,912 kB
  • sloc: java: 14,510; xml: 2,402; jsp: 865; makefile: 11
file content (372 lines) | stat: -rw-r--r-- 13,505 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
.... 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