Namespace: AuthProxy

sap. AuthProxy

The AuthProxy plugin provides the ability to make HTTPS requests with mutual authentication.

The regular XMLHttpRequest does not support mutual authentication. The AuthProxy plugin allows you to specify a certificate to include in an HTTPS request to identify the client to the server. This allows the server to verify the identity of the client. An example of where you might need mutual authenticaion is the onboarding process to register with an application, or, to access an OData producer. This occurs mostly in Business to Business (B2B) applications. This is different from most business to consumer (B2C) web sites where it is only the server that authenticates itself to the client with a certificate.

Adding and Removing the AuthProxy Plugin
The AuthProxy plugin is added and removed using the Cordova CLI.

To add the AuthProxy plugin to your project, use the following command:
cordova plugin add kapsel-plugin-authproxy

To remove the AuthProxy plugin from your project, use the following command:
cordova plugin rm kapsel-plugin-authproxy

Classes

CertificateFromFile
CertificateFromLogonManager
CertificateFromStore

Namespaces

OAuth2
OTP
SAML2

Members

(constant) ERR_CERTIFICATE_ALIAS_NOT_FOUND :number

Constant indicating the certificate with the given alias could not be found. Used as a possible value for the errorCode in sap.AuthProxy~errorCallback.
Type:
  • number

(constant) ERR_CERTIFICATE_FILE_NOT_EXIST :number

Constant indicating the certificate file could not be found. Used as a possible value for the errorCode in sap.AuthProxy~errorCallback.
Type:
  • number

(constant) ERR_CERTIFICATE_INVALID_FILE_FORMAT :number

Constant indicating incorrect certificate file format. Used as a possible value for the errorCode in sap.AuthProxy~errorCallback.
Type:
  • number

(constant) ERR_CLIENT_CERTIFICATE_VALIDATION :number

Constant indicating the provided certificate failed validation on the server side. Used as a possible value for the errorCode in sap.AuthProxy~errorCallback.
Type:
  • number

(constant) ERR_DOMAIN_WHITELIST_REJECTION :number

Constant indicating cordova domain whitelist rejection error while sending request to server. Used as a possible value for the errorCode in sap.AuthProxy~errorCallback.
Type:
  • number

(constant) ERR_FILE_CERTIFICATE_SOURCE_UNSUPPORTED :number

Constant indicating the certificate from file is not supported on the current platform. Used as a possible value for the errorCode in sap.AuthProxy~errorCallback.
Type:
  • number

(constant) ERR_GET_CERTIFICATE_FAILED :number

Constant indicating failure in getting the certificate. Used as a possible value for the errorCode in sap.AuthProxy~errorCallback.
Type:
  • number

(constant) ERR_HTTP_TIMEOUT :number

Constant indicating timeout error while connecting to the server. Used as a possible value for the errorCode in sap.AuthProxy~errorCallback.
Type:
  • number

(constant) ERR_INVALID_PARAMETER_VALUE :number

Constant indicating the operation failed due to an invalid parameter (for example, a string was passed where a number was required). Used as a possible value for the errorCode in sap.AuthProxy~errorCallback.
Type:
  • number

(constant) ERR_LOGON_MANAGER_CERTIFICATE_METHOD_NOT_AVAILABLE :number

Constant indicating the logon manager certifciate method is not available. Used as a possible value for the errorCode in sap.AuthProxy~errorCallback.
Type:
  • number

(constant) ERR_LOGON_MANAGER_CORE_NOT_AVAILABLE :number

Constant indicating the logon manager core library is not available. Getting this error code means you tried to use Logon plugin features (for example, a certificate from Logon) without adding the Logon plugin to the app. A possible value for the errorCode in sap.AuthProxy~errorCallback.
Type:
  • number

(constant) ERR_MISSING_PARAMETER :number

Constant indicating the operation failed because of a missing parameter. Used as a possible value for the errorCode in sap.AuthProxy~errorCallback.
Type:
  • number

(constant) ERR_NO_SUCH_ACTION :number

Constant indicating there is no such Cordova action for the current service. When a Cordova plugin calls into native code it specifies an action to perform. If the action provided by the JavaScript is unknown to the native code this error occurs. This error should not occur as long as authproxy.js is unmodified. Used as a possible value for the errorCode in sap.AuthProxy~errorCallback.
Type:
  • number

(constant) ERR_SERVER_CERTIFICATE_VALIDATION :number

