Package net.rim.pushsdk.subscription.auth

This package contains classes related to subscription authentication.

See:
Description

Interface Summary
ContentProviderAuthenticationService	Interface which allows a content provider to perform their own authentication actions.

Class Summary
AuthenticationRequest	Represents the details from an HTTP request to be used for authenticating a subscriber.
BaseAuthenticationRequest	Base class representing the details from an HTTP request to be used for authenticating a subscriber.
ContentProviderAuthServiceImpl	Basic implementation of the ContentProviderAuthenticationService interface.
SubscriberPrincipal	This class implements the Principal interface and represents a subscriber returned from authentication with a name (unique identification) and a set of properties (e.g.

Exception Summary
AuthenticationFailureException	Exception thrown when a subscriber cannot be authenticated.

Package net.rim.pushsdk.subscription.auth Description

This package contains classes related to subscription authentication.

Subscriber authentication:

When a BlackBerry user subscribes to a certain push application for a content provider, they must specify what their username is. The username is just like a username when you go to login to a website. It is supposed to uniquely distinguish one user from another user. For example, my username might be my email address user@somedomain.com. It uniquely identifies me, because only I have access to this email account.

There are other pieces of information that might be pertinent to authenticating a user such as the application the user wishes to subscribe to, the type of subscription operation the user is performing, and possibly a password to confirm that the user is who they say they are.

It is important to note that the subscription servlets (see the net.rim.pushsdk.subscription.web package) allow for the possibility of container-managed authentication through a security realm. If a content provider's application uses container-managed security, then the servlets will retrieve the name (i.e. subscriber id) from the principal of the HTTP request and the authentication classes present in this package will be ignored. If the content provider's application does not use container-managed security, the servlets will make use of the authentication classes in this package to validate a user.

This is where the Content Provider Authentication Service (ContentProviderAuthenticationService) comes in. This interface provides an authenticate method which is used by a content provider to authenticate a user when they attempt a subscription operation (i.e. subscribe, unsubscribe, resume, suspend).

If authentication fails, then an AuthenticationFailureException is thrown.

If authentication is successful, this authenticate method must return a SubscriberPrincipal. A subscriber principal basically contains information that is known about the authenticated user. The name of this subscriber principal must correspond to the id that the content provider uses to uniquely identify that user in their own system. To give examples, this might correspond to the primary key in a content provider's own user database table or the user's id in the content provider's LDAP. For example, I might subscribe to a push application with my email address user@somedomain.com . In their implementation of the authenticate method, a content provider could end up mapping my email address to a subscriber principal with a name of 21456210 (as an example) corresponding to the id that uniquely identifies me in their user's database table.

We have provided a class (ContentProviderAuthServiceImpl) which provides a default implementation of this authenticate method. It always authenticates successfully and does not look up the provided username in a database to get back a primary key or a unique id. It simply returns a subscriber principal with the provided username as the name and a set of properties, including one for the subscription type.

Adding extra properties to subscriber authentication:

An authentication request (see the AuthenticationRequest class) presently has an application id (from an HTTP request parameter), a username (from an HTTP request parameter), password (from an HTTP request parameter), and subscription type (set based on the subscription operation being performed). It is possible for a content provider to add more properties that they specifically need to perform authentication of their users.

Steps:

1. Create a new class (e.g. TestAuthRequest) which extends the AuthenticationRequest class. This new class will have extra authentication fields (e.g. field1, field2).
2. Create a new subscription parser class (e.g. TestSubParser) which extends the SubscriptionRequestParser class. Override the parseAuthenticationRequest(HttpServletRequest) method with your own implementation which parses out field1 and field2 from the HTTP request and returns a TestAuthRequest object.
3. Modify the spring configuration file (pushsdk-subscription-context.xml) to point to your subscription parser class (e.g. TestSubParser) instead of to the SubscriptionRequestParser class:
   <bean id="subscriptionRequestParser" class="net.rim.pushsdk.subscription.web.TestSubParser"> </bean>
4. Create a new class (e.g. TestCPAuthServiceImpl) which implements the ContentProviderAuthenticationService interface. The implementation of the authenticate(BaseAuthenticationRequest) method should cast the request to a TestAuthRequest so that it can make use of the additional fields (i.e. field1, field2) when authenticating a user.
5. Modify the spring configuration file (pushsdk-subscription-context.xml) to point to your implementation (e.g. TestCPAuthServiceImpl) instead of the default implementation (i.e. ContentProviderAuthServiceImpl):
   <bean id="contentProviderAuthenticationService" class="net.rim.pushsdk.subscription.auth.TestCPAuthServiceImpl"> </bean>