uk.ac.starlink.auth

Interface AuthContext

public interface AuthContext

An object which is capable of manipulating HTTP connections to add required authentication information.

Since:

15 Jun 2020

Method Summary

Modifier and Type	Method and Description
void	configureConnection(java.net.HttpURLConnection connection) Configures an HTTP connection with required authentication.
java.lang.String[]	getCurlArgs(java.net.URL url, boolean showSecret) Returns an array of command-line arguments that could be passed to curl(1) corresponding to the authentication arrangements implemented by this context.
AuthScheme	getScheme() Returns the scheme that yielded this context.
boolean	hasCredentials() Indicates whether this context is actually believed capable of authenticating.
boolean	isChallengeDomain(Challenge challenge, java.net.URL url) Indicates whether this context is expected to be good for authenticating against a given challenge.
boolean	isExpired() Indicates whether this authentication period's validity is known to have expired.
boolean	isUrlDomain(java.net.URL url) Indicates whether this context is expected to be good for authenticating a given URL.

Method Detail

getScheme

AuthScheme getScheme()

Returns the scheme that yielded this context.

Returns:

scheme implementation

hasCredentials

boolean hasCredentials()

Indicates whether this context is actually believed capable of authenticating. If this method returns false, it effectively represents an anonymous connection; in that case the configureConnection(java.net.HttpURLConnection) method will normally do nothing.

Returns:

true if this context can authenticate, false if it represents anonymous access

isUrlDomain

boolean isUrlDomain(java.net.URL url)

Indicates whether this context is expected to be good for authenticating a given URL. Some authentication schemes document scope or protection space rules that allow one to determine whether a context representing a challenge to one URL will be applicable to another.

If this method unconditionally returns false, and a service has authenticated and anonymous access at the same endpoints, it's generally hard for client code ever to use the authenticated access.

Parameters:

url - URL for which authentication is required

Returns:

true iff this context ought to be able to authenticate to the given URL

isChallengeDomain

boolean isChallengeDomain(Challenge challenge,
                          java.net.URL url)

Indicates whether this context is expected to be good for authenticating against a given challenge.

Note that if this returns true, the authentication information owned by this context may be sent to the supplied URL. It is therefore important to return false if the authentication information might be private from the supplied URL, otherwise a malevolent endpoint might issue a challenge with the parameters of a different service to obtain authentication information under false pretences. As a rule of thumb therefore, true should only be returned if the supplied URL is known to be owned by the same party for which this context was established. However, schemes that include scoping rules preventing such information leakage may not require such restrictions.

Parameters:

challenge - challenge

url - URL from which the challenge was received

Returns:

true iff this context ought to be able to answer the given challenge

isExpired

boolean isExpired()

Indicates whether this authentication period's validity is known to have expired.

Returns:

true iff this context is known to be no longer useful

configureConnection

void configureConnection(java.net.HttpURLConnection connection)
                  throws java.io.IOException

Configures an HTTP connection with required authentication. The supplied connection object is unopened (no call to connect() has been made) on entry and on exit.

Parameters:

connection - unopened HTTP connection object

Throws:

java.io.IOException - if authentication could not be configured

getCurlArgs

java.lang.String[] getCurlArgs(java.net.URL url,
                               boolean showSecret)

Returns an array of command-line arguments that could be passed to curl(1) corresponding to the authentication arrangements implemented by this context. This is informational, and done on a best-efforts basis. An empty array may be returned if either no special arrangements in curl are required, or if no curl arguments are known that produce the desired effect.

Parameters:

url - URL to which curl would be connecting

showSecret - if true, sensitive information such as passwords may be included; if false, such items must be omitted

Returns:

array of curl command-line argument strings; no attempt at shell quoting should be applied

See Also:

curl(1)