uk.ac.starlink.auth

## Class AuthUtil

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

-     public class AuthUtil
      extends java.lang.Object

  Utilities used by authentication classes.
  Since:
    15 Jun 2020

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static AuthScheme[]` | `ALL_SCHEMES` List of all known authentication schemes.
    `static java.lang.String` | `AUTH_HEADER` RFC7235 Authorization header key "Authorization" (RFC 7235 sec 4.2).
    `static java.lang.String` | `AUTHID_HEADER` Header giving user authenticated ID "X-VO-Authenticated" (SSO_next).
    `static java.lang.String` | `CHALLENGE_HEADER` RFC 7235 challenge header key "WWW-Authenticate" (RFC 7235 sec 4.1).
    `static AuthScheme[]` | `DFLT_SCHEMES` Default list of authentication schemes in order of preference.
    `static boolean` | `LOG_SECRETS` Global config: if true, passwords etc may be logged by logger.
    `static java.lang.String` | `LOGSECRETS_PROP` Name of system property "auth.logsecrets" which if set "true" will allow reporting of sensitive information such as passwords through the logging system.
    `static java.lang.String` | `SCHEMES_PROP` Name of system property "auth.schemes" giving a comma-separated list of AuthScheme instances or classnames, which overrides the default list of authentication schemes in order of preference.
    `static java.nio.charset.Charset` | `UTF8` UTF-8 charset, guaranteed present.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.lang.String` | `authFailureMessage(java.net.HttpURLConnection hconn)` Prepares a short user-readable message indicating the state of a connection that failed because of auth issues.
    `static java.lang.String` | `cookieLogText(java.net.HttpCookie cookie)` Returns a string suitable for reporting through the logging system to represent a cookie.
    `static java.lang.String` | `getAuthenticatedId(AuthConnection aconn)` Returns the authenticated user ID recorded in the headers of a URL connection.
    `static Challenge[]` | `getChallenges(java.net.URLConnection conn)` Extracts challenges from an HTTP response.
    `static AuthScheme[]` | `getDefaultSchemes()` Returns a default list of AuthSchemes in order of preference.
    `static int` | `getResponseCode(java.net.URLConnection conn)` Returns the HTTP response code from a URL connection.
    `static void` | `postForm(java.net.HttpURLConnection hconn, java.util.Map<java.lang.String,java.lang.String> params)` Posts name=value pairs to an HTTP connection in `application/x-www-form-urlencoded` format.
    `static java.net.HttpURLConnection` | `postForm(java.net.URL url, java.util.Map<java.lang.String,java.lang.String> params)` Posts name=value pairs over HTTP in `application/x-www-form-urlencoded` format.
    `static java.lang.String` | `unNullString(java.lang.String txt)` Returns the input string, unless it's null, in which case it returns the empty string.

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

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

