[seam-commits] Seam SVN: r9703 - trunk/doc/Seam_Reference_Guide/en-US.
seam-commits at lists.jboss.org
seam-commits at lists.jboss.org
Wed Dec 3 16:57:55 EST 2008
Author: norman.richards at jboss.com
Date: 2008-12-03 16:57:55 -0500 (Wed, 03 Dec 2008)
New Revision: 9703
Modified:
trunk/doc/Seam_Reference_Guide/en-US/Security.xml
Log:
JBSEAM-3711
Modified: trunk/doc/Seam_Reference_Guide/en-US/Security.xml
===================================================================
--- trunk/doc/Seam_Reference_Guide/en-US/Security.xml 2008-12-03 21:24:03 UTC (rev 9702)
+++ trunk/doc/Seam_Reference_Guide/en-US/Security.xml 2008-12-03 21:57:55 UTC (rev 9703)
@@ -5018,5 +5018,154 @@
</sect1>
+
+
+ <sect1>
+ <title>OpenID</title>
+
+ <para>
+ OpenID is a community standard for external web-based authentication. The basic
+ idea is that any web application can supplement (or replace) its local handling of
+ authentication by delegating responsibility to an external OpenID server of the user's
+ chosing. This benefits the user, who no longer has to remember a name and password for
+ every web application he uses, and the developer, who is relieved of some of the burden of
+ maintaining a complex authentication system.
+ </para>
+
+ <para>When using OpenID, the user selects an OpenID provider, and the provider assigns the user
+ an OpenID. The id will take the form of a URL, for example <literal>http://maximoburrito.myopenid.com</literal> however,
+ it's acceptable to leave off the <literal>http://</literal> part of the identifier when logging into a site. The web application
+ (known as a relying party in OpenID-speak) determines which OpenID server to contact and redirects the user to the remote
+ site for authentication. Upon successful authentication the user is given
+ the (cryptographically secure) token proving his identity and is redirected back to the original web application.The
+ local web application can then be sure the user accessing the application controls the OpenID he presented.
+ </para>
+
+ <para>
+ It's important to realize at this
+ point that authentication does not imply authorization. The web application still needs to make a determination of how to
+ use that information. The web application could treat the user as instantly logged in and give full access to the system or
+ it could try and map the presented OpenID to a local user account, prompting the user to register if he hasn't already.
+ The choice of how to handle the OpenID is left as a design decision for the local application.
+ </para>
+
+ <sect2>
+ <title>Configuring OpenID</title>
+ <para>
+ Seam uses the openid4java package and requires four additional JARs to make use of the Seam integration. These
+ are: <literal>htmlparser.jar</literal>, <literal>openid4java.jar</literal>, <literal>openxri-client.jar</literal>
+ and <literal>openxri-syntax.jar</literal>.
+ </para>
+
+ <para>
+ OpenID processing requires the use of the <literal>OpenIdPhaseListener</literal>, which should be added to your
+ <literal>faces-config.xml</literal> file. The phase listener processes the callback from the OpenID provider, allowing
+ re-entry into the local application.
+ </para>
+
+ <programlisting role="XML"><lifecycle>
+ <phase-listener>org.jboss.seam.security.openid.OpenIdPhaseListener</phase-listener>
+</lifecycle></programlisting>
+
+
+ <para>
+ With this configuration, OpenID support is available to your application.
+ The OpenID support component, <literal>org.jboss.seam.security.openid.openid</literal>, is installed automatically if the openid4java
+ classes are on the classpath.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Presenting an OpenIdDLogin form</title>
+
+ <para>
+ To initiate an OpenID login, you can present a simply form to the user asking for the user's OpenID. The <literal>#{openid.id}</literal>
+ value
+ accepts the user's OpenID and the <literal>#{openid.login}</literal> action initiates an authentication request.
+ </para>
+ <programlisting role="XML"><h:form>
+ <h:inputText value="#{openid.id}" />
+ <h:commandButton action="#{openid.login}" value="OpenID Login"/>
+</h:form></programlisting>
+
+ <para>
+ When the user submits the login form, he will be redirected to his OpenID provider. The user will eventually
+ return to your application through the Seam pseudo-view <literal>/openid.xhtml</literal>, which is
+ provided by the <literal>OpenIdPhaseListener</literal>. Your application can handle the OpenID response by means
+ of a <literal>pages.xml</literal> navigation from that view, just as if the user had never left your application.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Logging in immediately</title>
+
+ <para> The simplest strategy is to simply login the user immediately. The following navigation rule shows how to handle this using
+ the <literal>#{openid.loginImmediately()}</literal> action.
+ </para>
+
+ <programlisting role="XML"><page view-id="/openid.xhtml">
+ <navigation evaluate="#{openid.loginImmediately()}">
+ <rule if-outcome="true">
+ <redirect view-id="/main.xhtml">
+ <message>OpenID login successful...</message>
+ </redirect>
+ </rule>
+ <rule if-outcome="false">
+ <redirect view-id="/main.xhtml">
+ <message>OpenID login rejected...</message>
+ </redirect>
+ </rule>
+ </navigation>
+</page></programlisting>
+
+ <para>Thie <literal>loginImmediately()</literal> action checks to see if the OpenID is valid. If it is valid, it adds an
+ OpenIDPrincipal to the identity component, marks the user as logged in (i.e. <literal>#{identity.loggedIn}</literal> will be true)
+ and returns true. If the OpenID was not validated, the method returns false, and the user re-enters the application un-authenticated.
+ If the user's OpenID is valid, it will be accessible using the expression <literal>#{openid.validatedId}</literal> and
+ <literal>#{openid.valid}</literal> will be true.
+ </para>
+
+
+ </sect2>
+
+ <sect2>
+ <title>Deferring login</title>
+
+ <para>
+ You may not want the user to be immediately logged in to your application. In that case, your navigation
+ should check the <literal>#{openid.valid}</literal> property and redirect the user to a local registration or processing
+ page. Actions you might take would be asking for more information and creating a local user account or presenting a captcha
+ to avoid programmatic registrations. When you are done processing, if you want to log the user in, you can call
+ the <literal>loginImmediately</literal> method, either through EL as shown previously or by directly interaction with the
+ <literal>org.jboss.seam.security.openid.OpenId</literal> component. Of course, nothing prevents you from writing custom
+ code to interact with the Seam identity component on your own for even more customized behaviour.
+ </para>
+
+ </sect2>
+
+
+ <sect2>
+ <title>Logging out</title>
+
+ <para>
+ Logging out (forgetting an OpenID association) is done by calling <literal>#{openid.logout}</literal>. If you
+ are not using Seam security, you can call this method directly. If you are using Seam security, you should
+ continue to use <literal>#{identity.logout}</literal> and install an event handler to capture the logout event, calling
+ the OpenID logout method.
+
+ </para>
+ <programlisting role="XML"><event type="org.jboss.seam.security.loggedOut">
+ <action execute="#{openid.logout}" />
+</event> </programlisting>
+
+ <para>It's important that you do not leave this out or the user will not be able to login again in the same session.</para>
+ </sect2>
+
+
+
+
+ </sect1>
+
+
</chapter>
More information about the seam-commits
mailing list