uk.ac.starlink.auth

## Class IvoaAuthScheme

- java.lang.Object
- - uk.ac.starlink.auth.IvoaAuthScheme

- All Implemented Interfaces:
    AuthScheme
  Direct Known Subclasses:
    BearerIvoaAuthScheme, CookieIvoaAuthScheme, X509IvoaAuthScheme

      public abstract class IvoaAuthScheme
      extends java.lang.Object
      implements AuthScheme

  Partial AuthScheme implementation for standard SSO challenges. This provides a framework for AuthSchemes in which the login protocol, as defined by the `standard_id` challenge parameter, is separable from the type of AuthContext that is produced.

  It matches challenges of the form

  > `WWW-Authenticate: <schemeName> standard_id=<login-protocol-name>, access_url=<login-url>`

  Since:
    10 Dec 2021

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `IvoaAuthScheme.AuthReader<T>` Knows how to acquire specific authentication information from an open URL connection.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `ACCESSURL_PARAM` Parameter name for the SSO login URL ("access_url").
    `static java.lang.String` | `STANDARDID_PARAM` Parameter name for the SSO login protocol standard id ("standard_id").

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `IvoaAuthScheme(java.lang.String schemeName)` Constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `ContextFactory` | `createContextFactory(Challenge challenge, java.net.URL url)` Attempts to return an object that can take user input to generate an AuthContext based on a given challenge.
    `protected abstract ContextFactory` | `createContextFactory(LoginProtocol loginProto, java.net.URL accessUrl, java.net.URL challengeUrl)` Creates a ContextFactory for this scheme with a given login protocol instance.
    `java.lang.String` | `getName()` Returns a human-readable name identifying the authentication scheme implemented by this object.
    `static java.net.HttpURLConnection` | `getSuccessResponse(LoginProtocol loginProto, AuthScheme authScheme, java.net.URL loginUrl, UserInterface ui)` Utility method that attempts to acquire a successful HTTP response from a login URL given a login protocol, with credential input from the user.
    `static <A> A` | `readAuth(LoginProtocol loginProto, AuthScheme authScheme, java.net.URL loginUrl, UserInterface ui, IvoaAuthScheme.AuthReader<A> authReader)` Utility method that acquires authentication information from a login URL given a login protocol, with credential input from the user.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### STANDARDID_PARAM

          public static final java.lang.String STANDARDID_PARAM

      Parameter name for the SSO login protocol standard id ("standard_id").
      See Also:
        Constant Field Values

    - #### ACCESSURL_PARAM

          public static final java.lang.String ACCESSURL_PARAM

      Parameter name for the SSO login URL ("access_url").
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### IvoaAuthScheme

          protected IvoaAuthScheme(java.lang.String schemeName)

      Constructor.
      Parameters:
        `schemeName` - scheme name as presented in challenge

  - ### Method Detail

    - #### getName

          public java.lang.String getName()

      Description copied from interface: `AuthScheme`
      Returns a human-readable name identifying the authentication scheme implemented by this object. The returned string is typically the `auth-scheme` token from an RFC7235 challenge (for instance "Basic" for Basic authentication), but a different value may be used if required to distinguish it from other instances.
      Specified by:
        `getName` in interface `AuthScheme`
      Returns:
        name for this scheme

    - #### createContextFactory

          public ContextFactory createContextFactory(Challenge challenge,
                                                     java.net.URL url)
                                              throws BadChallengeException

      Description copied from interface: `AuthScheme`
      Attempts to return an object that can take user input to generate an AuthContext based on a given challenge. There are three possible outcomes of this method.
      - If this scheme recognises the challenge type and expects to be able to use it to generate AuthContexts, it should return a suitable ContextFactory
      - If this scheme recognises the challenge type but something is wrong with the challenge syntax (for instance missing parameters), it should throw a BadChallengeException, preferably with an explanatory message
      - If this scheme doesn't recognise the challenge type (for instance the challenge scheme string is not that implemented by this object), it should return null

      Note that this method should just examine the syntax of the supplied challenge; it is not expected to make network connections etc to determine if context creation will be successful.

      Specified by:
        `createContextFactory` in interface `AuthScheme`
      Parameters:
        `challenge` - authentication challenge object
        `url` - URL with which the challenge is associated
      Returns:
        context factory if challenge is recognised, or null if it isn't
      Throws:
        `BadChallengeException` - if the challenge scheme etc indicates that it is destined for this AuthScheme, but the challenge is not of the correct form

    - #### createContextFactory

          protected abstract ContextFactory createContextFactory(LoginProtocol loginProto,
                                                                 java.net.URL accessUrl,
                                                                 java.net.URL challengeUrl)
                                                          throws BadChallengeException

      Creates a ContextFactory for this scheme with a given login protocol instance. The return value should generally not be null, since if it's got as far as this call, the challenge looks like it's intended for this scheme.
      Parameters:
        `loginProto` - login protocol
        `accessUrl` - login URL
        `challengeUrl` - URL from which the challenge was received
      Returns:
        context factory
      Throws:
        `BadChallengeException`

    - #### getSuccessResponse

          public static java.net.HttpURLConnection getSuccessResponse(LoginProtocol loginProto,
                                                                      AuthScheme authScheme,
                                                                      java.net.URL loginUrl,
                                                                      UserInterface ui)
                                                               throws java.io.IOException

      Utility method that attempts to acquire a successful HTTP response from a login URL given a login protocol, with credential input from the user.

      This method manages user interaction by retrying if appropriate on 401/403 response codes, and returns a response with a 200 code. Authentication schemes for which this is not appropriate are free to manage user interaction without use of this method.

      Parameters:
        `loginProto` - login protocol
        `authScheme` - authentication scheme (used for messaging)
        `loginUrl` - URL at which credentials can be swapped for a token
        `ui` - user interface for supplying credentials
      Returns:
        200 response from login URL, or null if the user has declined to authenticate
      Throws:
        `java.io.IOException` - if some communications failed; in this case retry is not expected to help

    - #### readAuth

          public static <A> A readAuth(LoginProtocol loginProto,
                                       AuthScheme authScheme,
                                       java.net.URL loginUrl,
                                       UserInterface ui,
                                       IvoaAuthScheme.AuthReader<A> authReader)

      Utility method that acquires authentication information from a login URL given a login protocol, with credential input from the user.

      This method manages user interaction using `getSuccessResponse` and either succeeds in returning the desired information or returns null; in the latter case the user is messaged appropriately.

      Parameters:
        `loginProto` - login protocol
        `authScheme` - authentication scheme, used for messaging
        `loginUrl` - URL at which credentials can be swapped for a token
        `ui` - user interface for supplying credentials
        `authReader` - acquires auth info from a URL connection
      Returns:
        authentication information, or null if login failed