Constant indicating the server certificate failed validation on the client side. This is likely because the server certificate is self-signed, or not signed by a well-known certificate authority. This constant is used as a possible value for the errorCode in sap.AuthProxy~errorCallback.
Type:
  • number

(constant) ERR_SERVER_REQUEST_FAILED :number

Constant indicating the server request failed. Used as a possible value for the errorCode in sap.AuthProxy~errorCallback.
Type:
  • number

(constant) ERR_SYSTEM_CERTIFICATE_SOURCE_UNSUPPORTED :number

Constant indicating the certificate from the system keystore is not supported on the current platform. Used as a possible value for the errorCode in sap.AuthProxy~errorCallback.
Type:
  • number

(constant) ERR_UNKNOWN :number

Constant indicating the operation failed with unknown error. Used as a possible value for the errorCode in sap.AuthProxy~errorCallback.
Type:
  • number

Methods

clearClientCertPreferences(successCallback, errorCallback)

Clears the client certificate preferences stored in response to proceeding/cancelling client cert requests. Only available for Android.
Parameters:
Name Type Description
successCallback sap.AuthProxy~successCallback Callback method upon success.
errorCallback sap.AuthProxy~errorCallback Callback method upon failure.

deleteCertificateFromStore(successCB, errorCBopt, certificateKey)

Delete a cached certificate from the keychain. iOS clients always checks the cached certificate first to see if it is available before loading the certificate from the file system. If the cached certificate is no longer valid, use this method to delete it from the keychain.
Only supported on iOS platform, NOT Android.
Parameters:
Name Type Attributes Description
successCB sap.AuthProxy~deleteCertificateSuccessCallback Callback method upon success.
errorCB sap.AuthProxy~errorCallback <optional>
Callback method upon failure.
certificateKey string The key of the certificate to be deleted.
Example
var successCB = function(){
    alert("certificate successfully deleted.");
}
var errorCB = function(error){
    alert("error deleting certificate: " + JSON.stringify(error));
}
sap.AuthProxy.deleteCertificateFromStore(successCB, errorCB, "certificateKeyToDelete");

generateODataHttpClient()

Generates an OData client that uses the AuthProxy plugin to make requests. This is useful if you are using Datajs, but want to make use of the certificate features of AuthProxy. Datajs is a javascript library useful for accessing OData services. Datajs has a concept of an HttpClient, which does the work of making the request. This function generates an HttpClient that you can specify to Datajs so you can provide client certificates for requests. If you want to use the generated HTTP client for all future Datajs requests, you can do that by setting the OData.defaultHttpClient property to the return value of this function. Once that is done, then doing OData stuff with Datajs is almost exactly the same, but you can add a certificateSource to a request.
Example
OData.defaultHttpClient = sap.AuthProxy.generateODataHttpClient();

// Using a certificate from file, for example.
fileCert = new sap.AuthProxy.CertificateFromFile("mnt/sdcard/cert.p12", "password", "certKey");

// This is the same request object you would have created if you were just using Datajs, but now
// you can add the extra 'certificateSource' property.
var createRequest = {
    requestUri: "http://www.example.com/stuff/etc/example.svc",
    certificateSource : fileCert,
    user : "username",
    password : "password",
    method : "POST",
    data:
    {
         Description: "Created Record",
         CategoryName: "Created Category"
    }
}

// Use Datajs to send the request.
OData.request( createRequest, successCallback, failureCallback );

generateODataHttpClient2()

Generates an OData client that uses the AuthProxy plugin's sendRequest2 method. This method is similar to sap.AuthProxy.generateODataHttpClient, but it replaces user, password, and certificateSource parameters with the new authConfig parameter as required by Authproxy's sendRequest2 method.
Example
OData.defaultHttpClient = sap.AuthProxy.generateODataHttpClient2();

The below sample use a certificate from file, and a preset user and password.
var request = {
                  authConfig : {basic:
                                  [
                                     {type:"preset", data:{user:"smptester", password:"SMP_t3st3r"}}
                                  ],
                                clientCert:
                                  [
                                      {type: "file", data: { path:"cert.p12", password:"password$", certificateKey:"client"}}
                                  ]
                                },
                  requestUri : "http://www.example.com/stuff/etc/example.svc",
                  method : "GET"
  };
  odatajs.oData.request(request, successCallback, errorCallback, null, httpClient);
