Author: rwatler
Date: Wed Apr 21 12:39:37 2010
New Revision: 936285
URL: http://svn.apache.org/viewvc?rev=936285&view=rev
Log:
JS2-1139: OpenID configuration docs
Added:
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/resources/images/openid-domain-loggedin.png
(with props)
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/resources/images/openid-domain-login.png
(with props)
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/resources/images/openid-loggedin.png
(with props)
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/resources/images/openid-login.png
(with props)
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/xdoc/openid.xml
Modified:
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/site.xml
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/xdoc/index.xml
Added:
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/resources/images/openid-domain-loggedin.png
URL:
http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/resources/images/openid-domain-loggedin.png?rev=936285&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/resources/images/openid-domain-loggedin.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added:
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/resources/images/openid-domain-login.png
URL:
http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/resources/images/openid-domain-login.png?rev=936285&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/resources/images/openid-domain-login.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added:
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/resources/images/openid-loggedin.png
URL:
http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/resources/images/openid-loggedin.png?rev=936285&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/resources/images/openid-loggedin.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added:
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/resources/images/openid-login.png
URL:
http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/resources/images/openid-login.png?rev=936285&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/resources/images/openid-login.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Modified:
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/site.xml
URL:
http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/site.xml?rev=936285&r1=936284&r2=936285&view=diff
==============================================================================
--- portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/site.xml
(original)
+++ portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/site.xml
Wed Apr 21 12:39:37 2010
@@ -53,6 +53,7 @@
<item name="Roles" href="roles.html" />
<item name="SSO" href="sso.html" />
<item name="Users" href="users.html" />
+ <item name="OpenID" href="openid.html" />
</menu>
<menu name="Portal Administration">
Modified:
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/xdoc/index.xml
URL:
http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/xdoc/index.xml?rev=936285&r1=936284&r2=936285&view=diff
==============================================================================
---
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/xdoc/index.xml
(original)
+++
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/xdoc/index.xml
Wed Apr 21 12:39:37 2010
@@ -40,6 +40,7 @@
<li><a href="credentials.html">Credentials</a></li>
<li><a href="permissions.html">Permissions</a></li>
<li><a href="sso.html">Single Sign-on
Management</a></li>
+ <li><a href="openid.html">OpenID
Configuration</a></li>
</ul>
</p>
</subsection>
@@ -63,4 +64,4 @@
</section>
</body>
-</document>
\ No newline at end of file
+</document>
Added:
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/xdoc/openid.xml
URL:
http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/xdoc/openid.xml?rev=936285&view=auto
==============================================================================
---
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/xdoc/openid.xml
(added)
+++
portals/site/jetspeed/jetspeed-2.2/jetspeed-guide-admin/src/site/xdoc/openid.xml
Wed Apr 21 12:39:37 2010
@@ -0,0 +1,332 @@
+<?xml version="1.0"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<document>
+ <properties>
+ <title>OpenID Configuration Guide</title>
+ <subtitle>OpenID Configuration Guide</subtitle>
+ <authors>
+ <person name="Randy Watler" email="[email protected]" />
+ </authors>
+ </properties>
+ <body>
+ <section name="OpenID Configuration">
+ <p>
+ OpenID support in Jetspeed Portal is disabled by default since it
typically needs to be configured for specific OpenID providers. To enable it,
the OpenID support filter and servlet need to be setup in the portal
<code>web.xml</code> configuration file and the OpenID login portlet needs to
be made available in the portal landing page. To utilize OpenID single sign-on,
(SSO), OpenID aware portlets can then be used to access information on other
sites seamlessly.
+ </p>
+ <subsection name="Enabling the OpenID Filter and Servlet">
+ <p>
+ The OpenIDPortalFilter and OpenIDRelayingPartyServlet are required
to support OpenID with the portal. A sample setup is included in the portal
<code>web.xml</code> configuration file. The servlet initialization parameters
configure OpenID discovery, OpenID consumer implementation, and portal user
registration. Some OpenID configuration found here can also be done in the <a
href="#Using_OpenID_Portlets">OpenID login portlet</a> if more than one set of
configurations is needed.
+ </p>
+ <source><![CDATA[
+ ...
+ <filter>
+ <filter-name>OpenIDPortalFilter</filter-name>
+
<filter-class>org.apache.jetspeed.openid.filter.OpenIDPortalFilter</filter-class>
+ </filter>
+ ...
+ <filter-mapping>
+ <filter-name>OpenIDPortalFilter</filter-name>
+ <url-pattern>/*</url-pattern>
+ </filter-mapping>
+ ...
+ <servlet>
+ <description>
+ OpenID Relaying Party, (RP), servlet used to return discovery
+ metadata at OpenID realm and to process authentication return
+ requests.
+ </description>
+ <display-name>OpenID Relaying Party Servlet</display-name>
+ <servlet-name>OpenIDRelayingPartyServlet</servlet-name>
+
<servlet-class>org.apache.jetspeed.openid.OpenIDRelayingPartyServlet</servlet-class>
+ <init-param>
+ <description>Discovery domain to provider URL/host
mapping.</description>
+ <param-name>discovery.gmail.com</param-name>
+ <param-value>https://www.google.com/accounts/o8/id</param-value>
+ </init-param>
+ <init-param>
+ <description>Enable servlet init parameter registration
configuration.</description>
+ <param-name>enableRegistrationConfig</param-name>
+ <param-value>false</param-value>
+ </init-param>
+ <init-param>
+ <description>Enable new user registration.</description>
+ <param-name>enableRegistration</param-name>
+ <param-value>true</param-value>
+ </init-param>
+ <init-param>
+ <description>Global new user template directory to be used for
registration.</description>
+ <param-name>newUserTemplateDirectory</param-name>
+ <param-value>/_template/new-user/</param-value>
+ </init-param>
+ <init-param>
+ <description>Global subsite root folder to be used for
registration.</description>
+ <param-name>subsiteRootFolder</param-name>
+ <param-value></param-value>
+ </init-param>
+ <init-param>
+ <description>Global roles to be assigned at
registration.</description>
+ <param-name>roles</param-name>
+ <param-value>user</param-value>
+ </init-param>
+ <init-param>
+ <description>Global groups to be assigned at
registration.</description>
+ <param-name>groups</param-name>
+ <param-value></param-value>
+ </init-param>
+ <init-param>
+ <description>Global profiling rule names to be assigned at
registration.</description>
+ <param-name>rulesNames</param-name>
+ <param-value>page</param-value>
+ </init-param>
+ <init-param>
+ <description>Global profiling rule values to be assigned at
registration.</description>
+ <param-name>rulesValues</param-name>
+ <param-value>j2</param-value>
+ </init-param>
+ <load-on-startup>2</load-on-startup>
+ </servlet>
+ ...
+ <servlet-mapping>
+ <servlet-name>OpenIDRelayingPartyServlet</servlet-name>
+ <url-pattern>/openid</url-pattern>
+ <url-pattern>/openid/*</url-pattern>
+ </servlet-mapping>
+ ...
+ ]]></source>
+ <p>
+ The following initialization parameters can be used to configure the
OpenIDRelayingPartyServlet:
+ </p>
+ <table>
+ <tr>
+ <th>Parameter</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>discovery.*</td>
+ <td>Discovery domain to provider URL/host mapping. A supported
OpenID domain is appended to property name prefix and the mapped domain or URL
is set for the domain with the property. This property is only necessary if a
non-standard OpenID provider URL is used, (e.g. Google), or a domain alias
mapping is necessary. Examples: discovery.gmail.com =
https://www.google.com/accounts/o8/id or discovery.anotherdomain.com =
mydomain.com</td>
+ </tr>
+ <tr>
+ <td>consumer.*</td>
+ <td>Discovery domain to consumer implementation mapping. A
supported OpenID domain is appended to property name prefix and the mapped
consumer implementation name, ('step2' or 'openid4java'), is set for the domain
with the property. This property is only necessary to specify the Google Step2
library implementation used for Google hosted OpenID domains, (OpenID4Java is
the default implementation). Example: consumer.mydomain.com = step2.</td>
+ </tr>
+ <tr>
+ <td>enableRegistrationConfig</td>
+ <td>Enable servlet init parameter registration configuration. If
this flag is not set, registration configurations in individual <a
href="#Using_OpenID_Portlets">OpenID login portlet</a> instances is used and
these are ignored.</td>
+ </tr>
+ <tr>
+ <td>enableRegistration</td>
+ <td>Enable new user registration.</td>
+ </tr>
+ <tr>
+ <td>newUserTemplateDirectory</td>
+ <td>Global new user template directory to be used for
registration.</td>
+ </tr>
+ <tr>
+ <td>subsiteRootFolder</td>
+ <td>Global subsite root folder to be used for registration.</td>
+ </tr>
+ <tr>
+ <td>roles</td>
+ <td>Global roles to be assigned at registration.</td>
+ </tr>
+ <tr>
+ <td>groups</td>
+ <td>Global groups to be assigned at registration.</td>
+ </tr>
+ <tr>
+ <td>rulesNames</td>
+ <td>Global profiling rule names to be assigned at
registration.</td>
+ </tr>
+ <tr>
+ <td>rulesValues</td>
+ <td>Global profiling rule values to be assigned at
registration.</td>
+ </tr>
+ </table>
+ <p>
+ The user's OpenID email address associated with their OpenId login
is used as the username in the portal. Whenever the user is authenticated by
the <a href="#Using_OpenID_Portlets">OpenID login portlet</a> and
OpenIDRelayingPartyServlet, the following OpenID attribute exchange and/or
simple registration data is synchronized with portal user attributes:
+ </p>
+ <table>
+ <tr>
+ <th>OpenId Data</th>
+ <th>Portal User Attribute</th>
+ </tr>
+ <tr>
+ <td>
+ attribute: http://axschema.org/contact/email<br/>
+ simple registration: email
+ </td>
+ <td>user.business-info.online.email</td>
+ </tr>
+ <tr>
+ <td>
+ attribute: http://axschema.org/namePerson<br/>
+ simple registration: fullname
+ </td>
+ <td>user.name</td>
+ </tr>
+ <tr>
+ <td>
+ attribute: http://axschema.org/namePerson/last<br/>
+ simple registration: n/a
+ </td>
+ <td>user.name.family</td>
+ </tr>
+ <tr>
+ <td>
+ attribute: http://axschema.org/namePerson/first<br/>
+ simple registration: n/a
+ </td>
+ <td>user.name.given</td>
+ </tr>
+ <tr>
+ <td>
+ attribute:http://axschema.org/namePerson/friendly<br/>
+ simple registration: nickname
+ </td>
+ <td>user.name.nickName</td>
+ </tr>
+ </table>
+ <p>
+ In addition to providing OpenID authentication services, the
OpenIDRelayingPartyServlet also serves OpenID Relaying Party metadata. The
metadata endpoint allows the OpenID provider to validate the portal as a
legitimate OpenID client. The URI associated with the metadata is computed from
the metadata request itself, (e.g.
<code>http[s]://portal.mydomain.com/jetspeed/openid</code>).
+ </p>
+ </subsection>
+ <subsection name="Using OpenID Portlets">
+ <p>
+ The OpenIDLoginPortlet is required to support portal OpenID logins.
By default, this portlet is configured to support login buttons for Google,
Yahoo!, and myOpenID providers with an OpenID entry field where users can enter
OpenID URLs or provider domains. New user registration is also enabled by
default, (as mentioned above, the new user's OpenID email address is used as
the portal user id). These and new user registration properties can be
configured as portlet parameters and preferences.
+ </p>
+ <img src="images/openid-login.png"/>
+ <p>
+ Once the end user is logged in, the OpenIDLoginPortlet displays the
logged in user id and allows the user to logout.
+ </p>
+ <img src="images/openid-loggedin.png"/>
+ <p>
+ The following configuration parameters and preferences are supported
by the OpenIDLoginPortlet:
+ </p>
+ <table>
+ <tr>
+ <th>Parameter/Preference Name</th>
+ <th>Default</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>providerLabels</td>
+ <td>Gmail, Yahoo!, myOpenID</td>
+ <td>Display names for OpenID provider buttons.</td>
+ </tr>
+ <tr>
+ <td>providerDomains</td>
+ <td>gmail.com, yahoo.com, myopenid.com</td>
+ <td>Domain names for OpenID provider buttons.</td>
+ </tr>
+ <tr>
+ <td>enableOpenIDEntry</td>
+ <td>true</td>
+ <td>Enable OpenID provider or URL entry.</td>
+ </tr>
+ <tr>
+ <td>enableRegistrationConfig</td>
+ <td>false</td>
+ <td>Enable portlet init parameter registration configuration.</td>
+ </tr>
+ <tr>
+ <td>enableRegistration</td>
+ <td>true</td>
+ <td>Global enable new user registration.</td>
+ </tr>
+ <tr>
+ <td>newUserTemplateDirectory</td>
+ <td>/_template/new-user/</td>
+ <td>Global new user template directory to be used for
registration.</td>
+ </tr>
+ <tr>
+ <td>subsiteRootFolder</td>
+ <td><i>none</i></td>
+ <td>Global subsite root folder to be used for registration.</td>
+ </tr>
+ <tr>
+ <td>roles</td>
+ <td>user</td>
+ <td>Global roles to be assigned at registration.</td>
+ </tr>
+ <tr>
+ <td>groups</td>
+ <td><i>none</i></td>
+ <td>Global groups to be assigned at registration.</td>
+ </tr>
+ <tr>
+ <td>rulesNames</td>
+ <td>page</td>
+ <td>Global profiling rule names to be assigned at
registration.</td>
+ </tr>
+ <tr>
+ <td>rulesValues</td>
+ <td>j2</td>
+ <td>Global profiling rule values to be assigned at
registration.</td>
+ </tr>
+ </table>
+ <p>
+ When a portal user is authenticated using the OpenIDLoginPortlet, a
session attribute that contains the login domain is set. This session
attribute, (<a
href="../apidocs/org/apache/jetspeed/PortalReservedParameters.html"><code>PortalReservedParameters.SESSION_OPEN_ID_PROVIDER</code></a>),
can be checked by other portlets to ensure the user is logged in before
referencing protected resources. The OpenIDIFramePortlet uses this technique to
check an OpenID login domain before including a protected web page. The
following configuration preference is supported by the OpenIDIFramePortlet in
addition to the IFramePortlet preferences:
+ </p>
+ <table>
+ <tr>
+ <th>Preference Name</th>
+ <th>Default</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>REQUIREDOPENIDPROVIDERLABEL</td>
+ <td><i>none</i></td>
+ <td>Required OpenID provider label.</td>
+ </tr>
+ <tr>
+ <td>REQUIREDOPENIDPROVIDER</td>
+ <td><i>none</i></td>
+ <td>Required OpenID provider domain.</td>
+ </tr>
+ </table>
+ <p>
+ The OpenIDIFramePortlet is often used when the portal uses a single
specific OpenID provider to protect enterprise assets. Both the
OpenIDLoginPortlet and the OpenIDIFramePortlet can be configured accordingly.
+ </p>
+ <p>
+ OpenIDLoginPortlet:
+ <ul>
+ <li>providerLabels = MyDomain</li>
+ <li>providerDomains = mydomain.com</li>
+ <li>enableOpenIDEntry = false</li>
+ </ul>
+ </p>
+ <p>
+ OpenIDIFramePortlet:
+ <ul>
+ <li>SRC = http://www.mydomain.com/...</li>
+ <li>REQUIREDOPENIDPROVIDERLABEL = MyDomain</li>
+ <li>REQUIREDOPENIDPROVIDER = mydomain.com</li>
+ </ul>
+ </p>
+ <p>
+ The portlet configuration above will appear like this when the user
is not logged in.
+ </p>
+ <img src="images/openid-domain-login.png"/>
+ <p>
+ After logging in, the user will be able to see the protected content
in the portal page.
+ </p>
+ <img src="images/openid-domain-loggedin.png"/>
+ </subsection>
+ </section>
+ </body>
+</document>
