Skip to Content

Getting Started with Kapsel – Appendix M — Using SAML with Kapsel (SP09+)


Appendix M:  Using SAML with Kapsel (SP09+)

Support for Security Assertion Markup Language (SAML) was added to Kapsel and the SMP server in SP05.

The following samples were creating using SP09 PL03 of the SDK.

Here are a few terms that are used with SAML.
An identity provider (IDP) maintains a directory of users and provides authentication.
A service provider is the web site or service that is being accessed.
A user is the person who has an account with the identity provider.

When a user logs in with the identity provider, a SAML token is returned that grants access to an application for a certain length of time.  If the SAML token is compromised it is only valid for a limited length of time against a specific application.  Multiple applications can use the same identity provider so multiple applications can use the same user name and password,  X.509 certificate or perhaps even a biometric like a fingerprint.

For additional details on SAML see SAML 101 Video and Enabling Secure Onboarding Using SAML.
The How to authenticate application users using SAML may also be of interest.

The following three examples demonstrate how to register from a Kapsel app to an application that is configured to use SAML on an HCPms server, how to configure the SMP 3.0 server to use an identity provider, and finally how to control when an application performs the SAML authentication.

Registering using SAML with HCPms
Registering using SAML with SMP 3.0 Server
Controlling the SAML Registration Flow

Registering using SAML with HCPms

The following steps demonstrate how to configure the Logon example from the HCPms sectionto use SAML as the authentication provider for the application.

  • Using the HANA Mobile service cockpit, modify the Security Configuration of the application com.mycompany.logon from None to Form.  Form indicates SAML should be used.  The identity provider for the HCPms trial server is

    and it requests your SCN user name and password.

  • Modify the context variable in LogonDemo\www\index.html to indicate that SAML should be used by adding.
        "auth": [ { "type": "" } ],
  • Prepare, build and deploy the app with the following command.
    cordova run android
    cordova run ios


    Note, if the Remember me checkbox is checked, a cookie will be set that will remain valid for three months so the user name and password will not need to be re-entered.


Registering using SAML with SMP 3.0 Server

The following steps will demonstrate how to configure the SMP server to work with an identity provider and then use that identity provider as an authentication provider for the Logon sample.  The identity provider used in this section is a hosted solution from SSOCircle that has free account registration to their hosted identity provider as well as paid offerings.

