Task

<setAuthenticator>

Installs an Authenticator whichs determines user name and password through its configuration, or prompts the user interactively for user name and password through a SWING JOptionPane.

An "authenticator" is used by all JRE URLConnections when a host asks for authentication, e.g. HTTP "401:Unauthorized" and "407: Proxy Authentication Required". Also the <ftp2> task uses the authenticator for server authentication and proxy authentication.

The exact strategy of this authenticator is as follows:

• The authentication request is matched against the requestingHost="...", requestingSite="...", requestingPort="...", requestingProtocol="...", requestingPrompt="...", requestingScheme="...", requestingUrl="..." and requestorType="..." of all <credentials> subelements, in the given order. This process stops at the first match.
• If the matching <credentials> subelement has both userName="..." and password="..." configured, then that user name-password pair is returned.
• Otherwise the user is prompted with a JOptionPane dialog for a user name and a password. (Iff the matching <credentials> subelement configured a userName="...", then that user name is pre-filled in.)
  
• After the user has filled in the missing data, the user name and password are returned.

Iff cache="..." is set to a value different from NONE, then the entered user name and/or password are remembered and pre-filled in the next time the authentication dialog pops up. The "remembered" data is not persisted and is lost when the JVM terminates.

Iff store="..." is set to a value different from NONE, then the entered user name and/or password are stored in a persistent "authentication store". That store is a properties file in the user's home directory, and the passwords stored therein are encrypted with a secret key, which is generated ad hoc and stored in another file in the user's home directory (the "key store"). The secret key is protected by a password (called the "master password"), so that an attacker can not compromise the passwords in the authentication store, even if he steals the key store file.

When the secret key is created, the user is prompted to choose the master password:

When a different JVM instance requires the secret key, it prompts the user to enter the master password:

See also:

Authenticator.setDefault(Authenticator)

<credentials>

Attribute Summary

Attributes

Name	Description
cache="..."	Whether user names, user names and passwords, or none of both are remembered while the JVM is running.
dialogLabel="..."	The text of the label in the authentication dialog, in MessageFormat format.
store="..."	Whether user names, user names and passwords, or none of both are persistently stored.

Subelement Summary

Subelements

Name	Description
<credentials>	Every time a server requests user name/password authentication, the <credentials> subelements are checked, and the first that matches the request determines the user name and password.

Attribute Detail

Default values are underlined.

dialogLabel="value"

The text of the label in the authentication dialog, in MessageFormat format.

The following arguments are replaced within the message:

{0}

The "key" to the authentication, which is composed like this:
requestor-type/requesting-protocol/requesting-host/requesting-port/requesting-scheme/
Example value: "PROXY/http/proxy.company.com/8080/Negotiate"

{1}, {2}^*

The requesting host; see requestingHost="..."

{3}, {4}^*

The requesting site; see requestingSite="..."

{5}, {6}^*

The requesting port; see requestingPort="..."

{7}, {8}^*

The requesting protocol; see requestingProtocol="..."

{9}, {10}^*

The requesting prompt; see requestingPrompt="..."

{11}, {12}^*

The requesting scheme; see requestingScheme="..."

{13}, {14}^*

The requesting URL; see requestingUrl="..."

{15}, {16}^*

The requestor type; see requestorType="..."

^* Where the above list presents two placeholders, they expand as follows:

• If the value is either null or "" or -1, the two placeholders expand to "0" and "".
• Otherwise, the two placeholders expand to "1" and the value.

The default value is

<html>
  <table>
    {1,  choice, 0#|1#'<tr><td>Host:    </td><td>'{2}'</td></tr>'}
    {3,  choice, 0#|1#'<tr><td>Site:    </td><td>'{4}'</td></tr>'}
    {5,  choice, 0#|1#'<tr><td>Port:    </td><td>'{6}'</td></tr>'}
    {7,  choice, 0#|1#'<tr><td>Protocol:</td><td>'{8}'</td></tr>'}
    {9,  choice, 0#|1#'<tr><td>Prompt:  </td><td>'{10}'</td></tr>'}
    {11, choice, 0#|1#'<tr><td>Scheme:  </td><td>'{12}'</td></tr>'}
    {13, choice, 0#|1#'<tr><td>URL:     </td><td>'{14}'</td></tr>'}
    {15, choice, 0#|1#'<tr><td>Type:    </td><td>'{16}'</td></tr>'}
  </table>
</html>

cache="NONE|USER_NAMES|USER_NAMES_AND_PASSWORDS"

Whether user names, user names and passwords, or none of both are remembered while the JVM is running. This attribute takes effect only on the first execution of this task.

store="NONE|USER_NAMES|USER_NAMES_AND_PASSWORDS"

Whether user names, user names and passwords, or none of both are persistently stored. This attribute takes effect only on the first execution of this task.

Subelement Detail

<credentials>

Every time a server requests user name/password authentication, the <credentials> subelements are checked, and the first that matches the request determines the user name and password.

A <credentials> subelement matches iff the requesting host, site, port, protocol, url, scheme and requestor type all match the respective attributes.

If no userName="..." and/or no password="..." are configured, then the user is prompted for the missing user name and/or password.

When this task is executed multiply, then the configured <credentials> add up, i.e. previously configured credentials are never erased and always take precedence over newly configured ones.

Attributes:

requestingHost="regex"

Hostname pattern of the site or proxy. The default is "any host".

requestingSite="regex"

InetAddress pattern of the site. The default is "any site".

requestingPort="regex"

The pattern to match against the "port number for the requested connection". The default is "any port".

requestingProtocol="regex"

The pattern to match against "the protocol that's requesting the connection". The default is "any protocol".

requestingPrompt="regex"

The pattern to match against "the prompt string given by the requestor (the "realm" for HTTP authentication)". The default is "any prompt string".

requestingScheme="regex"

The pattern to match against "the scheme of the requestor". The default is "any scheme".

requestingUrl="regex"

The pattern to match against "the URL that resulted in this request for authentication". The default is "any URL".

requestorType="regex"

Whether the requestor is a Proxy or a Server.

PROXY

Entity requesting authentication is a HTTP proxy server.

SERVER

Entity requesting authentication is a HTTP origin server.

The default is "any requestor type".

deny="true|false"

If set to true, then userName="..." and password="..." are ignored, and authentication is denied for this spec. The default is "false".

userName="user-name"

The user name to use iff this <credentials> element matches. Value "-" is equivalent to not configuring a user name.

password="password"

The password to use iff this <credentials> element matches. Value "-" is equivalent to not configuring a password.