org.cafesip.jiplet
Interface Realm

public interface Realm

This interface must be implemented by any class that wants to implement a realm. A realm is an authentication and authorization mechanism used by the jiplet container. The jiplet container supports container managed authentication and authorization. That is the jiplet container can authenticate SIP end points sending SIP request messages before the message is delivered to the jiplet. That way, the jiplet do not have to implement its own authentication and authorization scheme. Instead, it can use the mechanism provided by the container.

When a SIP request message is received and a jiplet object is selected for delivery of the request, the container checks if the SIP end point needs to be authenticated. The jip.xml file included with every context specifies the authentication and authorization criteria for all the jiplets in the context. Some jiplets may not have any authentication and authorization criteria, but others may have it. If a jiplet requires authentication and authorization, the SIP end point has not been authenticated and the request message does not contain a Authorization header, the container responds to the request with a UNAUTHORIZED (401) response. If the end point has not been authenticated and an Authorization header is included in the request message for the realm, the realm specified by the jiplet is used to authenticate the user. The container calls the authenticate() method specified by this interface to authenticate. If the SIP end point cannot be authenticated, an UNAUTHORIZED (401) response is sent. If the user is successfully authenticated, the container checks if the user roles to determine if the SIP end-point has the required authorization. If the end point does not have the proper authorization, a FORBIDDEN (403) response is sent. Otherwise, the request is forwarded to the jiplet object.

The jiplet container supports "pluggable authentication modules" (not to be confused with PAM although some of the concepts are similar). That is, it is possible to plugin custom authentication and authorization modules into the jiplet container (configured in server.xml). The jiplet container already comes with a number of pre-defined custom realms but you can plug in your own custom module by creating a class that implements this interface. That way, you can integrate your organization's subscriber database into your jiplet application.

Method Summary

boolean	addUser(java.lang.String user, java.lang.String password, java.lang.String[] roles) This method is used by management applications such as jiplet console to create a SIP end-point account.
java.lang.String[]	authenticate(java.lang.String method, javax.sip.header.AuthorizationHeader header) This method is called by the container to authentication a SIP end point.
boolean	deleteUser(java.lang.String user) This method is used by management applications such as jiplet console to delete a SIP end-point account.
void	destroy() This method is called by the container when the context is being removed.
javax.sip.header.WWWAuthenticateHeader	getAuthenticationHeader(Jiplet jiplet, javax.sip.message.Message message, java.lang.String headerType, boolean stale) When the jiplet container needs to send an UNAUTHORIZED response, it includes an Authenticate header.
java.util.HashMap	getParams() Returns the init params passed to this object in the init() method.
java.lang.String	getRealmName()
java.lang.String[]	getRoles(java.lang.String user) Returns the roles specified for an user.
void	init(java.lang.String name, java.io.File confDir, java.util.HashMap params, boolean defaultRealm) This method is called by the container while initializing the realm.
boolean	isDefaultRealm()
boolean	modifyUser(java.lang.String user, java.lang.String password, java.lang.String[] roles) This method is used by management applications such as jiplet console to modify a SIP end-point account.
boolean	supportsProvisioning()

Method Detail

init

void init(java.lang.String name,
          java.io.File confDir,
          java.util.HashMap params,
          boolean defaultRealm)
          throws JipletException

This method is called by the container while initializing the realm. Realm-providers can implement the initialization logic inside this method. The parameters configured in the server.xml file is passed in as the parameters to this method as key-value pairs. The realm can throw a jiplet exception to signal that the initialization failed.

Parameters:

name - name of the realm as configured in the server.xml.

confDir - the full path name for the conf directory - where the jiplet containerconfiguration is stored .

params - init params

defaultRealm - true if the realm is the default realm.

Throws:

JipletException

destroy

void destroy()

This method is called by the container when the context is being removed. Realm-providers can implement finalization logic inside this method.

getRealmName

java.lang.String getRealmName()

Returns:

the name of the realm.

authenticate

java.lang.String[] authenticate(java.lang.String method,
                                javax.sip.header.AuthorizationHeader header)

This method is called by the container to authentication a SIP end point. On successful authentication, a list of "roles" in returned. A role is a String containing an abstract role name specified while configuring the user. The role specifies the authorization criteria. A jiplet can be configured (using jip.xml) to accept request messages only when an authenticated SIP end point has the specified roles.

Parameters:

method - The method field of the SIP request message.

header - The parsed authorization header field received in the SIP message.

Returns:

null if the user could not be authenticated, Otherwise the roles configured for the user is returned.

getAuthenticationHeader

javax.sip.header.WWWAuthenticateHeader getAuthenticationHeader(Jiplet jiplet,
                                                               javax.sip.message.Message message,
                                                               java.lang.String headerType,
                                                               boolean stale)

When the jiplet container needs to send an UNAUTHORIZED response, it includes an Authenticate header. This method provides the Authentication header..

Parameters:

jiplet - the jiplet object.

message - the message that is being challenged.

headerType - WWW-Authenticate or Proxy-Authenticate

stale - true if the stale field should be set

Returns:

the header object. The realm can return a null to indicate that it does not want to throw a challenge to this message.

addUser

boolean addUser(java.lang.String user,
                java.lang.String password,
                java.lang.String[] roles)
                throws java.lang.UnsupportedOperationException

This method is used by management applications such as jiplet console to create a SIP end-point account. If a realm does not support this operation, it must throw an UnsupportedOperationException exception.

Parameters:

user - user name

password - password for the user

roles - authorization role for the user

Returns:

true if succssful, false otheriwse

Throws:

java.lang.UnsupportedOperationException

modifyUser

boolean modifyUser(java.lang.String user,
                   java.lang.String password,
                   java.lang.String[] roles)
                   throws java.lang.UnsupportedOperationException

This method is used by management applications such as jiplet console to modify a SIP end-point account. If a realm does not support this operation, it must throw an UnsupportedOperationException exception.

Parameters:

user - user name, must be an existing user

password - password for the user, null if the password does not have to be changed.

roles - authorization role for the user, null, if authorizations do not have to be modified.

Returns:

true if succssful, false otheriwse

Throws:

java.lang.UnsupportedOperationException

deleteUser

boolean deleteUser(java.lang.String user)
                   throws java.lang.UnsupportedOperationException

This method is used by management applications such as jiplet console to delete a SIP end-point account. If a realm does not support this operation, it must throw an UnsupportedOperationException exception.

Parameters:

user -

Returns:

true if succssful, false otheriwse

Throws:

java.lang.UnsupportedOperationException

getRoles

java.lang.String[] getRoles(java.lang.String user)
                            throws java.lang.UnsupportedOperationException

Returns the roles specified for an user. A null is returned if the user is not found.

Parameters:

user -

Returns:

Throws:

java.lang.UnsupportedOperationException

supportsProvisioning

boolean supportsProvisioning()

Returns:

true if the user supports provisioning (creating/modifying/deleting user accounts).

getParams

java.util.HashMap getParams()

Returns the init params passed to this object in the init() method.

Returns:

isDefaultRealm

boolean isDefaultRealm()

Returns:

true if this realm is the default realm.