OAuth2ServerSupport

All Known Implementing Classes:

SAPOAuth2ServerSupport
```
public interface OAuth2ServerSupport
```
This inteface is implemented by those classes which encompass the logic how the OAuth2 authorization flow is to be configured and executed against one or more resource servers protected with OAuth2.
An instance of this type can be registered with a CommonAuthFlowsConfigurator object via the 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:
1. The 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.
2. The 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.
3. After a challenge has been detected using canRecognizeChallengeInResponse(IReceiveEvent), the 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.
4. When the OAuth2 authorization flow completes successfully then the acquired access and refresh tokens needs to be stored for subsequent requests. This is done with the help of the 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 isSupportedEndpoint(Uri) and configForChallenge(IReceiveEvent).
See Also:

SAPOAuth2ServerSupport, CompletedFuture

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`boolean`	`canRecognizeChallengeInResponse(IReceiveEvent response)` 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.
`java.util.concurrent.Future<OAuth2Config>`	`configForChallenge(IReceiveEvent challengeResponse)` During the OAuth2 authorization flow, if no access or refresh tokens are available, the authorization flow needs to be started.
`java.util.concurrent.Future<java.lang.Boolean>`	`isSupportedEndpoint(android.net.Uri url)` Determines whether the endpoint specified by the given URL is one that this server support object can handle in terms of OAuth2 authentication.
`android.net.Uri`	`transformRequestUrlToStorageUrl(android.net.Uri requestUrl)` 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 `OAuth2TokenStorage` object which was configured with the `CommonAuthFlowsConfigurator` object (using the `CommonAuthFlowsConfigurator.setTokenStorage(OAuth2TokenStorage)` method) which this support object has been registered with.

- Method Detail
  - isSupportedEndpoint
```
java.util.concurrent.Future<java.lang.Boolean> isSupportedEndpoint(android.net.Uri url)
```
    Determines whether the endpoint specified by the given URL is one that this server support object can handle in terms of OAuth2 authentication. This method is asynchronous which allows implementations to employ complex mechanisms (for ex. pinging the server) to auto-detect whether the targeted endpoint is on a supported server or not.
    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.
    
    Parameters:
    
    url - the URL of the endpoint concerning which an assessment is needed, must be non-null
    
    Returns:
    
    the future to be returned with true or false, depending on whether the endpoint is a supported one or not
  - canRecognizeChallengeInResponse
```
boolean canRecognizeChallengeInResponse(IReceiveEvent response)
```
    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. The response URL is one that is found to be supported as of isSupportedEndpoint(Uri).
    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.
    
    Returns:
    
    true if the specified response indicates that its an OAuth2 challenge, false otherwise
  - configForChallenge
```
java.util.concurrent.Future<OAuth2Config> configForChallenge(IReceiveEvent challengeResponse)
```
    During the OAuth2 authorization flow, if no access or refresh tokens are available, the authorization flow needs to be started. This method is invoked to return the specific configuration object containing important parameters such as the authorization endpoint, token endpoint, client IDs and secrets, etc..
    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.
  - transformRequestUrlToStorageUrl
```
android.net.Uri transformRequestUrlToStorageUrl(android.net.Uri requestUrl)
```
    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 OAuth2TokenStorage object which was configured with the CommonAuthFlowsConfigurator object (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 example.com/foo/... and example.com/bar/... URLs separately then the corresponding suffix should be trimmed off of the specified URL. Calling this method then with 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.
    
    This library ensures that tokens acquired with the help of different OAuth2ServerSupport objects cannot be intermixed with each other within a single OAuth2TokenStorage object.
    
    Parameters:
    
    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
    
    Returns:
    
    the transformed URL to use as a key when persisting or reading access and refresh tokens, always non-null

Interface OAuth2ServerSupport

Method Summary

Method Detail

isSupportedEndpoint

canRecognizeChallengeInResponse

configForChallenge

transformRequestUrlToStorageUrl