Documentation Contents

Overview

• HTTP Basic authentication (RFC2617)
• HTTP Digest authentication (RFC2617)
• NTLM (defined by Microsoft)
• Http SPNEGO Negotiate (defined by Microsoft), with the following underlying mechanisms:
  • Kerberos
  • NTLM

Generally, all authentication schemes work with both proxies and servers. Some (basic and digest) can be used simultaneously with proxies and servers. See below for how to distinguish between proxy and server authentication.

How to use the Authenticator class

Extending java.net.Authenticator

    class MyAuthenticator extends Authenticator {

        public PasswordAuthentication getPasswordAuthentication () {
            return new PasswordAuthentication ("user", "pass1".toCharArray());
        }
    }

This simple example returns the username "user" and the password "pass1" for every HTTP authentication interaction. A more realistic example would use the other methods of java.net.Authenticator to get more information about the HTTP request that needs to be authenticated. Any of the following methods may be called by the implementation of getPasswordAuthentication() in order to decide how to handle each request for credentials.

• getRequestingHost()
• getRequestingPort()
• getRequestingPrompt()
• getRequestingProtocol()
• getRequestingScheme()
• getRequestingURL()
• getRequestingSite()
• getRequestorType(). Returns whether requestor is a proxy or server.

Enabling authentication

        Authenticator.setDefault (authinstance);

where authinstance is an instance of the declared implementation class. If this is not called, then authentication is disabled, and server authentication errors will be returned to user code via IOException objects. Once installed, the http implementation will try to authenticate automatically where possible (via cached credentials, or credentials that can be acquired from the system). If the correct credentials are not available then the user's authenticator is invoked to provide them.

Controlling which authentication scheme is used

If the user needs to ensure that a particular scheme is used, then the following system property can be set to modify the default behavior.

        -Dhttp.auth.preference="scheme"

-D is specified if the property is being set on the command line. "http.auth.preference" is the property name, and scheme is the name of the scheme to use. If the server does not include this scheme in its list of proposed schemes, then the default choice is made.

Details of each authentication scheme

Http Basic

The getRequestingPrompt() method returns the Basic authentication realm as provided by the server.

Http digest

        -Dhttp.auth.digest.validateServer="true"
        -Dhttp.auth.digest.validateProxy="true"

The getRequestingPrompt() method returns the Digest authentication realm as provided by the server.

NTLM

On Microsoft Windows platforms, NTLM authentication attempts to acquire the user credentials from the system without prompting the user's authenticator object. If these credentials are not accepted by the server then the user's authenticator will be called.

Because the Authenticator class was defined prior to NTLM being supported, it was not possible to add support in the API for the NTLM domain field. There are three options for specifying the domain:

1. Do not specify it. In some environments, the domain is not actually required and the application need not specify it.
2. The domain name can be encoded within the username by prefixing the domain name followed by a back-slash '\' before the username. With this method, existing applications that use the Authenticator class do not need to be modified, so long as users are made aware that this notation must be used.
3. If a domain name is not specified as in method 2) and the system property "http.auth.ntlm.domain" is defined, then the value of this property will be used as the domain name.

Http Negotiate (SPNEGO)

Kerberos 5 Configuration

• Some way to provide Kerberos configurations. This can be achieved with the Java system property java.security.krb5.conf. For example:

            java -Djava.security.krb5.conf=krb5.conf \
                 -Djavax.security.auth.useSubjectCredsOnly=false \
                 ClassName

• A JAAS config file denoting what login module to use. HTTP SPNEGO codes will look for the standard entry named com.sun.security.jgss.krb5.initiate.

          com.sun.security.jgss.krb5.initiate {
              com.sun.security.auth.module.Krb5LoginModule
                  required useTicketCache=true;
          };

            java -Djava.security.krb5.conf=krb5.conf \
                 -Djava.security.auth.login.config=spnegoLogin.conf \
                 -Djavax.security.auth.useSubjectCredsOnly=false \
                 ClassName

Username and Password Retrieval

    class MyAuthenticator extends Authenticator {

        public PasswordAuthentication getPasswordAuthentication () {
            if (getRequestingScheme().equalsIgnoreCase("negotiate")) {
                String krb5user;
                char[] krb5pass;
                // get krb5user and krb5pass in your own way
                ....
                return (new PasswordAuthentication (krb5user,
                            krb5pass));
            } else {
                ....
            }
        }
    }

Scheme Preference

• GSS/SPNEGO -> Digest -> NTLM -> Basic

Fallback

Example

You need to prepare these files to get the protected file:

Code listing for RunHttpSpnego.java

import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.Authenticator;
import java.net.PasswordAuthentication;
import java.net.URL;

public class RunHttpSpnego {

    static final String kuser = "username"; // your account name
    static final String kpass = "password"; // your password for the account

    static class MyAuthenticator extends Authenticator {
        public PasswordAuthentication getPasswordAuthentication() {
            // I haven't checked getRequestingScheme() here, since for NTLM
            // and Negotiate, the usrname and password are all the same.
            System.err.println("Feeding username and password for " + getRequestingScheme());
            return (new PasswordAuthentication(kuser, kpass.toCharArray()));
        }
    }

    public static void main(String[] args) throws Exception {
        Authenticator.setDefault(new MyAuthenticator());
        URL url = new URL(args[0]);
        InputStream ins = url.openConnection().getInputStream();
        BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
        String str;
        while((str = reader.readLine()) != null)
            System.out.println(str);
    }
}

Code listing for krb5.conf

[libdefaults]
    default_realm = AD.LOCAL
[realms]
    AD.LOCAL = {
        kdc = kdc.ad.local
    }
    

Code listing for login.conf

com.sun.security.jgss.krb5.initiate {
  com.sun.security.auth.module.Krb5LoginModule required doNotPrompt=false useTicketCache=true;
};

Then, compile RunHttpSpnego.java and run:

java -Djava.security.krb5.conf=krb5.conf \
    -Djava.security.auth.login.config=login.conf \
    -Djavax.security.auth.useSubjectCredsOnly=false \
    RunHttpSpnego \
    http://www.ad.local/hello/hello.html

You will see:

Feeding username and password for Negotiate
<h1>Hello, You got me!</h1>

In fact, if you are running on a Windows machine as a domain user, or, you are running on a Linux or Solaris machine that has already issued the kinit command and got the credential cache. The class MyAuthenticator will be completely ignored, and the output will be simply

<h1>Hello, You got me!</h1>

java RunHttpSpnego \
    http://www.ad.local/hello/hello.html

Feeding username and password for ntlm
<h1>Hello, You got me!</h1>

Copyright © 1993, 2011, Oracle and/or its affiliates. All rights reserved. Please send comments using this Feedback page.

Java Technology