Package uk.ac.starlink.auth

# Class AuthUtil

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

public class AuthUtil extends Object
Utilities used by authentication classes.

Since:
  15 Jun 2020
Author:
  Mark Taylor

## Field Summary

Fields
Modifier and Type
Field
Description
`static final AuthScheme[]`
`ALL_SCHEMES`
List of all known authentication schemes.
`static final String`
`AUTH_HEADER`
RFC7235 Authorization header key "Authorization" (RFC 7235 sec 4.2).
`static final String`
`AUTHID_HEADER`
Header giving user authenticated ID "X-VO-Authenticated" (SSO_next).
`static final String`
`CHALLENGE_HEADER`
RFC 7235 challenge header key "WWW-Authenticate" (RFC 7235 sec 4.1).
`static final 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 final 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 final 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 final Charset`
`UTF8`
UTF-8 charset, guaranteed present.

## Method Summary

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

### UTF8

public static final Charset UTF8
UTF-8 charset, guaranteed present.

### CHALLENGE_HEADER

public static final 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 String AUTH_HEADER
RFC7235 Authorization header key "Authorization" (RFC 7235 sec 4.2).

See Also:
  - Constant Field Values

### AUTHID_HEADER

public static final String AUTHID_HEADER
Header giving user authenticated ID "X-VO-Authenticated" (SSO_next).

See Also:
  - Constant Field Values

### LOGSECRETS_PROP

public static final 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 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 Details

### getResponseCode

public static int getResponseCode(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(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 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 String authFailureMessage(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 String unNullString(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 String cookieLogText(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 HttpURLConnection postForm(URL url, Map<String,String> params) throws 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:
  `IOException`

### postForm

public static void postForm(HttpURLConnection hconn, Map<String,String> params) throws 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:
  `IOException`