Class HttpAuthenticationFeature

  • All Implemented Interfaces:
    javax.ws.rs.core.Feature

    public class HttpAuthenticationFeature
    extends java.lang.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.

      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:

    Since:
    2.5
    • Field Detail

      • HTTP_AUTHENTICATION_USERNAME

        public static final java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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​(java.lang.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​(java.lang.String username,
                                                      java.lang.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​(java.lang.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​(java.lang.String username,
                                                       java.lang.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​(java.lang.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​(java.lang.String username,
                                                          java.lang.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