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`, User Guide - Authentication

### Field Summary

### Fields inherited from class org.restlet.routing.Filter

`CONTINUE, SKIP, STOP`

### Constructor Summary

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

### Method Summary

Methods
`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.
`java.lang.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(java.lang.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, isOptional, setEnroler, 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

`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`

### Constructor Detail

#### ChallengeAuthenticator

    public ChallengeAuthenticator(Context context,
                          boolean optional,
                          ChallengeScheme challengeScheme,
                          java.lang.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,
                          java.lang.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,
                          java.lang.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 Detail

#### 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 `ChallengeResponse.setAuthenticated(boolean)` and `ClientInfo.setAuthenticated(boolean)` methods are 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 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.

#### 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(java.lang.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.