org.restlet.ext.crypto
Class CookieAuthenticator

java.lang.Object
  extended by org.restlet.Restlet
      extended by org.restlet.routing.Filter
          extended by org.restlet.security.Authenticator
              extended by org.restlet.security.ChallengeAuthenticator
                  extended by org.restlet.ext.crypto.CookieAuthenticator
All Implemented Interfaces:
Uniform

public class CookieAuthenticator
extends ChallengeAuthenticator

Challenge authenticator based on browser cookies. This is useful when the web application requires a finer grained control on the login and logout process and can't rely solely on standard schemes such as ChallengeScheme.HTTP_BASIC.

Login can be automatically handled by intercepting HTTP POST calls to the getLoginPath() URI. The request entity should contain an HTML form with two fields, the first one named getIdentifierFormName() and the second one named getSecretFormName().

Logout can be automatically handled as well by intercepting HTTP GET or POST calls to the getLogoutPath() URI.

After login or logout, the user's browser can be redirected to the URI provided in a query parameter named by getRedirectQueryName().

When the credentials are missing or stale, the challenge(Response, boolean) method is invoked by the parent class, and its default behavior is to redirect the user's browser to the getLoginFormPath() URI, adding the URI of the target resource as a query parameter of name getRedirectQueryName().

Note that credentials, both identifier and secret, are stored in a cookie in an encrypted manner. The default encryption algorithm is AES but can be changed with setEncryptAlgorithm(String). It is also strongly recommended to

Author:
Remi Dewitte, Jerome Louvel

Field Summary
 
Fields inherited from class org.restlet.routing.Filter
CONTINUE, SKIP, STOP
 
Constructor Summary
CookieAuthenticator(Context context, boolean optional, String realm, byte[] encryptSecretKey)
          Constructor.
CookieAuthenticator(Context context, String realm, byte[] encryptSecretKey)
          Constructor for mandatory cookie authenticators.
 
Method Summary
protected  void attemptRedirect(Request request, Response response)
          Attempts to redirect the user's browser can be redirected to the URI provided in a query parameter named by getRedirectQueryName().
protected  boolean authenticate(Request request, Response response)
          Restores credentials from the cookie named getCookieName() if available.
protected  int authenticated(Request request, Response response)
          Sets or update the credentials cookie.
protected  int beforeHandle(Request request, Response response)
          Optionally handles the login and logout actions by intercepting the HTTP calls to the getLoginPath() and getLogoutPath() URIs.
 void challenge(Response response, boolean stale)
          This method should be overridden to return a login form representation.
By default, it redirects the user's browser to the getLoginFormPath() URI, adding the URI of the target resource as a query parameter of name getRedirectQueryName().
In case the getLoginFormPath() is not set, it calls the parent's method.
protected  String formatCredentials(ChallengeResponse challenge)
          Formats the raws credentials to store in the cookie.
 String getCookieName()
          Returns the cookie name to use for the authentication credentials.
protected  CookieSetting getCredentialsCookie(Request request, Response response)
          Returns the credentials cookie setting.
 String getEncryptAlgorithm()
          Returns the name of the algorithm used to encrypt the log info cookie value.
 byte[] getEncryptSecretKey()
          Returns the secret key for the algorithm used to encrypt the log info cookie value.
 String getIdentifierFormName()
          Returns the name of the HTML login form field containing the identifier.
 String getLoginFormPath()
          Returns the URI path of the HTML login form to use to challenge the user.
 String getLoginPath()
          Returns the login URI path to intercept.
 String getLogoutPath()
          Returns the logout URI path to intercept.
 int getMaxCookieAge()
          Returns the maximum age of the log info cookie.
 String getRedirectQueryName()
          Returns the name of the query parameter containing the URI to redirect the browser to after login or logout.
 String getSecretFormName()
          Returns the name of the HTML login form field containing the secret.
 boolean isInterceptingLogin()
          Indicates if the login requests should be intercepted.
 boolean isInterceptingLogout()
          Indicates if the logout requests should be intercepted.
protected  boolean isLoggingIn(Request request, Response response)
          Indicates if the request is an attempt to log in and should be intercepted.
protected  boolean isLoggingOut(Request request, Response response)
          Indicates if the request is an attempt to log out and should be intercepted.
protected  void login(Request request, Response response)
          Processes the login request.
protected  int logout(Request request, Response response)
          Processes the logout request.
