# Package uk.ac.starlink.auth

Manages authentication for HTTP(S) resources in accordance with VO standards.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  AuthContext | An object which is capable of manipulating HTTP connections to add required authentication information.
  AuthScheme | Represents an RFC7235 authentication scheme.
  ContextFactory | Contains configuration for creating AuthContext objects from user credentials.
  IvoaAuthScheme.AuthReader<T> | Knows how to acquire specific authentication information from an open URL connection.
  LoginProtocol | Defines a way to present credentials for the purpose of subsequent access to a service.
  UrlConnector | Defines how a connection is obtained from a URL.

- Class Summary
  Class | Description
  --- | ---
  AuthConnection | Aggregates a URLConnection and the AuthContext used to make the connection.
  AuthManager | Manages authentication.
  AuthStatus | Characterises the authentication associated with a connection.
  AuthTest |
  AuthUtil | Utilities used by authentication classes.
  BasicAuthScheme | Implements HTTP Basic Authentication as defined in RFC7617.
  BearerIvoaAuthScheme | IvoaAuthScheme concrete subclass for working with bearer tokens.
  Challenge | Represents and parses challenge specifications as defined by RFC7235.
  ContentType | Simple abstraction of MIME type.
  CookieIvoaAuthScheme | IvoaAuthScheme concrete subclass for working with cookies.
  Get | Retrieves a resource from a URL using the authentication system.
  IvoaAuthScheme | Partial AuthScheme implementation for standard SSO challenges.
  IvoaLoginProtocol | Provides SSO-compliant implementations of LoginProtocol.
  ProtectionSpace | Protection Space is a concept defined in RFC7235, aggregating the canonical root URI and an optional realm.
  Redirector | Defines how HTTP 3xx redirects are handled.
  UserInterface | Abstraction via which authentication classes can acquire credentials from the user.
  UserPass | Aggregates a username and password.
  X509IvoaAuthScheme | IvoaAuthScheme concrete subclass for working with X509 certificates.

- Enum Summary
  Enum | Description
  --- | ---
  AuthType | Enumerates different types of authentication available for a connection.

- Exception Summary
  Exception | Description
  --- | ---
  BadChallengeException | Exception indicating that an authentication challenge is badly formed, for instance missing parameters required by the scheme to which it is supposed to conform.

## Package uk.ac.starlink.auth Description

Manages authentication for HTTP(S) resources in accordance with VO standards.

The main user-visible class of this package is `AuthManager`. In general there is one user-visible instance of this class, obtained from `AuthManager.getInstance()`, and its `openStream` method can be used as a drop-in replacement for `URL.openStream()`; other methods are available for more nuanced HTTP interactions. If this is done, when a resource is encountered which issues a 401 or 403 challenge of a recognised type, the user will be queried for credentials, which are used to acquire the resource in question, and also for subsequent resources from the same domain, so that multiple logins to the same domain are not required.

Some details about the above outline:

- The meaning of the term "domain" is dependent on the authentication scheme in use.
- The authentication schemes are recognised according to the `WWW-Authenticate` challenge headers accompanying an HTTP response (typcally, though not necessarily, 401/403). These recognised schemes are implementations of the `AuthScheme` interface, of which several are provided, and of which a list may be configured on the `AuthManager`.
- The nature of the query to the user is determined by the `UserInterface` implementation installed on the AuthManager (see `AuthManager.setUserInterface`).

This package relies on VO standards that are still under discussion. The behaviour and user interface may change in future releases, and at time of writing not all data services that require or offer authentication advertise it in a way that AUTH can work with. It is hoped that authentication interoperability will improve in future versions of this library and of server-side software.

This package has no external dependencies, and may, depending on user demand, be released in future as a standalone package.

Since:
  31 Oct 2023