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.https://accounts.sap.com/saml2/idp/sso/accounts.sap.com - Modify the context variable in LogonDemo\www\index.html to indicate that SAML should be used by adding.
"auth": [ { "type": "saml2.web.post" } ],
- Prepare, build and deploy the app with the following command.
cordova run android
or
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 asc:\temp\saml\idp.ssocircle.com.xml - 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.C:\temp\saml\smp-metadata.xml - 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
c:\temp\saml\idp.ssocircle.com.xml
- 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.
Note the config section is optional. For additional details see Enabling Secure Onboarding Using SAML."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"
}
}
],
- 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.
After successfully registering examine the registration in the management cockpit.cordova run android
or
cordova run ios
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.
https://ykfn00528072a.amer.global.corp.sap/odata/applications/v1/com.mycompany.logon/Connections
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.
com.sap.cloud.security.login: login-request...
<body onload="document.forms[0].submit()">
<form method="post" action="https://idp.ssocircle.com:443/sso/SSOPOST/metaAlias/ssocircle">
or
<form method="post" action="https://accounts.sap.com/saml2/idp/sso/accounts.sap.com">
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.
https://idp.ssocircle.com/sso/UI/Login
or
https://accounts.sap.com/saml2/idp/sso/accounts.sap.comOnce 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.
https://ykfn00528072a.amer.global.corp.sap/SAMLAuthLauncher
https://ykfn00528072a.amer.global.corp.sap/SAMLAuthLauncher?finishEndpointParam=someUnusedValue
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.
https://ykfn00528072a.amer.global.corp.sap/SAMLAuthLauncher
If the session is still valid, the SMP server responds with a redirect.
https://ykfn00528072a.amer.global.corp.sap/SAMLAuthLauncher?finishEndpointParam=someUnusedValue
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.
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.
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");
return;
}
var xmlhttp = new XMLHttpRequest();
xmlhttp.onreadystatechange = function() {
if (xmlhttp.readyState == 4 && xmlhttp.status == 200) {
var SAMLSessionNeeded = xmlhttp.getResponseHeader("com.sap.cloud.security.login");
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");
performSAMLAuth();
}
else {
console.log(xmlhttp.responseText);
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 + "')";
xmlhttp.open("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));
xmlhttp.send();
}
...
<button id="saml" onclick="performSAMLAuth()">Perform SAML Auth</button>
<button id="settings" onclick="getSettings()">Get Settings</button>
"refreshSAMLSessionOnResume": "skip",
- Prepare, build and deploy the app with the following command.
cordova run android
or
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.
- SAP Managed Tags:
14 Comments