Other identity providers include Microsoft Active Directory Federation Services and Identity Provider for SAP Single Sign-On

  •     Register with SSOCircle.
  • Once registered, note the user id and remember your password.

    Choose Manage Metadata > SSOCircle Public IDP Metadata.

    Save the xml as

  • In the SMP server’s management cockpit choose Settings > SAML > Local Service Provider.
    Provide a unique name and a Base URL that is the fully qualified host name of the SMP server.

    Click on Generate Key Pair.
    Click Save.
    Click Get Metadata.  Copy that file to the following location.

  • In the SMP server’s management cockpit choose Settings > SAML > Trusted Identity Provider > New > and for the Metadata File click the browse button and choose


  • In the SSO Circle website choose Manage Metadata and click on Add new Service Provider.  Enter the FQDN of the SMP server and paste in the contents from the file c:\temp\saml\smp-metadata.xml.

  • Modify the application with the id of com.mycompany.logon to use a SAML Authentication provider.

    Note the Identity Provider Name can be determined by examining Settings > SAML > Trusted Identity Provider > Name.

  • Modify the host variable so it points to your server and ensure that the port is the HTTPS port and https is true.
    Modify the context variable in LogonDemo\www\index.html to indicate that SAML should be used by adding.
        "auth": [
                        "type": "",
                        "config": {
                            "": "",
                            "": "/SAMLAuthLauncher",
                            "": "finishEndpointParam"

    Note the config section is optional.  For additional details see Enabling Secure Onboarding Using SAML.

  • In the SMP Management Cockpit, under Applications > com.mycompany.logon > Back End > SSO Mechanisms, add a Technical User (Basic) scheme that contains the user name and password used to access the backend OData source.
  • Prepare, build and deploy the app with the following command.
    cordova run android
    cordova run ios

    After successfully registering examine the registration in the management cockpit.

See also How to Authenticate Application Users Using SAML

Controlling the SAML Registration Flow

When the Logon plugin is configured to use SAML and the app begins the registration process due to sap.Logon.init being called, a request such as the following is made from within the InAppBrowser.

If the server has been configured to use SAML authentication for the application, it will respond with a special header and an HTML page containing a redirect as shown below. login-request
<body onload="document.forms[0].submit()">
<form method="post" action="">
<form method="post" action="">

Since no prior SAML session exists, the IDP will redirect to a logon page where the user can enter their user name and password or possibly an X 509 cert to be validated.

Once validated, the IDP submits a post to the SMP server that contains the SAMLRESPONSE and the InAppBrowser window is closed when it detects the URL parameter finishEndpointParam.

The reason the SAML requests are done in an InAppBrowser window is so that the running application does not have to be reloaded causing the user to lose their flow within the application when the SAML session needs to be re-created.

By default, the logon plugin will attempt to revalidate the SAML session when the app is reopened after being removed from memory or after entering a correct passcode on the passcode screen.

If the session is still valid, the SMP server responds with a redirect.

If the session is missing or has expired, the same process happens that occurs during the initial registration.

As of SP09 PL03, it is possible to perform the SAML validation via an API method rather than each time the application is restarted or unlocked.  This provides the developer greater control which would be useful in an offline app where the SAML authentication should only be done while the application is online.

Also note that in SP09 PL03 if the SAML IDP cannot be reached, a dialog appears as shown below enabling the app to continue to open without a valid session.  If the user presses cancel the error callback from the sap.Logon.init or sap.Logon.performSAMLAuth is called.

Follow the below steps to try this out.

  • Modify the index.html used for the previous example and add the following methods and buttons.
    function performSAMLAuth() {
        sap.Logon.performSAMLAuth(samlSuccess, samlError);
    function samlSuccess() {
        alert("Success from SAML");
    function samlError(e) {
        alert("Error from SAML:" + e);
    //This method is used to make a request to the SAML protected application.  It looks at the server response to determine if a new SAML session needs to be started
    function getSettings() {
        if (!applicationContext) {
            alert("Must be registered");
        var xmlhttp = new XMLHttpRequest();
        xmlhttp.onreadystatechange = function() {
            if (xmlhttp.readyState == 4 && xmlhttp.status == 200) {
                var SAMLSessionNeeded = xmlhttp.getResponseHeader("");
                if (SAMLSessionNeeded) {
                    alert("SAML session has expired or the session header has expired due to the app being removed from memory.  Please retry the operation after a successful registration");
                else {
                    alert("Check the Web Insepctor console for the settings details or the Network > Preview tab.");
        var lastSlash = applicationContext.applicationEndpointURL.lastIndexOf('/');
        var serverURL = applicationContext.applicationEndpointURL.substring(0, lastSlash);
        sUrl = serverURL + "/odata/applications/latest/com.mycompany.logon/Connections('" + applicationContext.applicationConnectionId + "')";"GET", sUrl, true);
        xmlhttp.setRequestHeader("Accept", "application/json");  //setting this so it is easier to view response in Network > Preview tab.
        xmlhttp.setRequestHeader("Authorization", "Basic " + btoa(applicationContext.registrationContext.user + ":" + applicationContext.registrationContext.password));
    <button id="saml" onclick="performSAMLAuth()">Perform SAML Auth</button>
    <button id="settings" onclick="getSettings()">Get Settings</button>

    Modify the context in the init method and add the following configuration value which indicates that the SAML session should not be refreshed automatically when the app is restarted or unlocked.

    "refreshSAMLSessionOnResume": "skip",
  • Prepare, build and deploy the app with the following command.
    cordova run android
    cordova run ios
  • Provide your credentials.
    Press the back button to exit the app or on iOS remove the app from memory.
    Reopen the app.  Notice that this time the SAML logon page is not shown.
  • Press the Get Settings button.  Note that the SAML authentication screen now appears as the app detected that a SAML session is required.

Back to Getting Started With Kapsel

You must be Logged on to comment or reply to a post.
  • As always, thanks for the awesome write-ups! Question, I run into a problem where the InAppBrowser doesn't close after logging in. It just hands with a blank screen and all I can see is the cancel button to manually close IAB. I assume I'm supposed to be redirected back to my app, but that's not happening.

    I'm using the LogonDemo, ssocircle SAML, with on-prem SMP 3.0 SP09 (latest?)

    Any ideas?

    • I would check the device log to see if it has any clues.  Which version of SP09 are you using?  In the plugin.xml file for each Kapsel plugin is a version entry.

      What device OS are you using?  Sometimes it helps to try another OS flavor ie Android vs iOS.  Sometimes you get a slightly different error message that is more helpful.

      One other option is to introduce Fiddler so that you can see the request response flow between your device and the server's it is communicating with.  There is some information on using Fiddler here.

      Getting Started with Kapsel - Appendix F -- Tips (SP09+)


      Dan van Leeuwen

      • Sorry, I'm using SMP (On-Prem)

        Kapsel Plugins

        logon - 3.9.3

        inappbrowser - 0.6.0-patched

        I'm using iOS. To capture traffic on Mac between client and service, do you have a recommendation besides Fiddler? I tried it out before, but didn't work well for Mac.

        Also, which device logs are you referring to? The logs I see in Safari while attaching to simulator? Or Xcode? None didn't give much info. Is there a debug level I can set to get more logs from Logon plugin?

        Also, I was able to do a successful registration via Chrome and Advanced Rest Client. Got the 501, then sent POST and got back 201.



        • Hi Daniel,

          We are also facing the same issue, and have to close the iab manually for iOS. Were you able to tackle this issue? Could you guide us.

          Thanks a ton in advance.



          • Hi Daniel Van Leeuwen,

            We are facing the same issue. We have identified the cause, but do not know how to tackle it. In your blog for Fiori Client, the section for Removing Set Passcode screen was followed and this leads to the above behavior. Once we default to the standard code, it displays the passcode screen which the user can manually disable and then continue.

            Is there any other way of disabling the set passcode screen, as this does not work properly with SAML.

            Thank You!

          • Hi Vigil,

            This particular issue was due to some configuration issues on our setup. Relay was setup for SSL, so the client could access via HTTPS, but the configuration between the relay server and internal SMP server was HTTP. Once we configured it for HTTPS, the issue was resolved.

            If I remember correctly, the fix was at the rsoe.config file.

  • Hi Daniel,

    Thank you for the precise blog. We are trying to configure SAML using SAP NW as IdP. We are facing difficulty while trying to run this through Kapsel logon plugin. Our application ID is configured for SAML authentication, and redirection is happening at Browser level, both on desktop and mobile browser. However, when opening the application after setting "auth" parameter in the logon's context, the application is stuck at re-direction. The idp's page does not appear. We configured SSO Circle as well, but are facing the same issue.

    We are using SP 10 PL2 server, and tried both SP11 and SP10 PL10 SDK along with it but unsuccessful. What could be the issue here?



    • I was successful using SP10 of the SMP server and SP11 of the SDK using SSO Circle.

      Sometimes using a tool such as Fiddler to capture the communications being sent from the device to the SMP server can be helpful.  There are some instructions here that may be helpful on this subject.

      Getting Started with Kapsel - Appendix F -- Tips (SP09+)

      There is also a section called Controlling the SAML flow that attempts to document the requests that are made.  It may be helpful to compare your flow to that.

      Have you examined the SMP server log files? 


      Dan van Leeuwen

      • Hi Daniel,

        Further debugging, we have identified the root cause using Fiddler. It looks like the proxy is coming into the picture, although not sure why. The proxy server has authentication enabled, and using fiddler we are able to force credentials for every session using this. Using fiddler we are able to see the IdP screen. So we went and configured proxy settings in SMP and set the IdP server as bypass proxy, but still the issue is there. I believe this setting is valid only for connections, although wanted to give it a try.

        Could you guide us?



        • Please create a new Discussion marked as a Question.  The Comments section of a Blog (or Document) is not the right vehicle for asking questions as the results are not easily searchable.  Once your issue is solved, a Discussion with the solution (and marked with Correct Answer) makes the results visible to others experiencing a similar problem.  If a blog or document is related, put in a link.  Read the Getting Started documents (link at the top right) including the Rules of Engagement. 

          NOTE: Getting the link is easy enough for both the author and Blog.  Simply MouseOver the item, Right Click, and select Copy Shortcut.  Paste it into your Discussion.  You can also click on the url after pasting.  Click on the A to expand the options and select T (on the right) to Auto-Title the url.

          Thanks, Mike (Moderator)

          SAP Technology RIG