From seam-commits at lists.jboss.org Wed Dec 3 16:57:55 2008 Content-Type: multipart/mixed; boundary="===============7239700674513440595==" MIME-Version: 1.0 From: seam-commits at lists.jboss.org To: seam-commits at lists.jboss.org Subject: [seam-commits] Seam SVN: r9703 - trunk/doc/Seam_Reference_Guide/en-US. Date: Wed, 03 Dec 2008 16:57:55 -0500 Message-ID: --===============7239700674513440595== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: norman.richards(a)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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/doc/Seam_Reference_Guide/en-US/Security.xml 2008-12-03 21:24:03 U= TC (rev 9702) +++ trunk/doc/Seam_Reference_Guide/en-US/Security.xml 2008-12-03 21:57:55 U= TC (rev 9703) @@ -5018,5 +5018,154 @@ = = + = + = + + OpenID + = + + OpenID is a community standard for external web-based authenti= cation. The basic + idea is that any web application can supplement (or replace) i= ts local handling of + authentication by delegating responsibility to an external Ope= nID server of the user's + chosing. This benefits the user, who no longer has to remembe= r a name and password for = + every web application he uses, and the developer, who is relie= ved of some of the burden of = + maintaining a complex authentication system. = + + = + 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 http://maximoburrito.myopenid.com however, + it's acceptable to leave off the http:// pa= rt of the identifier when logging into a site. The web application + (known as a relying party in OpenID-speak) determines which Op= enID 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. + + = + + It's important to realize at this + point that authentication does not imply authorization. The w= eb application still needs to make a determination of how to = + use that information. The web application could treat the use= r as instantly logged in and give full access to the system or + it could try and map the presented OpenID to a local user acco= unt, prompting the user to register if he hasn't already. + The choice of how to handle the OpenID is left as a design dec= ision for the local application. = + = + = + + Configuring OpenID + + Seam uses the openid4java package and requires four additi= onal JARs to make use of the Seam integration. These = + are: htmlparser.jar, openid4ja= va.jar, openxri-client.jar = + and openxri-syntax.jar. + + = + + OpenID processing requires the use of the OpenIdP= haseListener, which should be added to your = + faces-config.xml file. The phase liste= ner processes the callback from the OpenID provider, allowing + re-entry into the local application. + + = + <lifecycle> + <phase-listener>org.jboss.seam.security.openid.OpenIdPhaseListen= er</phase-listener> +</lifecycle> + + = + + With this configuration, OpenID support is available to yo= ur application. + The OpenID support component, org.jboss.seam.secu= rity.openid.openid, is installed automatically if the openid4java + classes are on the classpath. + + + = + + Presenting an OpenIdDLogin form + = + + To initiate an OpenID login, you can present a simply for= m to the user asking for the user's OpenID. The #{openid.id} = + value = + accepts the user's OpenID and the #{openid.login= } action initiates an authentication request. + + <h:form> + <h:inputText value=3D"#{openid.id}" /> + <h:commandButton action=3D"#{openid.login}" value=3D"= ;OpenID Login"/> +</h:form> = + = + + When the user submits the login form, he will be redirecte= d to his OpenID provider. The user will eventually = + return to your application through the Seam pseudo-view /openid.xhtml, which is + provided by the OpenIdPhaseListener. Yo= ur application can handle the OpenID response by means = + of a pages.xml navigation from that vie= w, just as if the user had never left your application. + + + = + + Logging in immediately + = + The simplest strategy is to simply login the user immediately. = The following navigation rule shows how to handle this using + the #{openid.loginImmediately()} action. + + = + <page view-id=3D"/openid.xhtm= l"> + <navigation evaluate=3D"#{openid.loginImmediately()}"> + <rule if-outcome=3D"true"> + <redirect view-id=3D"/main.xhtml"> + <message>OpenID login successful...</message> + </redirect> + </rule> + <rule if-outcome=3D"false"> + <redirect view-id=3D"/main.xhtml"> + <message>OpenID login rejected...</message> + </redirect> + </rule> + </navigation> +</page> = + = + Thie loginImmediately() 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 l= ogged in (i.e. #{identity.loggedIn} 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 #{openid.validatedId} and = + #{openid.valid} will be true. + + + + + = + + Deferring login + = + + You may not want the user to be immediately logged in to y= our application. In that case, your navigation + should check the #{openid.valid} proper= ty and redirect the user to a local registration or processing + page. Actions you might take would be asking for more inf= ormation and creating a local user account or presenting a captcha = + to avoid programmatic registrations. When you are done pr= ocessing, if you want to log the user in, you can call + the loginImmediately method, either thr= ough EL as shown previously or by directly interaction with the = + org.jboss.seam.security.openid.OpenId c= omponent. Of course, nothing prevents you from writing custom = + code to interact with the Seam identity component on your = own for even more customized behaviour. + + = + + = + = + + Logging out + = + + Logging out (forgetting an OpenID association) is done by = calling #{openid.logout}. If you + are not using Seam security, you can call this method dire= ctly. If you are using Seam security, you should + continue to use #{identity.logout} and = install an event handler to capture the logout event, calling = + the OpenID logout method. + = + + <event type=3D"org.jboss= .seam.security.loggedOut"> + <action execute=3D"#{openid.logout}" /> +</event> + = + It's important that you do not leave this out or the use= r will not be able to login again in the same session. + + + + = + = + + = + = --===============7239700674513440595==--