- - ### Field Detail

    - #### UTF8

          public static final java.nio.charset.Charset UTF8

      UTF-8 charset, guaranteed present.

    - #### CHALLENGE_HEADER

          public static final java.lang.String CHALLENGE_HEADER

      RFC 7235 challenge header key "WWW-Authenticate" (RFC 7235 sec 4.1).
      See Also:
        Constant Field Values

    - #### AUTH_HEADER

          public static final java.lang.String AUTH_HEADER

      RFC7235 Authorization header key "Authorization" (RFC 7235 sec 4.2).
      See Also:
        Constant Field Values

    - #### AUTHID_HEADER

          public static final java.lang.String AUTHID_HEADER

      Header giving user authenticated ID "X-VO-Authenticated" (SSO_next).
      See Also:
        Constant Field Values

    - #### LOGSECRETS_PROP

          public static final java.lang.String LOGSECRETS_PROP

      Name of system property "auth.logsecrets" which if set "true" will allow reporting of sensitive information such as passwords through the logging system.
      See Also:
        Constant Field Values

    - #### LOG_SECRETS

          public static boolean LOG_SECRETS

      Global config: if true, passwords etc may be logged by logger.

    - #### SCHEMES_PROP

          public static final java.lang.String SCHEMES_PROP

      Name of system property "auth.schemes" giving a comma-separated list of AuthScheme instances or classnames, which overrides the default list of authentication schemes in order of preference.
      See Also:
        Constant Field Values

    - #### DFLT_SCHEMES

          public static final AuthScheme[] DFLT_SCHEMES

      Default list of authentication schemes in order of preference.

    - #### ALL_SCHEMES

          public static final AuthScheme[] ALL_SCHEMES

      List of all known authentication schemes.

  - ### Method Detail

    - #### getResponseCode

          public static int getResponseCode(java.net.URLConnection conn)

      Returns the HTTP response code from a URL connection. In case of error (including if the connection is not an HTTP one), -1 is returned.
      Parameters:
        `conn` - URL connection
      Returns:
        HTTP response code, or -1

    - #### getChallenges

          public static Challenge[] getChallenges(java.net.URLConnection conn)

      Extracts challenges from an HTTP response.
      Parameters:
        `conn` - open URL connection (typically, but not necessarily, 401)
      Returns:
        challenges indicated in WWW-Authenticate header(s)

    - #### getAuthenticatedId

          public static java.lang.String getAuthenticatedId(AuthConnection aconn)

      Returns the authenticated user ID recorded in the headers of a URL connection. This attempts to read the non-standard header "X-VO-Authenticated". If the header is absent, some placeholder non-null value is returned. If the connection does not look like an authenticated one, null is returned.
      Parameters:
        `aconn` - connection to endpoint expected to yield an auth ID
      Returns:
        real or placeholder authenticated user ID, or null

    - #### authFailureMessage

          public static java.lang.String authFailureMessage(java.net.HttpURLConnection hconn)

      Prepares a short user-readable message indicating the state of a connection that failed because of auth issues.
      Parameters:
        `hconn` - open connection, should usually be 401 or 403
      Returns:
        short message

    - #### unNullString

          public static java.lang.String unNullString(java.lang.String txt)

      Returns the input string, unless it's null, in which case it returns the empty string.
      Parameters:
        `txt` - string
      Returns:
        non-null equivalent string

    - #### cookieLogText

          public static java.lang.String cookieLogText(java.net.HttpCookie cookie)

      Returns a string suitable for reporting through the logging system to represent a cookie. Depending on the value of `LOG_SECRETS`, it will or will not contain sensitive information.
      Parameters:
        `cookie` - cookie to represent
      Returns:
        loggable text

    - #### getDefaultSchemes

          public static AuthScheme[] getDefaultSchemes()

      Returns a default list of AuthSchemes in order of preference. This is affected by the `SCHEMES_PROP` system property; if that is not set, it will take the value of `DFLT_SCHEMES`.
      Returns:
        default authentication scheme list

    - #### postForm

          public static java.net.HttpURLConnection postForm(java.net.URL url,
                                                            java.util.Map<java.lang.String,java.lang.String> params)
                                                     throws java.io.IOException

      Posts name=value pairs over HTTP in `application/x-www-form-urlencoded` format.
      Parameters:
        `url` - destination URL
        `params` - map of name->value pairs
      Returns:
        an opened HTTP connection from which exit status and output content can be read
      Throws:
        `java.io.IOException`

    - #### postForm

          public static void postForm(java.net.HttpURLConnection hconn,
                                      java.util.Map<java.lang.String,java.lang.String> params)
                               throws java.io.IOException

      Posts name=value pairs to an HTTP connection in `application/x-www-form-urlencoded` format. The supplied connection can be the result of a call to `URL.openConnection()`, with or without some customization.
      Parameters:
        `hconn` - unopened connection
        `params` - map of name->value pairs
      Throws:
        `java.io.IOException`