public interface OAuth2ServerSupport
An instance of this type can be registered with a
CommonAuthFlowsConfigurator.supportOAuth2Using(OAuth2ServerSupport) method. From then on, the
conversation managers configured with the configurator will have OAuth2 server support enabled and will start a chosen OAuth2 code flow
whenever it's necessary.
Think of a class of this type as one that holds the OAuth2-related knowledge about certain servers and what to do to acquire the proper credentials to access resources on it. During the processing of a HTTP response, an object of this type is used as follows:
isSupportedEndpoint(Uri)method is called first to determine if this object supports the endpoint denoted by the given URI from which an HTTP response is currently being received. "Supports" here means that this object knows how to perform OAuth2 authorization against this endpoint. If this method returns false then this object will no longer take part in the flow.
canRecognizeChallengeInResponse(IReceiveEvent)is called after
isSupportedEndpoint(Uri)returned true for a particular URI. This method is responsible for detecting the OAuth2 challenge. The OAuth2 standard itself does not specify how should a server respond if it requires OAuth2 authentication. Using this method one can observe the HTTP status codes and the response headers using which this object can figure out if the response indeed represents a challenge and an OAuth2 authorization flow needs to start. If this method returns false then this object will not take part in the flow any more.
configForChallenge(IReceiveEvent)method is called to get the configuration using which the actual OAuth2 authorization is started. Refer to the documentation of this method for the details on what this actually means.
transformRequestUrlToStorageUrl(Uri)which helps to scope the tokens to particular endpoints. Read its documentation for the details.
Refer to the documentation of the methods of this interface to understand more when and how they are used in the overall OAuth2 flow implemented in this library.
For convenience, when working with SAP-specific server solutions the built-in
SAPOAuth2ServerSupport class can be an option. Refer to its
documentation to check which servers can it support and how to use it.
If you intend to implement your own server support object, take a look at the
CompletedFuture class which can be very handy if you'd like
to implement synchronous logic in the otherwise asynchronous methods, such as
|Modifier and Type||Method and Description|
This method attempts to determining whether the particular response is to be treated as an OAuth2 challenge, meaning that the targeted resource can be accessed only by acquiring an access token first.
During the OAuth2 authorization flow, if no access or refresh tokens are available, the authorization flow needs to be started.
Determines whether the endpoint specified by the given URL is one that this server support object can handle in terms of OAuth2 authentication.
After the access and refresh tokens have been acquired, the OAuth2 functionality of this library will make an attempt to persist said tokens via the
java.util.concurrent.Future<java.lang.Boolean> isSupportedEndpoint(android.net.Uri url)
However, repeatedly issuing time-consuming auto-detection mechanisms is discouraged as this method is invoked quite often during response processing.
During the analysis of a response, this library calls the registered server support objects one after the other until one is found that returns true from this method. From then on, the found server support object is marked as the winning one and is assumed to be able to assist in the remaining steps of the OAuth2 authorization flow. In other words, this is the first method that gets called on an object of this type and the rest of the methods are called only if this one returns true.
Mainly, this method is called whenever a HTTP response with status code between 400 and 500 is received as the first step of analyzing the response to decide if it's an OAuth2 challenge or not. Furthermore, this method is invoked before every request when attempting to find a suitable access token in the storage.
url- the URL of the endpoint concerning which an assessment is needed, must be non-null
boolean canRecognizeChallengeInResponse(IReceiveEvent response)
The way certain resource servers indicate that proper OAuth2 authorization is required might vary from server to server. This method holds the knowledge with respect to a particular set of servers and is capable of recognizing their specific way of telling the client that the proper access token must be obtained beforehand.
java.util.concurrent.Future<OAuth2Config> configForChallenge(IReceiveEvent challengeResponse)
If this method returns a cancellation via the
Future object then it is considered as a fatal error causing the
OAuth2 authorization to come to a full stop in the current conversation. The same error occurs if the returned configuration
is not one of the
OAuth2Config subclasses shipped with this library.
android.net.Uri transformRequestUrlToStorageUrl(android.net.Uri requestUrl)
OAuth2TokenStorageobject which was configured with the
CommonAuthFlowsConfiguratorobject (using the
CommonAuthFlowsConfigurator.setTokenStorage(OAuth2TokenStorage)method) which this support object has been registered with.
This method is called when this library attempts to either read or persist the tokens from/to a token storage. Implementors can use it to transform a specific request URL to another URL that then can be used as a key for storing and retrieving a token. Note that the transformed URL is purely virtual and serves only identification purposes, it is never attempted to be opened or accessed in any way.
The transformation realized by this method is what implicitly determines the scope of the tokens. For example, if
an implementor would like to store the tokens for
separately then the corresponding suffix should be trimmed off of the specified URL. Calling this method
http://example.com/foo/a/b/c/resource will yield
http://example.com/foo. Note that
the implementor must pay attention to the used URL scheme as the returned URL is used as-is as a key to store the tokens.
Returning the argument without modifications will cause the corresponding tokens to be used only when the request URL exactly matches the one which they have been acquired for.
requestUrl- the URL for which either a challenge has been received and tokens need to be read or OAuth2 authorization has completed successfully and the tokens must be stored, must be non-null