OpenID consumer based authentication provides end users with a single digital identity that they can use across the internet. It proves that an end user owns an identity URL without externalizing their password, email address, or any other information users would prefer to protect.

OpenID is completely decentralized, meaning that anyone can choose to be a consumer or identity provider without registering or being approved by any central authority. End users can pick which identity provider they want to use and preserve their identity as they move between providers.

The zero.security.openid package provides an OpenID consumer library that allows applications to use OpenID Identity Providers for third party authentication using the Project Zero Security Relying Party interface.

The following sections of this article provide information about OpenID:

Adding zero.security.openid to your application
Configuring OpenID

Adding zero.security.openid to your application

If you are using OpenID within a Project Zero application, you need to resolve a dependency to install the required jar files. After creating your application, add the following line in the dependencies section of your config/ivy.xml file:

<dependency org="zero" name="zero.security.openid " rev="1.0+"/>

After adding the dependency, run the resolve command as either an Ant task (command line) or Eclipse command. (See Installing and configuring: Command Line Interface or Installing and configuring: Eclipse for Java and Groovy, respectively, for more information.)

Configuring OpenID

To enable OpenID authentication, you need to specify two configuration stanzas as summarized in the following table.

Key	Description	Default Value	Mandatory ?
openidLoginPage	URI for OpenID login form	openidLogin.html	Optional
allowedOpenidDomains	List of trusted OpenID provider domain names	Empty	Optional

The following example shows the OpenID application configuration:

# specify the OpenID loginPage
@include "openid/rule.config"{
   "openidLoginPage": "/openidlogin.gt",
   "allowedOpenidDomains" : ["myopenid.com", "verisignlabs.com"]
}

For securing resources, OpenID uses the same configuration as for other authentication types with the authType being RP for relying party authentication. See the Security rules section of the Security considerations article in the Core Developer's Guide for more information.

The following example shows an OpenID security constraint configuration:

#specify the security constraints
@include "security/rule.config"{
   "conditions": "/request/path =~/protectedResource.groovy(/.*)?",
   "authType" : "RP",
   "groups" : ["ALL_AUTHENTICATED_USERS"]
}

Creating a login form

OpenID login requires the creation of a login form at the location specified by openidLoginPage. There are several requirements for this form:

The method must be POST.
The action must result in the request going to the login page, openidLoginPage, upon submit. If a user navigates to the login page as a result of directory indexing (for example, requests to the root of the application without a resource explicitly listed), the action needs to be openidLoginPage. For all other types of requests, the action can be left blank.
The OpenID Identity field must be named openid_url (as recommended by the OpenID 2.0 specification).

The following example is a sample form:

<html>
        <form method="POST" action="">
        <input type="text" name="openid_url" >
        <input type="submit" name="submit" value="Login">
        <!-- optional hidden value used in requesting unprotected OpenID login page scenario -->
        <input type="hidden" name="postLoginTargetURI" value="secure/index.gt"> 
        
        <input type="submit" value="Submit"/>
        </form>
</html>

Form-based security flow

You can request a protected resource or an unprotected form login page, as described in the following sections.

Requesting a protected resource

When a request comes in for a protected resource, the following events take place:

The incoming request is checked for a valid token.
If a token is:
- Not found or expired:
  1. A 302 status code is sent to the client to redirect it to the login page (as defined in the configuration file under the openidLoginPage entry).
  2. A login is attempted with the incoming credentials.
  3. The server internally connects to a URL specified in openid_url to determine the OpenId provider.
  4. The client is redirected to the OpenID provider for authentication.
  5. If the login is:
    - Unsuccessful, the OpenID Provider's login page is returned again.
    - Successful, a token is generated for subsequent requests and a 302 status code is sent to the client to redirect it to the original protected resource (or was overriden by the postLoginTargetURI query parameter for the OpenID Login Form).
- Found, then an authorization check is performed.
  1. If authorization is:
    - Unsuccessful, a 403 unauthorized status header is returned to the client.
    - Successful, the protected resource is served.

Requesting an unprotected form login page

When a request comes in for the OpenID login page, the following events take place:

A login is attempted with the incoming credentials.
- If the incoming request for the protected resource contains an invalid or missing token:
  1. A login is attempted with the incoming credentials.
  2. The server internally connects to URL specified in openid_url to determine the OpenId provider.
  3. The client is redirected to the OpenID provider for authentication.
  4. If the login is:
    - Unsuccessful, the login page is returned again with a 200 status code.
    - Successful, a token is generated for subsequent requests and a 302 status code is sent to the client to redirect it to the protected resource (that was stored in the hidden postLoginTargetURI form field parameter).
- If the incoming request for the protected resource contains a valid token:
  1. An authorization check is performed.
  2. If authorization is:
    - Unsuccessful, a 403 unauthorized status header is returned to the client.
    - Successful, the protected resource is served.

Note If the OpenIDBasedLoginHandler does not receive the parameter postLoginTargetURI, the user is redirected to the context root of the application where the application developer can define a default file resource to handle the request.

Converting an OpenID to a local ID

While the common usage pattern specifies ALL_AUTHENTICATED_USERS as the GROUP associated with the protected resource for OpenID protected resources, you can also convert an OpenID account to a local account using the resolveFederatedId handler and a custom User Registry named zero.core.security.relying.party.userservice.RPUserService. This handler is fired between the secure and authorization events and can be used to do perform a range of functions from converting the userID to an internal alias to adding special GROUPS or ROLES for the authenticated user. By default, a simple resolver populates the /request/subject in the global context with the remoteUser equal to the OpenID and a group called VALID_OPENID_USER.

The following example shows configuration for a resolveFederatedId:

/config/handlers += [{
   "events" : "resolveFederatedId",
   "handler" : "zero.core.security.relying.party.openid.OpenidResolver.class"
}]

For additional information on how to create a custom user service registry, see the User Service article in the Core Developer's Guide.

Obtaining an OpenID

There are many ways to obtain a OpenID. See the page on the OpenID.net site that lists the various OpenID providers which are commonly used.

r17 - 15 Feb 2008 - 16:32:38 - steveims

Syndicate this site RSS ATOM