The below sample use a certificate from file, and allow user to input credential at runtime.
var request = {
                  authConfig : {basic:
                                  [
                                      {type:"user"}
                                  ],
                                clientCert:
                                  [
                                      {type: "file", data: { path:"cert.p12", password:"password$", certificateKey:"client"}}
                                  ]
                                },
                  requestUri : "http://www.example.com/stuff/etc/example.svc",
                  method : "GET"
  };
  odatajs.oData.request(request, successCallback, errorCallback, null, httpClient);

get(url, header, successCB, errorCB, useropt, passwordopt, timeoutopt, certSourceopt) → {function}

Send an HTTP(S) GET request to a remote server. This is a convenience function that simply calls sap.AuthProxy#sendRequest with "GET" as the method and null for the request body. All given parameters are passed as-is to sap.AuthProxy.sendRequest. The success callback is invoked upon any response from the server. Even responses not generally considered to be successful (such as 404 or 500 status codes) will result in the success callback being invoked. The error callback is reserved for problems that prevent the AuthProxy from creating the request or contacting the server. It is, therefore, important to always check the status property on the object given to the success callback.
Parameters:
Name Type Attributes Description
url string The URL against which to make the request.
header Object HTTP header to send to the server. This is an Object. Can be null.
successCB sap.AuthProxy~successCallback Callback method invoked upon a response from the server.
errorCB sap.AuthProxy~errorCallback Callback method invoked in case of failure.
user string <optional>
User ID for basic authentication.
password string <optional>
User password for basic authentication.
timeout number <optional>
Timeout setting in seconds. Default timeout is 60 seconds. A value of 0 means there is no timeout.
certSource Object <optional>
Certificate description object. It can be one of sap.AuthProxy#CertificateFromFile, sap.AuthProxy#CertificateFromStore, or sap.AuthProxy#CertificateFromLogonManager.
Returns:
A JavaScript function object to abort the operation. Calling the abort function results in neither the success or error callback being invoked for the original request (excepting the case where the success or error callback was invoked before calling the abort functino). Note that the request itself cannot be unsent, and the server will still receive the request - the JavaScript will just not know the results of that request.
Type
function
Example
var successCB = function(serverResponse){
    alert("Status: " + JSON.stringify(serverResponse.status));
    alert("Headers: " + JSON.stringify(serverResponse.headers));
    if (serverResponse.responseText){
        alert("Response: " + JSON.stringify(serverResponse.responseText));
    }
}
var errorCB = function(errorObject){
    alert("Error making request: " + JSON.stringify(errorObject));
}

// To send a GET request to server, call the method
var abortFunction = sap.AuthProxy.get("http://www.example.com", null, successCB, errorCB);

// An example of aborting the request
abortFunction();

// To send a GET request to the server with headers, call the method
sap.AuthProxy.get("http://www.example.com", {HeaderName : "Header value"}, successCB, errorCB);

// To send a GET request to the server with basic authentication, call the method
sap.AuthProxy.get("https://www.example.com", headers, successCB, errorCB, "username", "password");

// To send a GET request to the server with mutual authentication, call the method
sap.AuthProxy.get("https://www.example.com", headers, successCB, errorCB, null, null, 0, 
    new sap.AuthProxy.CertificateFromLogonManager("theAppId"));

sendRequest(method, url, header, requestBody, successCB, errorCB, useropt, passwordopt, timeoutopt, certSourceopt) → {function}

Send an HTTP(S) request to a remote server. This function is the centerpiece of the AuthProxy plugin. It will handle mutual authentication if a certificate source is provided. The success callback is invoked upon any response from the server. Even responses not generally considered to be successful (such as 404 or 500 status codes) will result in the success callback being invoked. The error callback is reserved for problems that prevent the AuthProxy from creating the request or contacting the server. It is therefore important to always check the status property on the object given to the success callback.
Parameters:
Name Type Attributes Description
method string Standard HTTP request method name.
url string The HTTP URL with format http(s)://[user:password]@hostname[:port]/path.
header Object HTTP header to send to the server. This is an Object. Can be null.
requestBody string Data to send to the server with the request. Can be null.
successCB sap.AuthProxy~successCallback Callback method invoked upon a response from the server.
errorCB sap.AuthProxy~errorCallback Callback method invoked in case of failure.
user string <optional>
User ID for basic authentication.
password string <optional>
User password for basic authentication.
timeout number <optional>
Timeout setting in seconds. Default timeout is 60 seconds. A value of 0 means there is no timeout.
certSource Object <optional>
Certificate description object. It can be one of sap.AuthProxy#CertificateFromFile, sap.AuthProxy#CertificateFromStore, or sap.AuthProxy#CertificateFromLogonManager.
Returns:
A JavaScript function object to abort the operation. Calling the abort function results in neither the success or error callback being invoked for the original request (excepting the case where the success or error callback was invoked before calling the abort function). Note that the request itself cannot be unsent, and the server will still receive the request - the JavaScript will just not know the results of that request.
Type
function
Example
// callbacks
var successCB = function(serverResponse){
    alert("Status: " + JSON.stringify(serverResponse.status));
    alert("Headers: " + JSON.stringify(serverResponse.headers));
    alert("Response: " + JSON.stringify(serverResponse.response));
}
var errorCB = function(errorObject){
    alert("Error making request: " + JSON.stringify(errorObject));
}

