org.restlet
Class Guard

java.lang.Object
  extended by org.restlet.Uniform
      extended by org.restlet.Restlet
          extended by org.restlet.Filter
              extended by org.restlet.Guard

public class Guard
extends Filter

Filter guarding the access to an attached Restlet. More concretely, it guards from unauthenticated and unauthorized requests, providing facilities to check credentials such as passwords. It is also a relatively generic class which can work with several challenge schemes such as HTTP Basic and HTTP Digest.

Here are the processing steps of a Guard when a request reaches it:

  1. It first attempts to authenticate it, i.e. to make sure that the challenge scheme used is supported and that the credentials given by the client (such as a login and password) are valid. The actual implementation of the authentication is delegated to the matching authentication helper. The result of this authentication can be:
    1. Valid: the authentication credentials are valid, the right scheme was used and the credentials could be verified by calling back the checkSecret() method on Guard. Here are the next steps:
      1. The authorize() method is called and if authorization is given the accept() method is invoked, which delegates to the attached Restlet or Resource by default. Otherwise, the forbid method is called, which sets the response status to CLIENT_ERROR_FORBIDDEN (403).
    2. Missing: no credentials could be found, the challenge() method is invoked which delegates to the matching authenticator helper.
    3. Invalid: bad credentials were given such as a wrong password or unsupported scheme was used. If the "rechallenge" property is true, the challenge() method is invoked otherwise, the forbid() method is invoked.
    4. Stale: the credentials expired and must be renew. Therefore, the challenge() method is invoked.
Concurrency note: instances of this class or its subclasses can be invoked by several threads at the same time and therefore must be thread-safe. You should be especially careful when storing state in member variables.

Author:
Jerome Louvel
See Also:
Tutorial: Guarding access to sensitive resources

Field Summary
static int AUTHENTICATION_INVALID
          Indicates that an authentication response is considered invalid.
static int AUTHENTICATION_MISSING
          Indicates that an authentication response couldn't be found.
static int AUTHENTICATION_STALE
          Indicates that an authentication response is stale.
static int AUTHENTICATION_VALID
          Indicates that an authentication response is valid.
static long DEFAULT_NONCE_LIFESPAN_MILLIS
          Default lifespan for generated nonces (5 minutes).
 
Fields inherited from class org.restlet.Filter
CONTINUE, SKIP, STOP
 
Constructor Summary
Guard(Context context, ChallengeScheme scheme, java.lang.String realm)
          Constructor.
Guard(Context context, java.lang.String realm, java.util.Collection<java.lang.String> baseUris, java.lang.String serverKey)
          Alternate Constructor for HTTP DIGEST authentication scheme.
 
Method Summary
 void accept(Request request, Response response)
          Accepts the call.
 int authenticate(Request request)
          Indicates if the call is properly authenticated.
 boolean authorize(Request request)
          Indicates if the request is authorized to pass through the Guard.
 void challenge(Response response)
          Deprecated. Use the challenge(Response, boolean) method instead.
 void challenge(Response response, boolean stale)
          Challenges the client by adding a challenge request to the response and by setting the status to CLIENT_ERROR_UNAUTHORIZED.
 boolean checkSecret(Request request, java.lang.String identifier, char[] secret)
          Indicates if the secret is valid for the given identifier.
protected  boolean checkSecret(java.lang.String identifier, char[] secret)
          Deprecated. Use the checkSecret(Request, String, char[]) method instead.
 int doHandle(Request request, Response response)
          Handles the call by distributing it to the next Restlet.
 char[] findSecret(java.lang.String identifier)
          Finds the secret associated to a given identifier.
 void forbid(Response response)
          Rejects the call due to a failed authentication or authorization.
 java.util.Collection<java.lang.String> getDomainUris()
          Returns the base URIs that collectively define the protected domain for HTTP Digest Authentication.
 long getNonceLifespan()
          Returns the number of milliseconds between each mandatory nonce refresh.
 java.lang.String getRealm()
          Returns the authentication realm.
 ChallengeScheme getScheme()
          Returns the authentication challenge scheme.
 Resolver<char[]> getSecretResolver()
          Returns the secret resolver.
 java.util.concurrent.ConcurrentMap<java.lang.String,char[]> getSecrets()
          Returns the modifiable map of identifiers and secrets.
 java.lang.String getServerKey()
          Returns the secret key known only by server.
 boolean isRechallengeEnabled()
          Indicates if a new challenge should be sent when invalid credentials are received (true by default to conform to HTTP recommendations).
 void setDomainUris(java.util.Collection<java.lang.String> domainUris)
          Sets the URIs that define the HTTP DIGEST authentication protection domains.
 void setNonceLifespan(long lifespan)
          Sets the number of milliseconds between each mandatory nonce refresh.
 void setRealm(java.lang.String realm)
          Sets the authentication realm.
 void setRechallengeEnabled(boolean rechallengeEnabled)
          Indicates if a new challenge should be sent when invalid credentials are received.
 void setScheme(ChallengeScheme scheme)
          Sets the authentication challenge scheme.
 void setSecretResolver(Resolver<char[]> secretResolver)
          Sets the secret resolver.
 void setServerKey(java.lang.String serverKey)
          Sets the secret key known only by server.
 
