Skip to content

Backend Connectivity

Much of the Foundation APIs' functionality is closely tied to the network communication to the backend servers. While Foundation APIs make it easier for developers to write applications that interact with servers, the APIs rely on the okHttp library for network communication. In order to give developers using the foundation library more control, the classes that make networking calls use the OkHttpClient that is directly given to them, or fall back to use the OkHttpClient that is set globally on ClientProvider.

Authentication

When a mobile application is configured with an authentication method, any access to the backend that uses REST API requires an authenticated session context or valid authentication headers for authentication. Authentication modules provided with the SDK help you with authentication.

Typical usage of OkHttpClient involves setting up an instance with the necessary authenticator or interceptor and passing that instance for OkHttpClient parameter in for any method calls that interact with mobile services.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
...
...
OkHttpClient mobileServiceNetworkingClient = new OkHttpClient.Builder()
    .addInterceptor(new SamlInterceptor(samlConfiguration))
    .cookieJar(new WebkitCookieJar())
    .build();
...
Settings mobileAppSettings = new Settings(mobileServiceNetworkingClient, mobileAppParameters);
mobileAppSettings.load();
...
...
RemoteNotificationClient mobileServicePushClient = new RemoteNotificationClient(mobileServiceNetworkingClient, mobileAppParameters);

Foreground Activity tracking

When establishing a new session, authentication modules may need to interact with the user to obtain credential information. To accomplish this, the modules need to know which activity is in the foreground. The Foundation component has a AppLifeCycleCallbackHandler singleton that is used to find which activity is in the foreground.

This callback handler must be registered using android.app.Application.registerActivityLifecycleCallbacks before any networking calls are made. Once registered, the ApplLifeCycleCallbackHandler will be able to keep track of the foreground activity.

See the Authentication topic for more information.

Mobile Service Http Headers

Some functionality in mobile services depend on special http headers.

Header Description
X-SMP-APPID The application id of the mobile app as configured in SAP Cloud Platform Mobile Services
X-SMP-DEVICEID Device Id
X-SMP-APP-VERSION The mobile application version
X-SMP-SDK-VERSION The version of the SDK the app is using

The presence of these headers in a request affects certain functions like logout. The foundation library provides AppHeadersInterceptor that automatically adds this header to the okHttp request if they are not already present.

To use this class, add an AppHeadersInterceptor. The following example shows how to use AppHeadersInterceptor in a "no-auth" configuration. However, please note that usually this interceptor is added in addition to the other authentication interceptors.

1
2
3
4
5
6
// Construct AppHeadersInterceptor using a SettingsParameter object.
AppHeadersInterceptor appHeadersInterceptor = AppHeadersInterceptor(settingsParameters);

OkHttpClient client = new OkHttpClient.Builder()
    .addInterceptor(appHeadersInterceptor)
    .build();

Cross-Site Request Forgery Protection

If you want to use Cross-Site Request Forgery (CSRF) protection for your application, first you must enable this feature in the mobile services cockpit. See: Defining Application Security for more information.

If CSRF protection is enabled, you need to send a X-CSRF-Token header for the modifying HTTP requests. The CsrfTokenInterceptor can automatically handle this for every request.

Note

The CSRF Protection option protects all services, such as registration, with CSRF tokens. Proxied endpoints are not protected, since they may be protected on the back end.

Basic usage

The following example shows how to add the CsrfTokenInterceptor if you have one root URL for every CSRF token request. The rootUrl parameter is the URL from which the CSRF token will be requested.

1
2
3
4
5
String rootUrl = "https://myserver.hana.ondemand.com/odata/applications/v4/myappid/";

OkHttpClient client = new OkHttpClient.Builder()
    .addInterceptor(new CsrfTokenInterceptor(rootUrl))
    .build()

Advanced usage

If you have multiple CSRF protected backends and these backends accept different CSRF tokens, you must implement a CsrfTokenUrlProvider to provide CSRF URL for different request URLs. For token storing, you should implement a CsrfTokenStore. A default implementation of the store is provided that will keep a token per host and port.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
public class MyCsrfTokenUrlProvider implements CsrfTokenUrlProvider {
    @Override
    public String getTokenUrl(String url) {
        // TODO: implement custom logic to create token URL from the request URL
        return ...
    }
}

public class MyCsrfTokenStore implements CsrfTokenStore {
    @Override
    public void setToken(String token, String url) {
        // TODO: implement
    }

    @Override
    public String getToken(String url) {
        // TODO: implement
        return ...
    }

    @Override
    public void deleteToken(String url) {
        // TODO: implement
    }
}

For more information about how this protection works, see the following topics: