OpenID authentication

OpenID Description

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 IBM® WebSphere® sMash Security Relying Party interface. The following sections of this article provide information about OpenID:

Adding zero.security.openid to your application

If you are using OpenID within a WebSphere sMash 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: After adding the dependency, run the zero resolve task from the WebSphere sMash CLI from Eclipse.

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: 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 for more information. The following example shows an OpenID security constraint configuration:

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:

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:

1. The incoming request is checked for a valid token.
2. 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:

1. 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: For additional information on how to create a custom user service registry, see the User Service section.

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.

OpenID and the Connection API