protected  ChallengeResponse parseCredentials(String cookieValue)
          Decodes the credentials stored in a cookie into a proper ChallengeResponse object.
 void setCookieName(String cookieName)
          Sets the cookie name to use for the authentication credentials.
 void setEncryptAlgorithm(String secretAlgorithm)
          Sets the name of the algorithm used to encrypt the log info cookie value.
 void setEncryptSecretKey(byte[] secretKey)
          Sets the secret key for the algorithm used to encrypt the log info cookie value.
 void setIdentifierFormName(String loginInputName)
          Sets the name of the HTML login form field containing the identifier.
 void setInterceptingLogin(boolean intercepting)
          Indicates if the login requests should be intercepted.
 void setInterceptingLogout(boolean intercepting)
          Indicates if the logout requests should be intercepted.
 void setLoginFormPath(String loginFormPath)
          Sets the URI path of the HTML login form to use to challenge the user.
 void setLoginPath(String loginPath)
          Sets the login URI path to intercept.
 void setLogoutPath(String logoutPath)
          Sets the logout URI path to intercept.
 void setMaxCookieAge(int timeout)
          Sets the maximum age of the log info cookie.
 void setRedirectQueryName(String redirectQueryName)
          Sets the name of the query parameter containing the URI to redirect the browser to after login or logout.
 void setSecretFormName(String passwordInputName)
          Sets the name of the HTML login form field containing the secret.
 
Methods inherited from class org.restlet.security.ChallengeAuthenticator
createChallengeRequest, forbid, getRealm, getScheme, getVerifier, isRechallenging, setRealm, setRechallenging, setVerifier
 
Methods inherited from class org.restlet.security.Authenticator
getEnroler, isMultiAuthenticating, isOptional, setEnroler, setMultiAuthenticating, setOptional, unauthenticated
 
Methods inherited from class org.restlet.routing.Filter
afterHandle, doHandle, getNext, handle, hasNext, setNext, setNext, start, stop
 
Methods inherited from class org.restlet.Restlet
createFinder, finalize, getApplication, getAuthor, getContext, getDescription, getFinderClass, getLogger, getName, getOwner, handle, handle, handle, isStarted, isStopped, setAuthor, setContext, setDescription, setFinderClass, setName, setOwner
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CookieAuthenticator

public CookieAuthenticator(Context context,
                           boolean optional,
                           String realm,
                           byte[] encryptSecretKey)
Constructor. Use the ChallengeScheme.HTTP_COOKIE pseudo-scheme.

Parameters:
context - The parent context.
optional - Indicates if this authenticator is optional so alternative authenticators down the chain can be attempted.
realm - The name of the security realm.
encryptSecretKey - The secret key used to encrypt the cookie value.

CookieAuthenticator

public CookieAuthenticator(Context context,
                           String realm,
                           byte[] encryptSecretKey)
Constructor for mandatory cookie authenticators.

Parameters:
context - The parent context.
realm - The name of the security realm.
encryptSecretKey - The secret key used to encrypt the cookie value.
Method Detail

attemptRedirect

protected void attemptRedirect(Request request,
                               Response response)
Attempts to redirect the user's browser can be redirected to the URI provided in a query parameter named by getRedirectQueryName().

Parameters:
request - The current request.
response - The current response.

authenticate

protected boolean authenticate(Request request,
                               Response response)
Restores credentials from the cookie named getCookieName() if available. The usual processing is the followed.

Overrides:
authenticate in class ChallengeAuthenticator

authenticated

protected int authenticated(Request request,
                            Response response)
Sets or update the credentials cookie.

Overrides:
authenticated in class Authenticator

beforeHandle

protected int beforeHandle(Request request,
                           Response response)
Optionally handles the login and logout actions by intercepting the HTTP calls to the getLoginPath() and getLogoutPath() URIs.

Overrides:
beforeHandle in class Authenticator

challenge

public void challenge(Response response,
                      boolean stale)
This method should be overridden to return a login form representation.
By default, it redirects the user's browser to the getLoginFormPath() URI, adding the URI of the target resource as a query parameter of name getRedirectQueryName().
In case the getLoginFormPath() is not set, it calls the parent's method.

Overrides:
challenge in class ChallengeAuthenticator

formatCredentials

protected String formatCredentials(ChallengeResponse challenge)
                            throws GeneralSecurityException
Formats the raws credentials to store in the cookie.

Parameters:
challenge - The challenge response to format.
Returns:
The raw credentials.
Throws:
GeneralSecurityException

getCookieName

public String getCookieName()
Returns the cookie name to use for the authentication credentials. By default, it is is "Credentials".

Returns:
The cookie name to use for the authentication credentials.

getCredentialsCookie

protected CookieSetting getCredentialsCookie(Request request,
                                             Response response)
Returns the credentials cookie setting. It first try to find an existing cookie. If necessary, it creates a new one.

Parameters:
request - The current request.
response - The current response.
Returns:
The credentials cookie setting.

getEncryptAlgorithm

public String getEncryptAlgorithm()
Returns the name of the algorithm used to encrypt the log info cookie value. By default, it returns "AES".

Returns:
The name of the algorithm used to encrypt the log info cookie value.

getEncryptSecretKey

public byte[] getEncryptSecretKey()
Returns the secret key for the algorithm used to encrypt the log info cookie value.

Returns:
The secret key for the algorithm used to encrypt the log info cookie value.

getIdentifierFormName

public String getIdentifierFormName()
Returns the name of the HTML login form field containing the identifier. Returns "login" by default.

Returns:
The name of the HTML login form field containing the identifier.

