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

    All Methods Instance Methods Abstract Methods
    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)