org.restlet.ext.crypto

Class CookieAuthenticator

java.lang.Object

org.restlet.Restlet

org.restlet.routing.Filter

org.restlet.security.Authenticator

org.restlet.security.ChallengeAuthenticator

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

Constructors

Constructor and Description
CookieAuthenticator(Context context, boolean optional, String realm, byte[] encryptSecretKey) Constructor.
CookieAuthenticator(Context context, String realm, byte[] encryptSecretKey) Constructor for mandatory cookie authenticators.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	attemptRedirect(Request request, Response response) Attempts to redirect the user's browser 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 updates 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.
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 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 updates 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

public 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.