Package org.restlet.security

Class ChallengeAuthenticator

java.lang.Object

org.restlet.Restlet

org.restlet.routing.Filter

org.restlet.security.Authenticator

org.restlet.security.ChallengeAuthenticator

All Implemented Interfaces:

Uniform

public class ChallengeAuthenticator
extends Authenticator

Authenticator based on a challenge scheme. This is typically used to support the HTTP BASIC and DIGEST challenge schemes.

Author:

Jerome Louvel

See Also:

• ChallengeScheme
• ChallengeRequest
• ChallengeResponse

Field Summary

Fields inherited from class org.restlet.routing.Filter

CONTINUE, SKIP, STOP

Constructor Summary

Constructors

Constructor	Description
ChallengeAuthenticator(Context context, boolean optional, ChallengeScheme challengeScheme, String realm)	Constructor using the context's default verifier.
ChallengeAuthenticator(Context context, boolean optional, ChallengeScheme challengeScheme, String realm, Verifier verifier)	Constructor.
ChallengeAuthenticator(Context context, ChallengeScheme challengeScheme, String realm)	Constructor setting the optional property to false.

Method Summary

Modifier and Type	Method	Description
protected boolean	authenticate(Request request, Response response)	Authenticates the call, relying on the verifier to check the credentials provided (in general an identifier + secret couple).
void	challenge(Response response, boolean stale)	Challenges the client by adding a challenge request to the response and by setting the status to Status.CLIENT_ERROR_UNAUTHORIZED.
protected ChallengeRequest	createChallengeRequest(boolean stale)	Creates a new challenge request.
void	forbid(Response response)	Rejects the call due to a failed authentication or authorization.
String	getRealm()	Returns the authentication realm.
ChallengeScheme	getScheme()	Returns the authentication challenge scheme.
Verifier	getVerifier()	Returns the credentials verifier.
boolean	isRechallenging()	Indicates if a new challenge should be sent when invalid credentials are received (true by default to conform to HTTP recommendations).
void	setRealm(String realm)	Sets the authentication realm.
void	setRechallenging(boolean rechallenging)	Indicates if a new challenge should be sent when invalid credentials are received.
void	setVerifier(Verifier verifier)	Sets the credentials verifier.

Methods inherited from class org.restlet.security.Authenticator

authenticated, beforeHandle, 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 Details

ChallengeAuthenticator

public ChallengeAuthenticator(Context context,
 boolean optional,
 ChallengeScheme challengeScheme,
 String realm)

Constructor using the context's default verifier.

Parameters:

context - The context.

optional - Indicates if the authentication success is optional.

challengeScheme - The authentication scheme to use.

realm - The authentication realm.

See Also:

• ChallengeAuthenticator(Context, boolean, ChallengeScheme, String, Verifier)

ChallengeAuthenticator

public ChallengeAuthenticator(Context context,
 boolean optional,
 ChallengeScheme challengeScheme,
 String realm,
 Verifier verifier)

Constructor.

Parameters:

context - The context.

optional - Indicates if the authentication success is optional.

challengeScheme - The authentication scheme to use.

realm - The authentication realm.

verifier - The credentials verifier.

ChallengeAuthenticator

public ChallengeAuthenticator(Context context,
 ChallengeScheme challengeScheme,
 String realm)

Constructor setting the optional property to false.

Parameters:

context - The context.

challengeScheme - The authentication scheme to use.

realm - The authentication realm.

See Also:

• ChallengeAuthenticator(Context, boolean, ChallengeScheme, String, Verifier)

Method Details

authenticate

protected boolean authenticate(Request request,
 Response response)

Authenticates the call, relying on the verifier to check the credentials provided (in general an identifier + secret couple). If the credentials are valid, the next Restlet attached is invoked.

If the credentials are missing, then challenge(Response, boolean) is invoked.

If the credentials are invalid and if the "rechallenge" property is true then challenge(Response, boolean) is invoked. Otherwise, forbid(Response) is invoked.

If the credentials are stale, then challenge(Response, boolean) is invoked with the "stale" parameter to true.

At the end of the process, the ClientInfo.setAuthenticated(boolean) method is invoked.

Specified by:

authenticate in class Authenticator

Parameters:

request - The request sent.

response - The response to update.

Returns:

True if the authentication succeeded.

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 Status.CLIENT_ERROR_UNAUTHORIZED.

Parameters:

response - The response to update.

stale - Indicates if the new challenge is due to a stale response.

createChallengeRequest

protected ChallengeRequest createChallengeRequest(boolean stale)

Creates a new challenge request.

Parameters:

stale - Indicates if the new challenge is due to a stale response.

Returns:

A new challenge request.

forbid

public void forbid(Response response)

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.

getRealm

public String getRealm()

Returns the authentication realm.

Returns:

The authentication realm.

getScheme

public ChallengeScheme getScheme()

Returns the authentication challenge scheme.

Returns:

The authentication challenge scheme.

getVerifier

public Verifier getVerifier()

Returns the credentials verifier.

Returns:

The credentials verifier.

isRechallenging

public boolean isRechallenging()

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 method forbid(Response) will be called.

Returns:

True if invalid credentials result in a new challenge.

setRealm

public void setRealm(String realm)

Sets the authentication realm.

Parameters:

realm - The authentication realm.

setRechallenging

public void setRechallenging(boolean rechallenging)

Indicates if a new challenge should be sent when invalid credentials are received.

Parameters:

rechallenging - True if invalid credentials result in a new challenge.

See Also:

• isRechallenging()

setVerifier

public void setVerifier(Verifier verifier)

Sets the credentials verifier.

Parameters:

verifier - The credentials verifier.