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 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

Author:

Mark Taylor

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 String	ACCESSURL_PARAM Parameter name for the SSO login URL ("access_url").
static String	STANDARDID_PARAM Parameter name for the SSO login protocol standard id ("standard_id").

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	IvoaAuthScheme(String schemeName) Constructor.

Method Summary

Modifier and Type	Method and Description
ContextFactory	createContextFactory(Challenge challenge, 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, URL accessUrl, URL challengeUrl) Creates a ContextFactory for this scheme with a given login protocol instance.
String	getName() Returns a human-readable name identifying the authentication scheme implemented by this object.
static HttpURLConnection	getSuccessResponse(LoginProtocol loginProto, AuthScheme authScheme, 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, 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 String STANDARDID_PARAM

Parameter name for the SSO login protocol standard id ("standard_id").

See Also:

Constant Field Values

ACCESSURL_PARAM

public static final String ACCESSURL_PARAM

Parameter name for the SSO login URL ("access_url").

See Also:

Constant Field Values

Constructor Detail

IvoaAuthScheme

protected IvoaAuthScheme(String schemeName)

Constructor.

Parameters:

schemeName - scheme name as presented in challenge

Method Detail

getName

public 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,
                                           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,
                                                       URL accessUrl,
                                                       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 HttpURLConnection getSuccessResponse(LoginProtocol loginProto,
                                                   AuthScheme authScheme,
                                                   URL loginUrl,
                                                   UserInterface ui)
                                            throws 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:

IOException - if some communications failed; in this case retry is not expected to help

readAuth

public static <A> A readAuth(LoginProtocol loginProto,
                             AuthScheme authScheme,
                             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