Methods inherited from class org.restlet.Filter
afterHandle, beforeHandle, getNext, handle, hasNext, setNext, setNext
 
Methods inherited from class org.restlet.Restlet
getApplication, getContext, getLogger, init, isStarted, isStopped, setContext, start, stop
 
Methods inherited from class org.restlet.Uniform
delete, delete, get, get, handle, head, head, options, options, post, post, put, put
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

AUTHENTICATION_INVALID

public static final int AUTHENTICATION_INVALID
Indicates that an authentication response is considered invalid.

See Also:
Constant Field Values

AUTHENTICATION_MISSING

public static final int AUTHENTICATION_MISSING
Indicates that an authentication response couldn't be found.

See Also:
Constant Field Values

AUTHENTICATION_STALE

public static final int AUTHENTICATION_STALE
Indicates that an authentication response is stale.

See Also:
Constant Field Values

AUTHENTICATION_VALID

public static final int AUTHENTICATION_VALID
Indicates that an authentication response is valid.

See Also:
Constant Field Values

DEFAULT_NONCE_LIFESPAN_MILLIS

public static final long DEFAULT_NONCE_LIFESPAN_MILLIS
Default lifespan for generated nonces (5 minutes).

See Also:
Constant Field Values
Constructor Detail

Guard

public Guard(Context context,
             ChallengeScheme scheme,
             java.lang.String realm)
      throws java.lang.IllegalArgumentException
Constructor.

Parameters:
context - The context.
scheme - The authentication scheme to use.
realm - The authentication realm.
Throws:
java.lang.IllegalArgumentException - if the scheme is null

Guard

public Guard(Context context,
             java.lang.String realm,
             java.util.Collection<java.lang.String> baseUris,
             java.lang.String serverKey)
Alternate Constructor for HTTP DIGEST authentication scheme.

Parameters:
context - context
realm - authentication realm
baseUris - protection domain as a collection of base URIs
serverKey - secret key known only to server
Method Detail

accept

public void accept(Request request,
                   Response response)
Accepts the call. By default, it is invoked if the request is authenticated and authorized. The default behavior is to ask to the attached Restlet to handle the call.

Parameters:
request - The request to accept.
response - The response to accept.

authenticate

public int authenticate(Request request)
Indicates if the call is properly authenticated. By default, this delegates credential checking to checkSecret(). Note that the ChallengeResponse.setAuthenticated(boolean) method is always called after authentication.

Parameters:
request - The request to authenticate.
Returns:
-1 if the given credentials were invalid, 0 if no credentials were found and 1 otherwise.
See Also:
checkSecret(String, char[])

authorize

public boolean authorize(Request request)
Indicates if the request is authorized to pass through the Guard. This method is only called if the call was successfully authenticated. It always returns true by default. If specific checks are required, they could be added by overriding this method.

Parameters:
request - The request to authorize.
Returns:
True if the request is authorized.

challenge

@Deprecated
public void challenge(Response response)
Deprecated. Use the challenge(Response, boolean) method instead.

Challenges the client by adding a challenge request to the response and by setting the status to CLIENT_ERROR_UNAUTHORIZED.

Parameters:
response - The response to update.

challenge

public void challenge(Response response,
                      boolean stale)
Challenges the client by adding a challenge request to the response and by setting the status to CLIENT_ERROR_UNAUTHORIZED.

Parameters:
response - The response to update.
stale - Indicates if the new challenge is due to a stale response.

checkSecret

public boolean checkSecret(Request request,
                           java.lang.String identifier,
                           char[] secret)
Indicates if the secret is valid for the given identifier. By default, this returns true given the correct login/password couple as verified via the findSecret() method.

Parameters:
request - The Request
identifier - the identifier
secret - the identifier's secret
Returns:
true if the secret is valid for the given identifier

checkSecret

@Deprecated
protected boolean checkSecret(java.lang.String identifier,
                                         char[] secret)
Deprecated. Use the checkSecret(Request, String, char[]) method instead.

Indicates if the secret is valid for the given identifier. By default, this returns true given the correct login/password couple as verified via the findSecret() method.

Parameters:
identifier - the identifier
secret - the identifier's secret
Returns:
true if the secret is valid for the given identifier

doHandle

public int doHandle(Request request,
                    Response response)
Handles the call by distributing it to the next Restlet.

Overrides:
doHandle in class Filter
Parameters:
request - The request to handle.
response - The response to update.
Returns:
The continuation status.

findSecret

public char[] findSecret(java.lang.String identifier)
Finds the secret associated to a given identifier. By default it looks up into the secrets map, but this behavior can be overriden by setting a custom secret resolver using the setSecretResolver(Resolver) method.

Parameters:
identifier - The identifier to lookup.
Returns:
The secret associated to the identifier or null.

forbid

public void forbid(Response response)
Rejects the call due to a failed authentication or authorization. This can be overriden to change the defaut behavior, for example to display an error page. By default, if authentication is required, the challenge method is invoked, otherwise the call status is set to CLIENT_ERROR_FORBIDDEN.

Parameters:
response - The reject response.

getDomainUris

public java.util.Collection<java.lang.String> getDomainUris()
Returns the base URIs that collectively define the protected domain for HTTP Digest Authentication.

Returns:
The base URIs.

getNonceLifespan

public long getNonceLifespan()
Returns the number of milliseconds between each mandatory nonce refresh.

Returns:
The nonce lifespan.

getRealm

public java.lang.String getRealm()
Returns the authentication realm.

Returns:
The authentication realm.

getScheme

public ChallengeScheme getScheme()
Returns the authentication challenge scheme.

Returns:
The authentication challenge scheme.

getSecretResolver

public Resolver<char[]> getSecretResolver()
Returns the secret resolver.

Returns:
The secret resolver.

getSecrets

public java.util.concurrent.ConcurrentMap<java.lang.String,char[]> getSecrets()
Returns the modifiable map of identifiers and secrets.

Returns:
The map of identifiers and secrets.

getServerKey

public java.lang.String getServerKey()
Returns the secret key known only by server. This is used by the HTTP DIGEST authentication scheme.

Returns:
The server secret key.

isRechallengeEnabled

public boolean isRechallengeEnabled()
Indicates if a new challenge should be sent when invalid credentials are received (true by default to conform to HTTP recommendations). If set to false, upon reception of invalid credentials, the Guard will forbid the access (Status.CLIENT_ERROR_FORBIDDEN).

Returns:
True if invalid credentials result in a new challenge.

setDomainUris

public void setDomainUris(java.util.Collection<java.lang.String> domainUris)
Sets the URIs that define the HTTP DIGEST authentication protection domains.

Parameters:
domainUris - The URIs of protection domains.

setNonceLifespan

public void setNonceLifespan(long lifespan)
Sets the number of milliseconds between each mandatory nonce refresh.

Parameters:
lifespan - The nonce lifespan in ms.

setRealm

public void setRealm(java.lang.String realm)
Sets the authentication realm.

Parameters:
realm - The authentication realm.

setRechallengeEnabled

public void setRechallengeEnabled(boolean rechallengeEnabled)
Indicates if a new challenge should be sent when invalid credentials are received.

Parameters:
rechallengeEnabled - True if invalid credentials result in a new challenge.
See Also:
isRechallengeEnabled()

setScheme

public void setScheme(ChallengeScheme scheme)
Sets the authentication challenge scheme.

Parameters:
scheme - The authentication challenge scheme.

setSecretResolver

public void setSecretResolver(Resolver<char[]> secretResolver)
Sets the secret resolver.

Parameters:
secretResolver - The secret resolver.

setServerKey

public void setServerKey(java.lang.String serverKey)
Sets the secret key known only by server. This is used by the HTTP DIGEST authentication scheme.

Parameters:
serverKey - The server secret key.


Copyright © 2005-2008 Noelios Technologies.