public class AuthManager extends Object
getInstance()
)
used for all access to URLs that might have authenticated access;
it will intercept accesses as required and retain authentication
information as required for use in subsequent HTTP(S) requests
so that the user does not have to keep supplying credentials
where they are already known.
An application should typically call setUserInterface(uk.ac.starlink.auth.UserInterface)
on the default instance with an appropriate value near startup and
use the same instance for all subsequent potentially authenticated
URL accesses.
To access (potentially) authenticated resources, client code
will usually just call one of the various overloaded
connect
methods. These are all convenience aliases
for calls to the makeConnection(java.net.URL, uk.ac.starlink.auth.UrlConnector, uk.ac.starlink.auth.Redirector)
method that actually
manages authentication and redirection for connecting to a given URL.
Currently no attempt is made to handle proxy-authentication (407).
Modifier and Type | Field and Description |
---|---|
static AuthScheme[] |
DFLT_SCHEMES
Authentication schemes used by default, in order of preference.
|
Constructor and Description |
---|
AuthManager(UserInterface ui,
AuthScheme[] schemes,
Redirector dfltRedirector)
Constructor.
|
Modifier and Type | Method and Description |
---|---|
AuthStatus |
authcheck(URL authcheckUrl,
boolean isHead,
boolean isForceLogin)
Attempts to establish authentication for an authcheck-type URL.
|
void |
clear()
Clears all authentication state from this manager.
|
URLConnection |
connect(URL url)
Opens a URL connection to a given URL,
negotiating authentication and with default handling of 3xx redirection.
|
URLConnection |
connect(URL url,
UrlConnector connector)
Opens a URL connection to a given URL with specified configuration,
negotiating authentication and with default handling of 3xx redirection.
|
URLConnection |
connect(URL url,
UrlConnector connector,
Redirector redirector)
Opens a URL connection to a given URL with specified configuration,
negotiating authentication and with configurable handling
of 3xx redirection.
|
URLConnection |
followRedirects(URLConnection conn,
UrlConnector connector,
Redirector redirector)
Follows 3xx redirects, applying authentication as required.
|
static AuthManager |
getInstance()
Returns the default instance of this class.
|
List<AuthScheme> |
getSchemes()
Returns a mutable list of authentication schemes known by this manager.
|
UserInterface |
getUserInterface()
Returns the object that controls how the user is queried for credentials.
|
AuthConnection |
makeConnection(URL url,
UrlConnector connector,
Redirector redirector)
Opens a URL connection to a given URL with specified configuration,
negotiating authentication and with configurable handling
of 3xx redirection.
|
InputStream |
openStream(URL url)
Returns the content stream acquired by opening a URL.
|
static void |
setDefaultInstance(AuthManager authManager)
Resets the default AuthManager instance.
|
void |
setUserInterface(UserInterface ui)
Sets the object that controls how the user is queried for credentials.
|
public static final AuthScheme[] DFLT_SCHEMES
public AuthManager(UserInterface ui, AuthScheme[] schemes, Redirector dfltRedirector)
getInstance()
method instead.ui
- user interface implementation;
if null, no authentication management is attemptedschemes
- list of known authentication schemes,
ordered by preferencedfltRedirector
- handles default 3xx redirection behaviourpublic void setUserInterface(UserInterface ui)
ui
- user interface to use
if null, no authentication management is attemptedpublic UserInterface getUserInterface()
public List<AuthScheme> getSchemes()
public void clear()
public URLConnection connect(URL url) throws IOException
connect()
has been called.
An IOException is only thrown in unexpected circumstances; connection failure is usually indicated by the status of the returned connection object.
url
- target URLIOException
public URLConnection connect(URL url, UrlConnector connector) throws IOException
connect()
has been called.
An IOException is only thrown in unexpected circumstances; connection failure is usually indicated by the status of the returned connection object.
url
- target URLconnector
- obtains a connection from a URL;
may be null for default behaviourIOException
public URLConnection connect(URL url, UrlConnector connector, Redirector redirector) throws IOException
connect()
has been called.
An IOException is only thrown in unexpected circumstances; connection failure is usually indicated by the status of the returned connection object.
url
- target URLconnector
- obtains a connection from a URL;
may be null for default behaviourredirector
- controls handling of 3xx redirectionIOException
public AuthConnection makeConnection(URL url, UrlConnector connector, Redirector redirector) throws IOException
connect()
has been called, and the AuthContext
which was used to open it.
An IOException is only thrown in unexpected circumstances; connection failure is usually indicated by the status of the returned connection object.
url
- target URLconnector
- obtains a connection from a URL;
may be null for default behaviourredirector
- controls handling of 3xx redirectionIOException
public InputStream openStream(URL url) throws IOException
connect(url).getInputStream()
.url
- target URLIOException
- in case of failure,
including authentication failurepublic URLConnection followRedirects(URLConnection conn, UrlConnector connector, Redirector redirector) throws IOException
conn
- initial URL connectionconnector
- obtains a connection from a URL;
may be null for default behaviourredirector
- defines how redirection is doneIOException
public AuthStatus authcheck(URL authcheckUrl, boolean isHead, boolean isForceLogin) throws IOException
isForceLogin
parameter)
query the user for credentials as required,
and has the side-effect of setting up authentication to related
URLs for subsequent communication.
Setting the isForceLogin
parameter affects whether
user interaction will take place.
If true, then any previous credentials for challenges received
are disregarded, and either a 200 or a 401/403 response will
trigger user interaction (request for credentials).
If false, any existing credentials are used where applicable,
and user interaction only takes place on a 401/403 response;
so a request for credentials only takes place if it can't
be avoided.
The behaviour of this authcheck endpoint is as follows. Briefly, it behaves as other endpoints in the service except that a service allowing both authenticated and anonymous access should accompany 200 responses to anonymous access with an RFC7235 challenge. In more detail: if authenticated or unauthenticated access is attempted, it should provoke a 200/401/403 response, following normal HTTP rules, matching the behaviour that a similarly authenticated request would see when using the associated VO service. However, in the case of a service that permits both authenticated and anonymous access on the same endpoint, an anonymous request should provoke a 200 response with an accompanying WWW-Authenticate header (an authentication Challenge as defined in RFC7235 sec 4.1). Thus clients attempting authenticated or unauthenticated access must be prepared for
X-VO-Authenticated
header giving the authenticated
user ID if authentication has been established.
The authcheck endpoint MUST support GET and HEAD requests;
the response body is not defined by this proposal.authcheckUrl
- URL at which an authcheck endpoint may be presentisHead
- if true use a HEAD request, if false use GETisForceLogin
- whether to force a new login where it could
be avoidedIOException
public static AuthManager getInstance()
setUserInterface(uk.ac.starlink.auth.UserInterface)
.public static void setDefaultInstance(AuthManager authManager)
authManager
- new default instance