org.glassfish.jersey.client.authentication.HttpAuthenticationFeature

All Implemented Interfaces:: Feature

public class HttpAuthenticationFeature extends Object implements Feature

Features that provides Http Basic and Digest client authentication (based on RFC 2617).

The feature can work in following modes:

BASIC: Basic preemptive authentication. In preemptive mode the authentication information is send always with each HTTP request. This mode is more usual than the following non-preemptive mode (if you require BASIC authentication you will probably use this preemptive mode). This mode must be combined with usage of SSL/TLS as the password is send only BASE64 encoded.
BASIC NON-PREEMPTIVE: Basic non-preemptive authentication. In non-preemptive mode the authentication information is added only when server refuses the request with 401 status code and then the request is repeated with authentication information. This mode has negative impact on the performance. The advantage is that it does not send credentials when they are not needed. This mode must be combined with usage of SSL/TLS as the password is send only BASE64 encoded.
Please note that when you use non-preemptive authentication, Jersey client will make 2 requests to a resource, which also means that all registered filters will be invoked twice.
DIGEST: Http digest authentication. Does not require usage of SSL/TLS.
UNIVERSAL: Combination of basic and digest authentication. The feature works in non-preemptive mode which means that it sends requests without authentication information. If 401 status code is returned, the request is repeated and an appropriate authentication is used based on the authentication requested in the response (defined in WWW-Authenticate HTTP header. The feature remembers which authentication requests were successful for given URI and next time tries to preemptively authenticate against this URI with latest successful authentication method.

To initialize the feature use static method of this feature.

Example of building the feature in Basic authentication mode:

 HttpAuthenticationFeature feature = HttpAuthenticationFeature.basic("user", "superSecretPassword");

Example of building the feature in basic non-preemptive mode:

 HttpAuthenticationFeature feature = HttpAuthenticationFeature.basicBuilder()
     .nonPreemptive().credentials("user", "superSecretPassword").build();

Example of building the feature in universal mode:

 HttpAuthenticationFeature feature = HttpAuthenticationFeature.universal("user", "superSecretPassword");

Example of building the feature in universal mode with different credentials for basic and digest:

 HttpAuthenticationFeature feature = HttpAuthenticationFeature.universalBuilder()
      .credentialsForBasic("user", "123456")
      .credentials("adminuser", "hello")
      .build();

Example of building the feature in basic preemptive mode with no default credentials. Credentials will have to be supplied with each request using request properties (see below):

 HttpAuthenticationFeature feature = HttpAuthenticationFeature.basicBuilder().build();

Once the feature is built it needs to be registered into the Client, WebTarget or other client configurable object. Example:

 final Client client = ClientBuilder.newClient();
 client.register(feature);

Then you invoke requests as usual and authentication will be handled by the feature. You can change the credentials for each request using properties HTTP_AUTHENTICATION_USERNAME and HTTP_AUTHENTICATION_PASSWORD. Example:

 final Response response = client.target("http://localhost:8080/rest/homer/contact").request()
    .property(HTTP_AUTHENTICATION_BASIC_USERNAME, "homer")
    .property(HTTP_AUTHENTICATION_BASIC_PASSWORD, "p1swd745").get();

This class also contains property key definitions for overriding only specific basic or digest credentials:

HTTP_AUTHENTICATION_BASIC_USERNAME and HTTP_AUTHENTICATION_BASIC_PASSWORD
HTTP_AUTHENTICATION_DIGEST_USERNAME and HTTP_AUTHENTICATION_DIGEST_PASSWORD.

Since:: 2.5
Author:: Miroslav Fuksa

Nested Class Summary

Nested Classes

Modifier and Type

Class

Description

static interface

HttpAuthenticationFeature.BasicBuilder

Extension of HttpAuthenticationFeature.Builder that builds the http authentication feature configured for basic authentication.

static interface

HttpAuthenticationFeature.Builder

Builder that creates instances of HttpAuthenticationFeature.

static interface

HttpAuthenticationFeature.UniversalBuilder

Extension of HttpAuthenticationFeature.Builder that builds the http authentication feature configured in universal mode that supports basic and digest authentication.
Field Summary

Fields

Modifier and Type

Field

Description

static final String

HTTP_AUTHENTICATION_BASIC_PASSWORD

Key of the property that can be set into the client request using ClientRequestContext.setProperty(String, Object) in order to override the password for http basic authentication feature for the request.

static final String

HTTP_AUTHENTICATION_BASIC_USERNAME

Key of the property that can be set into the client request using ClientRequestContext.setProperty(String, Object) in order to override the username for http basic authentication feature for the request.

static final String

HTTP_AUTHENTICATION_DIGEST_PASSWORD

Key of the property that can be set into the client request using ClientRequestContext.setProperty(String, Object) in order to override the password for http digest authentication feature for the request.

static final String

HTTP_AUTHENTICATION_DIGEST_USERNAME

Key of the property that can be set into the client request using ClientRequestContext.setProperty(String, Object) in order to override the username for http digest authentication feature for the request.

static final String

HTTP_AUTHENTICATION_PASSWORD

Key of the property that can be set into the client request using ClientRequestContext.setProperty(String, Object) in order to override the password for http authentication feature for the request.

static final String

HTTP_AUTHENTICATION_USERNAME

Key of the property that can be set into the client request using ClientRequestContext.setProperty(String, Object) in order to override the username for http authentication feature for the request.
Method Summary

Modifier and Type

Method

Description

static HttpAuthenticationFeature

basic(String username, byte[] password)

Create the http authentication feature in basic preemptive authentication mode initialized with credentials.

static HttpAuthenticationFeature

basic(String username, String password)

Create the http authentication feature in basic preemptive authentication mode initialized with credentials.

static HttpAuthenticationFeature.BasicBuilder

basicBuilder()

Create the builder of the http authentication feature working in basic authentication mode.

boolean

configure(FeatureContext context)

static HttpAuthenticationFeature

digest()

Create the http authentication feature in digest authentication mode initialized without default credentials.

static HttpAuthenticationFeature

digest(String username, byte[] password)

Create the http authentication feature in digest authentication mode initialized with credentials.

static HttpAuthenticationFeature

digest(String username, String password)

Create the http authentication feature in digest authentication mode initialized with credentials.

static HttpAuthenticationFeature

universal(String username, byte[] password)

Create the http authentication feature in combined mode supporting both, basic and digest authentication.

static HttpAuthenticationFeature

universal(String username, String password)

Create the http authentication feature in combined mode supporting both, basic and digest authentication.

static HttpAuthenticationFeature.UniversalBuilder

universalBuilder()

Create the builder that builds http authentication feature in combined mode supporting both, basic and digest authentication.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details
- HTTP_AUTHENTICATION_USERNAME
  
  public static final String HTTP_AUTHENTICATION_USERNAME
  Key of the property that can be set into the client request using ClientRequestContext.setProperty(String, Object) in order to override the username for http authentication feature for the request.
  Example:
  Response response = client.target("http://localhost:8080/rest/joe/orders").request() .property(HTTP_AUTHENTICATION_USERNAME, "joe") .property(HTTP_AUTHENTICATION_PASSWORD, "p1swd745").get();
  
  The property must be always combined with configuration of HTTP_AUTHENTICATION_PASSWORD property (as shown in the example). This property pair overrides all password settings of the authentication feature for the current request.
  The default value must be instance of String.
  
  The name of the configuration property is "jersey.config.client.http.auth.username".
  See Also:
  
  Constant Field Values
- HTTP_AUTHENTICATION_PASSWORD
  
  public static final String HTTP_AUTHENTICATION_PASSWORD
  Key of the property that can be set into the client request using ClientRequestContext.setProperty(String, Object) in order to override the password for http authentication feature for the request.
  Example:
  Response response = client.target("http://localhost:8080/rest/joe/orders").request() .property(HTTP_AUTHENTICATION_USERNAME, "joe") .property(HTTP_AUTHENTICATION_PASSWORD, "p1swd745").get();
  
  The property must be always combined with configuration of HTTP_AUTHENTICATION_USERNAME property (as shown in the example). This property pair overrides all password settings of the authentication feature for the current request.
  The value must be instance of String or byte array (byte[]).
  
  The name of the configuration property is "jersey.config.client.http.auth.password".
  See Also:
  
  Constant Field Values
- HTTP_AUTHENTICATION_BASIC_USERNAME
  
  public static final String HTTP_AUTHENTICATION_BASIC_USERNAME
  Key of the property that can be set into the client request using ClientRequestContext.setProperty(String, Object) in order to override the username for http basic authentication feature for the request.
  Example:
  Response response = client.target("http://localhost:8080/rest/joe/orders").request() .property(HTTP_AUTHENTICATION_BASIC_USERNAME, "joe") .property(HTTP_AUTHENTICATION_BASIC_PASSWORD, "p1swd745").get();
  
  The property must be always combined with configuration of HTTP_AUTHENTICATION_PASSWORD property (as shown in the example). The property pair influence only credentials used during basic authentication.
  The value must be instance of String.
  
  The name of the configuration property is "jersey.config.client.http.auth.basic.username".
  See Also:
  
  Constant Field Values
- HTTP_AUTHENTICATION_BASIC_PASSWORD
  
  public static final String HTTP_AUTHENTICATION_BASIC_PASSWORD
  Key of the property that can be set into the client request using ClientRequestContext.setProperty(String, Object) in order to override the password for http basic authentication feature for the request.
  Example:
  Response response = client.target("http://localhost:8080/rest/joe/orders").request() .property(HTTP_AUTHENTICATION_BASIC_USERNAME, "joe") .property(HTTP_AUTHENTICATION_BASIC_PASSWORD, "p1swd745").get();
  
  The property must be always combined with configuration of HTTP_AUTHENTICATION_USERNAME property (as shown in the example). The property pair influence only credentials used during basic authentication.
  The value must be instance of String or byte array (byte[]).
  
  The name of the configuration property is "jersey.config.client.http.auth.basic.password".
  See Also:
  
  Constant Field Values
- HTTP_AUTHENTICATION_DIGEST_USERNAME
  
  public static final String HTTP_AUTHENTICATION_DIGEST_USERNAME
  Key of the property that can be set into the client request using ClientRequestContext.setProperty(String, Object) in order to override the username for http digest authentication feature for the request.
  Example:
  Response response = client.target("http://localhost:8080/rest/joe/orders").request() .property(HTTP_AUTHENTICATION_DIGEST_USERNAME, "joe") .property(HTTP_AUTHENTICATION_DIGEST_PASSWORD, "p1swd745").get();
  
  The property must be always combined with configuration of HTTP_AUTHENTICATION_PASSWORD property (as shown in the example). The property pair influence only credentials used during digest authentication.
  The value must be instance of String.
  
  The name of the configuration property is "jersey.config.client.http.auth.digest.username".
  See Also:
  
  Constant Field Values
- HTTP_AUTHENTICATION_DIGEST_PASSWORD
  
  public static final String HTTP_AUTHENTICATION_DIGEST_PASSWORD
  Key of the property that can be set into the client request using ClientRequestContext.setProperty(String, Object) in order to override the password for http digest authentication feature for the request.
  Example:
  Response response = client.target("http://localhost:8080/rest/joe/orders").request() .property(HTTP_AUTHENTICATION_DIGEST_USERNAME, "joe") .property(HTTP_AUTHENTICATION_DIGEST_PASSWORD, "p1swd745").get();
  
  The property must be always combined with configuration of HTTP_AUTHENTICATION_PASSWORD property (as shown in the example). The property pair influence only credentials used during digest authentication.
  The value must be instance of String or byte array (byte[]).
  
  The name of the configuration property is "jersey.config.client.http.auth.digest.password".
  See Also:
  
  Constant Field Values
Method Details
- basicBuilder
  
  public static HttpAuthenticationFeature.BasicBuilder basicBuilder()
  
  Create the builder of the http authentication feature working in basic authentication mode. The builder can build preemptive and non-preemptive basic authentication features.
  
  Returns:
  
  Basic http authentication builder.
- basic
  
  public static HttpAuthenticationFeature basic(String username, byte[] password)
  
  Create the http authentication feature in basic preemptive authentication mode initialized with credentials.
  
  Parameters:
  
  username - Username.
  
  password - Password as byte array.
  
  Returns:
  
  Http authentication feature configured in basic mode.
- basic
  
  public static HttpAuthenticationFeature basic(String username, String password)
  
  Create the http authentication feature in basic preemptive authentication mode initialized with credentials.
  
  Parameters:
  
  username - Username.
  
  password - Password as String.
  
  Returns:
  
  Http authentication feature configured in basic mode.
- digest
  
  public static HttpAuthenticationFeature digest()
  
  Create the http authentication feature in digest authentication mode initialized without default credentials. Credentials will have to be supplied using request properties for each request.
  
  Returns:
  
  Http authentication feature configured in digest mode.
- digest
  
  public static HttpAuthenticationFeature digest(String username, byte[] password)
  
  Create the http authentication feature in digest authentication mode initialized with credentials.
  
  Parameters:
  
  username - Username.
  
  password - Password as byte array.
  
  Returns:
  
  Http authentication feature configured in digest mode.
- digest
  
  public static HttpAuthenticationFeature digest(String username, String password)
  
  Create the http authentication feature in digest authentication mode initialized with credentials.
  
  Parameters:
  
  username - Username.
  
  password - Password as String.
  
  Returns:
  
  Http authentication feature configured in digest mode.
- universalBuilder
  
  public static HttpAuthenticationFeature.UniversalBuilder universalBuilder()
  
  Create the builder that builds http authentication feature in combined mode supporting both, basic and digest authentication.
  
  Returns:
  
  Universal builder.
- universal
  
  public static HttpAuthenticationFeature universal(String username, byte[] password)
  
  Create the http authentication feature in combined mode supporting both, basic and digest authentication.
  
  Parameters:
  
  username - Username.
  
  password - Password as byte array.
  
  Returns:
  
  Http authentication feature configured in digest mode.
- universal
  
  public static HttpAuthenticationFeature universal(String username, String password)
  
  Create the http authentication feature in combined mode supporting both, basic and digest authentication.
  
  Parameters:
  
  username - Username.
  
  password - Password as String.
  
  Returns:
  
  Http authentication feature configured in digest mode.
- configure
  
  public boolean configure(FeatureContext context)
  
  Specified by:
  
  configure in interface Feature

Class HttpAuthenticationFeature

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Details

HTTP_AUTHENTICATION_USERNAME

HTTP_AUTHENTICATION_PASSWORD

HTTP_AUTHENTICATION_BASIC_USERNAME

HTTP_AUTHENTICATION_BASIC_PASSWORD

HTTP_AUTHENTICATION_DIGEST_USERNAME

HTTP_AUTHENTICATION_DIGEST_PASSWORD

Method Details

basicBuilder

basic

basic

digest

digest

digest

universalBuilder

universal

universal

configure