uk.ac.ed.epcc.webapp.servlet.session.token

Interface BearerTokenService

All Superinterfaces:

AppContextCleanup, AppContextService<BearerTokenService>, ScopeQuery

public interface BearerTokenService
extends AppContextService<BearerTokenService>, ScopeQuery

A AppContextService that encapsulates the policy for bearer token authentication. The model here is that bearer tokens can modify the session. Typically setting the current user. The role session roles may also be modified to fine tune permissions for example having a token that removes some of the users roles. Alternatively a user could not be set, with just session roles or explicit decoding of the access token used for access control. Normally bearer tokens will not establish a session but each request will authenticate. Different operations can then be restricted to different scopes (with a full impersonation scope being the default requirement). Normal user permissions will still apply but the token will only authenticate if it has at least one of the desired scopes. Different models could be mixed in the same application provided that the tokens always inhabit different realms.

Method Summary

Modifier and Type	Method and Description
ErrorCodes	getError() get an error to return with authentication request.
java.lang.String	getRealm() get the realm to request for bearer token authentication.
java.lang.String	getToken() get the successfully processed token.
default boolean	hasToken()
void	processToken(SessionService sess, java.lang.String token) Attempt to login with the specified token.
boolean	request() Should authentication be requested or errors reported.
java.util.Set<java.lang.String>	requestedScopes() Return the scopes requested during authentication.
void	setActive(boolean active) Enable/Disable bearer token authentication for this request.
void	setRealm(java.lang.String realm) set the realm to request if bearer authorisation is requested
void	setRequestable(boolean requestable) Can we request a token via an authorization header.
void	setRequiredScopes(java.lang.String[] scopes) restrict authentication to tokens that have one of the specified scopes.

Methods inherited from interface uk.ac.ed.epcc.webapp.AppContextService

getType

Methods inherited from interface uk.ac.ed.epcc.webapp.AppContextCleanup

cleanup

Methods inherited from interface uk.ac.ed.epcc.webapp.servlet.session.token.ScopeQuery

hasScope, hasScope

Method Detail

setActive

void setActive(boolean active)

Enable/Disable bearer token authentication for this request. the service will probably have a configurable default but this allows bearer tokens to be enabled/disabled for specific operations explicitly.

Parameters:

active -

setRealm

void setRealm(java.lang.String realm)

set the realm to request if bearer authorisation is requested

Parameters:

realm -

getRealm

java.lang.String getRealm()

get the realm to request for bearer token authentication. Realms are distinct token spaces. They may be set per url so only a sub-set of urls support bearer authentication. Not clear if the realm part of the standard is use much

Returns:

realm name or null

requestedScopes

java.util.Set<java.lang.String> requestedScopes()

Return the scopes requested during authentication. As these are optional in the request this may return null or an empty array. If specified the token should only authenticate if it has one of the specified scopes.

Returns:

String array of scopes

setRequiredScopes

void setRequiredScopes(java.lang.String[] scopes)

restrict authentication to tokens that have one of the specified scopes.

Parameters:

scopes -

getError

ErrorCodes getError()

get an error to return with authentication request. This should only return a non-null value after processToken(SessionService, String) has failed to validate a token.

Returns:

processToken

void processToken(SessionService sess,
                  java.lang.String token)

Attempt to login with the specified token. If this succeeds then the session should be modified appropriately (in principle we could support setting roles for anonymous users) request() should return false after this. If it fails then request() should return true and getError() may return a non-null value. This method MUST verify the permitted scopes of the token.

Parameters:

SessionService - to modify

token -

setRequestable

void setRequestable(boolean requestable)

Can we request a token via an authorization header. This allows an endpoint that primarily uses basic-auth but can process a token if present to suppress token requests.

Parameters:

requestable -

request

boolean request()

Should authentication be requested or errors reported. If this returns false then no authentication should be requested. This should return false after processToken(SessionService, String) has successfully processed a token. This should always return true if there is an error to report. If this returns false then bearer authentication will not be explicitly requested but a client can still provide a token spontaneously. A non-empty set of requested scopes are usually required fro authorisation to be requested.

Returns:

boolean

getToken

java.lang.String getToken()

get the successfully processed token. This is to support cases where the token needs to be decoded to obtain additional permission information.

Returns:

token

hasToken

default boolean hasToken()