// To send a post request to the server, call the method
var abortFunction = sap.AuthProxy.sendRequest("POST", "http://www.google.com", null, "THIS IS THE BODY", successCB, errorCB);
// An example of aborting the request
abortFunction();

// To send a post request to the server with headers, call the method
sap.AuthProxy.sendRequest("POST", url, {HeaderName : "Header value"}, "THIS IS THE BODY", successCB, errorCB);

// To send a post request to the server with basic authentication, call the method
sap.AuthProxy.sendRequest("POST", url, headers, "THIS IS THE BODY", successCB, errorCB, "username", "password");

// To send a post request to the server with mutual authentication, call the method
sap.AuthProxy.sendRequest("POST", "https://hostname", headers, "THIS IS THE BODY", successCB, errorCB, null, 
    null, 0, new sap.AuthProxy.CertificateFromLogonManager("theAppId"));

sendRequest2(method, url, header, requestBody, successCB, errorCB, timeoutopt, authConfigopt, forCheckReachabilityopt) → {function}

Send an HTTP(S) request to a remote server. This function is the centerpiece of the AuthProxy plugin. It will handle mutual authentication if a certificate source is provided. The success callback is invoked upon any response from the server. Even responses not generally considered to be successful (such as 404 or 500 status codes) will result in the success callback being invoked. The error callback is reserved for problems that prevent the AuthProxy from creating the request or contacting the server. It is therefore important to always check the status property on the object given to the success callback.
Parameters:
Name Type Attributes Description
method string Standard HTTP request method name.
url string The HTTP URL with format http(s)://hostname[:port]/path.
header Object HTTP header to send to the server. This is an Object. Can be null.
requestBody string Data to send to the server with the request. Can be null.
successCB sap.AuthProxy~successCallback Callback method invoked upon a response from the server.
errorCB sap.AuthProxy~errorCallback Callback method invoked in case of failure.
timeout number <optional>
Timeout setting in seconds. Default timeout is 60 seconds. A value of 0 means there is no timeout.
authConfig Object <optional>
authentication configuration object.
forCheckReachability Object <optional>
To check server reachability, set the parameter to an object, otherwise setting it to null
Returns:
A JavaScript function object to abort the operation. Calling the abort function results in neither the success or error callback being invoked for the original request (excepting the case where the success or error callback was invoked before calling the abort function). Note that the request itself cannot be unsent, and the server will still receive the request - the JavaScript will just not know the results of that request.
Type
function
Example
// callbacks
var successCB = function(serverResponse){
    alert("Status: " + JSON.stringify(serverResponse.status));
    alert("Headers: " + JSON.stringify(serverResponse.headers));
    alert("Response: " + JSON.stringify(serverResponse.response));
}
var errorCB = function(errorObject){
    alert("Error making request: " + JSON.stringify(errorObject));
}

// To send a post request to the server, call the method
var abortFunction = sap.AuthProxy.sendRequest("POST", "http://www.google.com", null, "THIS IS THE BODY", successCB, errorCB);
// An example of aborting the request
abortFunction();

// To send a post request to the server with headers, call the method
sap.AuthProxy.sendRequest("POST", url, {HeaderName : "Header value"}, "THIS IS THE BODY", successCB, errorCB);

// To send a post request to the server with preset basic authentication configuration, call the method
var authConfig = {basic:[{type:"preset", data:{user:"myname", password:"mypassword"}}, {type:"user"}]};
sap.AuthProxy.sendRequest("POST", url, headers, "THIS IS THE BODY", successCB, errorCB, null, authConfig);

// To send a post request to the server with mutual authentication selected by user, call the method
var authConfig = {clientcert:[{type:"user"}]};
sap.AuthProxy.sendRequest("POST", "https://hostname", null, "THIS IS THE BODY", successCB, errorCB, null, authConfig);

