org.glassfish.jersey.client.authentication
Class HttpAuthenticationFeature

java.lang.Object
  org.glassfish.jersey.client.authentication.HttpAuthenticationFeature

All Implemented Interfaces:

javax.ws.rs.core.Feature

@Beta
public class HttpAuthenticationFeature
extends Object
implements javax.ws.rs.core.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.
• 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 (beta)

Author:

Miroslav Fuksa (miroslav.fuksa at oracle.com)

Nested Class Summary

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

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

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(javax.ws.rs.core.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 Detail

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 Detail

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(javax.ws.rs.core.FeatureContext context)

Specified by:

configure in interface javax.ws.rs.core.Feature