getLoginFormPath

public String getLoginFormPath()
Returns the URI path of the HTML login form to use to challenge the user.

Returns:
The URI path of the HTML login form to use to challenge the user.

getLoginPath

public String getLoginPath()
Returns the login URI path to intercept.

Returns:
The login URI path to intercept.

getLogoutPath

public String getLogoutPath()
Returns the logout URI path to intercept.

Returns:
The logout URI path to intercept.

getMaxCookieAge

public int getMaxCookieAge()
Returns the maximum age of the log info cookie. By default, it uses -1 to make the cookie only last until the end of the current browser session.

Returns:
The maximum age of the log info cookie.
See Also:
CookieSetting.getMaxAge()

getRedirectQueryName

public String getRedirectQueryName()
Returns the name of the query parameter containing the URI to redirect the browser to after login or logout. By default, it uses "targetUri".

Returns:
The name of the query parameter containing the URI to redirect the browser to after login or logout.

getSecretFormName

public String getSecretFormName()
Returns the name of the HTML login form field containing the secret. Returns "password" by default.

Returns:
The name of the HTML login form field containing the secret.

isInterceptingLogin

public boolean isInterceptingLogin()
Indicates if the login requests should be intercepted.

Returns:
True if the login requests should be intercepted.

isInterceptingLogout

public boolean isInterceptingLogout()
Indicates if the logout requests should be intercepted.

Returns:
True if the logout requests should be intercepted.

isLoggingIn

protected boolean isLoggingIn(Request request,
                              Response response)
Indicates if the request is an attempt to log in and should be intercepted.

Parameters:
request - The current request.
response - The current response.
Returns:
True if the request is an attempt to log in and should be intercepted.

isLoggingOut

protected boolean isLoggingOut(Request request,
                               Response response)
Indicates if the request is an attempt to log out and should be intercepted.

Parameters:
request - The current request.
response - The current response.
Returns:
True if the request is an attempt to log out and should be intercepted.

login

protected void login(Request request,
                     Response response)
Processes the login request.

Parameters:
request - The current request.
response - The current response.

logout

protected int logout(Request request,
                     Response response)
Processes the logout request.

Parameters:
request - The current request.
response - The current response.

parseCredentials

protected ChallengeResponse parseCredentials(String cookieValue)
Decodes the credentials stored in a cookie into a proper ChallengeResponse object.

Parameters:
cookieValue - The credentials to decode from cookie value.
Returns:
The credentials as a proper challenge response.

setCookieName

public void setCookieName(String cookieName)
Sets the cookie name to use for the authentication credentials.

Parameters:
cookieName - The cookie name to use for the authentication credentials.

setEncryptAlgorithm

public void setEncryptAlgorithm(String secretAlgorithm)
Sets the name of the algorithm used to encrypt the log info cookie value.

Parameters:
secretAlgorithm - The name of the algorithm used to encrypt the log info cookie value.

setEncryptSecretKey

public void setEncryptSecretKey(byte[] secretKey)
Sets the secret key for the algorithm used to encrypt the log info cookie value.

Parameters:
secretKey - The secret key for the algorithm used to encrypt the log info cookie value.

setIdentifierFormName

public void setIdentifierFormName(String loginInputName)
Sets the name of the HTML login form field containing the identifier.

Parameters:
loginInputName - The name of the HTML login form field containing the identifier.

setInterceptingLogin

public void setInterceptingLogin(boolean intercepting)
Indicates if the login requests should be intercepted.

Parameters:
intercepting - True if the login requests should be intercepted.

setInterceptingLogout

public void setInterceptingLogout(boolean intercepting)
Indicates if the logout requests should be intercepted.

Parameters:
intercepting - True if the logout requests should be intercepted.

setLoginFormPath

public void setLoginFormPath(String loginFormPath)
Sets the URI path of the HTML login form to use to challenge the user.

Parameters:
loginFormPath - The URI path of the HTML login form to use to challenge the user.

setLoginPath

public void setLoginPath(String loginPath)
Sets the login URI path to intercept.

Parameters:
loginPath - The login URI path to intercept.

setLogoutPath

public void setLogoutPath(String logoutPath)
Sets the logout URI path to intercept.

Parameters:
logoutPath - The logout URI path to intercept.

setMaxCookieAge

public void setMaxCookieAge(int timeout)
Sets the maximum age of the log info cookie.

Parameters:
timeout - The maximum age of the log info cookie.
See Also:
CookieSetting.setMaxAge(int)

setRedirectQueryName

public void setRedirectQueryName(String redirectQueryName)
Sets the name of the query parameter containing the URI to redirect the browser to after login or logout.

Parameters:
redirectQueryName - The name of the query parameter containing the URI to redirect the browser to after login or logout.

setSecretFormName

public void setSecretFormName(String passwordInputName)
Sets the name of the HTML login form field containing the secret.

Parameters:
passwordInputName - The name of the HTML login form field containing the secret.


Copyright © 2005-2013 Restlet.