setAutoSelectCertificateConfig(successCB, errorCBopt, autoSelectSingleCert, authproxyKeychainGroup)

set configuration for automatically select client certificate
Only supported on iOS platform, NOT Android.
Parameters:
Name Type Attributes Description
successCB sap.AuthProxy~successCallback Callback method upon success.
errorCB sap.AuthProxy~errorCallback <optional>
Callback method upon failure.
autoSelectSingleCert bool enable or disable automatically select the single client certificate
authproxyKeychainGroup string optional parameter to specify the keychain group used to load the client certificate. The values of this parameter can be set as: all: loading client cert from all keychain groups; self: loading client cert only from the default keychain group; none: do not loading client cert by authproxy
Example
var successCB = function(){
    console.log("setAutoSelectCertificateConfig called successfully.");
}
var errorCB = function(error){
    console.log("error calling setAutoSelectCertificateConfig: " + JSON.stringify(error));
}
sap.AuthProxy.setAutoSelectCertificateConfig(successCB, errorCB, enableAutoSelectSingleCert);

setSAMLChallengeHandler(successCallback, errorCallback, samlChallengeCallback, samlConfig)

This method is used for handling SAML challenges and only applies to XMLHttpRequest requests.
Parameters:
Name Type Description
successCallback sap.AuthProxy~successCallback Callback method upon success.
errorCallback sap.AuthProxy~errorCallback Callback method upon failure.
samlChallengeCallback sap.AuthProxy~samlChallengeCallback Callback method upon SAML challenge.
samlConfig Object Configuration for SAML authentication.
Deprecated:
  • Yes
Example
// Below is a sample context variable from which the samlConfig is defined.
var context = {
  "serverHost" = "example.com",
  "https" : "true",
  "serverPort" : "8081",
  "auth": [ {
      "type": "saml2.web.post",
      "config": {
          "saml2.web.post.authchallengeheader.name": "com.sap.cloud.security.login",
          "saml2.web.post.finish.endpoint.uri": "/SAMLAuthLauncher",
          "saml2.web.post.finish.endpoint.redirectparam": "finishEndpointParam"
      }
  } ]
};

// callbacks
var successCallback = function(serverResponse){
  console.log("EventLogging: setSAMLChallengeHandler");
}
var errorCallback = function(errorObject){
  console.log("EventLogging: failed to setSAMLChallengeHandler");
}
var mySAMLHandler = function(url){
  console.log("EventLogging: mySAMLHandler with request url " + url);
}
sap.AuthProxy.setSAMLChallengeHandler(successCallback, errorCallback, mySAMLHandler, context.auth[0].config); 

Type Definitions

deleteCertificateSuccessCallback()

Callback function that is invoked upon successfully deleting a certificate from the store.

errorCallback(errorObject)

Callback function that is invoked in case of an error.
Parameters:
Name Type Description
errorObject Object An object containing two properties: 'errorCode' and 'description.' The 'errorCode' property corresponds to one of the sap.AuthProxy constants. The 'description' property is a string with more detailed information of what went wrong.
Example
function errorCallback(errCode) {
   //Set the default error message. Used if an invalid code is passed to the
   //function (just in case) but also to cover the
   //sap.AuthProxy.ERR_UNKNOWN case as well.
   var msg = "Unkown Error";
   switch (errCode) {
      case sap.AuthProxy.ERR_INVALID_PARAMETER_VALUE:
         msg = "Invalid parameter passed to method";
         break;
      case sap.AuthProxy.ERR_MISSING_PARAMETER:
         msg = "A required parameter was missing";
         break;
      case sap.AuthProxy.ERR_HTTP_TIMEOUT:
         msg = "The request timed out";
         break;
   };
   //Write the error to the log
   console.error(msg);
   //Let the user know what happened
   navigator.notification.alert(msg, null, "AuthProxy Error", "OK");
};

samlChallengeCallback(url)

Callback function that is invoked when the server indicates to the client that there is a SAML challenge.
Parameters:
Name Type Description
url string The request url.

successCallback(serverResponse)

Callback function that is invoked upon a response from the server.
Parameters:
Name Type Description
serverResponse Object An object containing the response from the server. Contains a 'headers' property, a 'status' property, and a 'responseText' property.
'headers' is an object containing all the headers in the response.
'status' is an integer corresponding to the HTTP status code of the response. It is important to check the status of the response, since this success callback is invoked upon any response from the server - including responses that are not normally thought of as successes (for example, the status code could be 404 or 500).
'responseText' is a string containing the body of the response.