Show TOC

AuthProxy Plugin OverviewLocate this document in the navigation structure

The AuthProxy plugin provides the ability to make HTTPS requests with mutual authentication, and to optionally intercept all web requests to handle basic authentication and X509 certificate challenges. The plugin is supported for use with applications on the Android, iOS, and Windows 8.1 platforms.

The AuthProxy plugin handles specifying a certificate to include in an HTTPS request that identifies the client to the server, which allows the server to verify the identity of the client. An example of where you might need mutual authentication is in the onboarding process, when you register with an application, or, to access an OData producer. You can make HTTPS requests with no authentication, with basic authentication, or by using certificates. Supported certificate sources include file, system key manager, and Afaria.

Interception of Web Requests and Handling Challenges

The AuthProxy plugin can intercept all web and data requests and handle basic authentication and X509 certificate challenges inside Cordova's embedded WebView. By default the WebView does not handle these challenges correctly. When the server challenges the client side authentication, the AuthProxy plugin shows the proper UI to let the user enter a username/password, or select from a list of installed certificates, for answering the challenge. Interception of web requests with Android devices is not particularly recommended, unless you have such a requirement. You can enable or disable interception of web requests using the SAPKapselHandleHttpRequests preference setting in config.xml. The default value of this preference is false for backward compatibility. To enable the feature, edit config.xml and change the value to true.

On Android devices, there is the concept of an HTTPS conversion host, which is a list of host names for which AuthProxy always sends the request as HTTPS (regardless of the protocol of the intercepted request). The JavaScript can use HTTP in the URL (knowing that AuthProxy will send the request with HTTPS), and AuthProxy can still intercept the request and handle it. You can use the JavaScript function sap.AuthProxy.addHTTPSConversionHost(successCallback, errorCallback, url) to add a hostname to the list of HTTPS conversion hosts. Note that you do not need to do any configuration for SAP Fiori Client, which handles the HTTPS conversion host automatically.

For requests with basic authentication, if the credentials are not provided with the request, then a dialog box prompts the user to enter a user name and password, and the credentials are cached in the data vault and are automatically used when the server challenges again.

For requests with an X.509 certificate challenge, a dialog box shows the list of client certificates already installed, and the user can select the correct certificate to answer the the server side challenge. The user is only prompted again for a certificate if the user entered an invalid certificate. Note that on iOS, the client certificate must be already installed in the application's keychain, before running the application.

Note A best practice is to avoid synchronized requests in the JavaScript implementation, as these requests may timeout in certain cases. For this reason, the default value for the setting for handling synchronized requests is false. However, to allow synchronized requests, manually set the sapkapselhandlehttpsyncrequests preference to true in config.xml
Sending Requests
There are these functions for sending requests:
  • get = function (url, header, successCB, errorCB, user, password, timeout, certSource). This is a convenience function and provides no additional functionality compared to the sendRequest function. It just calls the sendRequest function with the method set to GET and no requestBody.
  • sendRequest = function (method, url, header, requestBody, successCB, errorCB, user, password, timeout, certSource).
  • sendRequest2 = function (method, url, header, requestBody, successCB, errorCB, [timeout], [authConfig] )
Constructor Functions
There are three constructor functions to make objects that you can use for certificates:
  • CertificateFromFile = function (Path, Password, CertificateKey)
  • CertificateFromLogonManager = function( AppID ). Supported on iOS and Android.
  • CertificateFromStore = function (CertificateKey)
Note The success callback is called upon any response from the server, so be sure to check the status on the response.
Domain Whitelisting

Kapsel plugins support Apache Cordova's domain whitelisting model. Whitelisting allows you to control access to external network resources. Apache Cordova whitelisting allows you to whitelist individual network resources (URLs), for example, http://www.google.com.

For information about the whitelist rules, see http://docs.phonegap.com/en/3.3.0/guide_appdev_whitelist_index.md.htmlInformation published on non-SAP site.