org.restlet.security

Class Guard

java.lang.Object

org.restlet.Restlet

org.restlet.routing.Filter

org.restlet.security.Guard

All Implemented Interfaces:

Uniform

Deprecated.

Use the ChallengeAuthenticator class instead.

@Deprecated
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 Status.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

Field Summary

Fields

Modifier and Type	Field and Description
static int	AUTHENTICATION_INVALID Deprecated. Indicates that an authentication response is considered invalid.
static int	AUTHENTICATION_MISSING Deprecated. Indicates that an authentication response couldn't be found.
static int	AUTHENTICATION_STALE Deprecated. Indicates that an authentication response is stale.
static int	AUTHENTICATION_VALID Deprecated. Indicates that an authentication response is valid.
static long	DEFAULT_NONCE_LIFESPAN_MILLIS Deprecated. Default lifespan for generated nonces (5 minutes).

Fields inherited from class org.restlet.routing.Filter

CONTINUE, SKIP, STOP

Constructor Summary

Constructors

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

Method Summary

Methods

Modifier and Type	Method and Description
void	accept(Request request, Response response) Deprecated. Accepts the call.
int	authenticate(Request request) Deprecated. Indicates if the call is properly authenticated.
boolean	authorize(Request request) Deprecated. Indicates if the request is authorized to pass through the Guard.
void	challenge(Response response, boolean stale) Deprecated. 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) Deprecated. Indicates if the secret is valid for the given identifier.
int	doHandle(Request request, Response response) Deprecated. Handles the call by distributing it to the next Restlet.
char[]	findSecret(java.lang.String identifier) Deprecated. Finds the secret associated to a given identifier.
void	forbid(Response response) Deprecated. Rejects the call due to a failed authentication or authorization.
java.util.Collection<java.lang.String>	getDomainUris() Deprecated. Returns the base URIs that collectively define the protected domain for HTTP Digest Authentication.
long	getNonceLifespan() Deprecated. Returns the number of milliseconds between each mandatory nonce refresh.
java.lang.String	getRealm() Deprecated. Returns the authentication realm.
ChallengeScheme	getScheme() Deprecated. Returns the authentication challenge scheme.
Resolver<char[]>	getSecretResolver() Deprecated. Returns the secret resolver.
java.util.concurrent.ConcurrentMap<java.lang.String,char[]>	getSecrets() Deprecated. Returns the modifiable map of identifiers and secrets.
java.lang.String	getServerKey() Deprecated. Returns the secret key known only by server.
boolean	isRechallengeEnabled() Deprecated. 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) Deprecated. Sets the URIs that define the HTTP DIGEST authentication protection domains.
void	setNonceLifespan(long lifespan) Deprecated. Sets the number of milliseconds between each mandatory nonce refresh.
void	setRealm(java.lang.String realm) Deprecated. Sets the authentication realm.
void	setRechallengeEnabled(boolean rechallengeEnabled) Deprecated. Indicates if a new challenge should be sent when invalid credentials are received.
void	setScheme(ChallengeScheme scheme) Deprecated. Sets the authentication challenge scheme.
void	setSecretResolver(Resolver<char[]> secretResolver) Deprecated. Sets the secret resolver.
void	setServerKey(java.lang.String serverKey) Deprecated. Sets the secret key known only by server.

Methods inherited from class org.restlet.routing.Filter

afterHandle, beforeHandle, getNext, handle, hasNext, setNext, setNext, start, stop

Methods inherited from class org.restlet.Restlet

finalize, getApplication, getAuthor, getContext, getDescription, getLogger, getName, getOwner, isStarted, isStopped, setAuthor, setContext, setDescription, setName, setOwner

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

AUTHENTICATION_INVALID

public static final int AUTHENTICATION_INVALID

Deprecated.

Indicates that an authentication response is considered invalid.

See Also:

Constant Field Values

AUTHENTICATION_MISSING

public static final int AUTHENTICATION_MISSING

Deprecated.

Indicates that an authentication response couldn't be found.

See Also:

Constant Field Values

AUTHENTICATION_STALE

public static final int AUTHENTICATION_STALE

Deprecated.

Indicates that an authentication response is stale.

See Also:

Constant Field Values

AUTHENTICATION_VALID

public static final int AUTHENTICATION_VALID

Deprecated.

Indicates that an authentication response is valid.

See Also:

Constant Field Values

DEFAULT_NONCE_LIFESPAN_MILLIS

public static final long DEFAULT_NONCE_LIFESPAN_MILLIS

Deprecated.

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

Deprecated.

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)

Deprecated.

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)

Deprecated.

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)

Deprecated.

Indicates if the call is properly authenticated. By default, this delegates credentials checking to checkSecret(). Note that the ChallengeResponse.setAuthenticated(boolean) and ClientInfo.setAuthenticated(boolean) methods are 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(Request, String, char[])

authorize

public boolean authorize(Request request)

Deprecated.

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

public void challenge(Response response,
             boolean stale)

Deprecated.

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)

Deprecated.

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

doHandle

public int doHandle(Request request,
           Response response)

Deprecated.

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)

Deprecated.

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)

Deprecated.

Rejects the call due to a failed authentication or authorization. This can be overridden to change the default 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()

Deprecated.

Returns the base URIs that collectively define the protected domain for HTTP Digest Authentication.

Returns:

The base URIs.

getNonceLifespan

public long getNonceLifespan()

Deprecated.

Returns the number of milliseconds between each mandatory nonce refresh.

Returns:

The nonce lifespan.

getRealm

public java.lang.String getRealm()

Deprecated.

Returns the authentication realm.

Returns:

The authentication realm.

getScheme

public ChallengeScheme getScheme()

Deprecated.

Returns the authentication challenge scheme.

Returns:

The authentication challenge scheme.

getSecretResolver

public Resolver<char[]> getSecretResolver()

Deprecated.

Returns the secret resolver.

Returns:

The secret resolver.

getSecrets

public java.util.concurrent.ConcurrentMap<java.lang.String,char[]> getSecrets()

Deprecated.

Returns the modifiable map of identifiers and secrets.

Returns:

The map of identifiers and secrets.

getServerKey

public java.lang.String getServerKey()

Deprecated.

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()

Deprecated.

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)

Deprecated.

Sets the URIs that define the HTTP DIGEST authentication protection domains.

Parameters:

domainUris - The URIs of protection domains.

setNonceLifespan

public void setNonceLifespan(long lifespan)

Deprecated.

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)

Deprecated.

Sets the authentication realm.

Parameters:

realm - The authentication realm.

setRechallengeEnabled

public void setRechallengeEnabled(boolean rechallengeEnabled)

Deprecated.

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)

Deprecated.

Sets the authentication challenge scheme.

Parameters:

scheme - The authentication challenge scheme.

setSecretResolver

public void setSecretResolver(Resolver<char[]> secretResolver)

Deprecated.

Sets the secret resolver.

Parameters:

secretResolver - The secret resolver.

setServerKey

public void setServerKey(java.lang.String serverKey)

Deprecated.

Sets the secret key known only by server. This is used by the HTTP DIGEST authentication scheme.

Parameters:

serverKey - The server secret key.