Setting up Single Sign-On (SSO) with IBM Cloud App ID, simpleSAMLphp and LDAP
For an organization who plans to deploy public cloud application to their internal users, one in the top list that needs to be considered carefully is how to authenticate the users. Most of the organization have an existing intranet, behind a firewall on-premise infrastructure and applications that already includes an authentication server. This authentication server is commonly using either MS Active Directory (AD) or open-standard Lightweight Directory Access Protocol (LDAP).
It is not practical for the internal users to maintain two separate credentials, one for the existing intranet applications and another new one for the cloud applications. That is one of the reasons the concept of single sign-on (SSO) comes into play. SSO enables extranet application to authenticate users against the existing intranet authentication server without sacrificing the security. Enterprise SSO is implemented using Security Assertion Markup Language (SAML), open standard for securely exchanging authentication and authorization data between parties.
Implementing SSO in IBM Cloud (previously known as Bluemix) is now easier with App ID, a service that lets developers to easily add authentication, authorization and user profile services to apps and APIs. If your organization is using Active Directory, the tutorial on setting up SSO with App ID and AD FS (Active Directory Federation System) is described in this blog.
This tutorial is intended for an organization who uses LDAP instead. Since LDAP doesn’t support SAML 2.0 out of the box, you will need a bridge between the two. One such bridge is SimpleSAMLphp, an open-source PHP authentication application that provides support for SAML 2.0 as a Service Provider (SP) or Identity Provider (IdP). In this setup, you will configure SimpleSAMLphp as the IdP with LDAP as the authentication source and App ID as the SP.
Step 1. Install SimpleSAMLphp
For installing and testing SimpleSAMLphp, refer to this DigitalOcean tutorial. You need to follow thoroughly the prerequisites and step 1-5 of that tutorial. There are, however some changes required in step 3 and step 4 that are described below.
In Step 3 — Configuring SimpleSAMLphp:
DigitalOcean tutorial leaves the default IdP configuration as it is, however, you need to modify it for this tutorial.
First, you need to generate a new SSL private key and the corresponding self-signed certificate for signing SAML messages.
openssl req -newkey rsa:2048 -new -x509 -days 3652 -nodes -out myidp.crt -keyout myidp.pem
The command will generate two files, myidp.crt and myidp.pem that you need to put in the /var/simplesamlphp/cert directory.
Open the IdP configuration file:
$ nano /var/simplesamlphp/metadata/saml20-idp-hosted.php
Update the three definitions below:
'privatekey' => 'myidp.pem', 'certificate' => 'myidp.crt', 'auth' => 'example-sql',
Close and save the file.
In Step 4 — Configuring the Authentication Source:
In the DigitalOcean tutorial, SimpleSAMLphp is configured as IdP with SQL as the authentication source. Step 4 describes how to create the MySQL database and populate it with the test usernames and passwords. Since App ID requires email id attribute in addition to username and password, you need to add it at this step for later test.
When creating a users table, you need to add the mail field:
mysql> CREATE TABLE auth.users(username VARCHAR(30), password VARBINARY(30), mail VARCHAR(30));
Then when inserting the three users into the newly created table, you also need to insert the respective email id:
mysql> INSERT INTO auth.users(username, password, mail) VALUES mysql> ('user1', AES_ENCRYPT('user1pass','your_secret_key'), 'user1@mydomain.com'), mysql> ('user2', AES_ENCRYPT('user2pass','your_secret_key'), 'user2@mydomain.com'), mysql> ('user3', AES_ENCRYPT('user3pass','your_secret_key'), 'user3@mydomain.com');
Open the authsources configuration file:
$ nano /var/simplesamlphp/config/authsources.php
You need to add the mail in the query statement in the SQL authentication source definition:
'example-sql' => array(
'sqlauth:SQL',
'dsn' => 'mysql:host=localhost;port=5432;dbname=auth',
'username' => 'authuser',
'password' => 'your_mysql_auth_user_password',
'query' => 'SELECT username, mail FROM users WHERE username = :username AND AES_DECRYPT(password,"your_secret_key") = :password',
),
The username and email id attributes will be returned by the IdP to App ID when the user logs on.
Successful SAML 2.0 SP Demo in Step 5 will show both the username and email id attribute in the Example page.
Step 2. Create an App ID instance in IBM Cloud
Log in to your IBM Cloud (Bluemix) account, search App ID in the catalog then open the found service. You can leave the default entries as it is and just click the Create button. In the next page, select SAML 2.0 Federation under the Identity Providers menu.
Click on the Download SAML Metadata file button. It will download a file appid-metadata.xml that you will use in the next step.
Step 3. Setup and perform authentication test from App ID (SP) to SimpleSAMLphp (IdP)
Go back to your simpleSAMLphp interface and select Federation folder. Under Tools, click XML to SimpleSAMLphp metadata converter.
Upload the appid-metadata.xml file then click Parse button.
You will get the converted metadata that you need to copy into the clipboard.
Open the saml20-sp-remote.php
$ nano /var/simplesamlphp/metadata/saml20-sp-remote.php
Paste the converted metadata from the clipboard to the bottom of the file and then add the following two lines:
'simplesaml.nameidattribute' => 'mail', 'simplesaml.attributes' => false,
Close and save the file.
Refresh your simpleSAMLphp interface browser, under SAML 2.0 SP Metadata (Trusted) you will now see the App ID entityID that you got from the downloaded appid-metadata.xml file.
Click [Show metadata] and scroll down to the end of the page:
You need to note down the following three definitions that you will need to complete the App ID configuration.
- entityid
- Location
- certData
For certData, you could either copy directly from the page or from the downloaded idp.crt file.
Complete configuring App ID by using the above information.
- Set entityID to entityid
- Set Sign-in URL to Location
- Primary Certificate should be set to certData
Save the configuration data.
You can now test your setup by clicking on the Test button. This will initiate an authentication request from App ID as SP to simpleSAMLphp as IdP and MySQL as the authentication source. It will open the simpleSAMLphp authentication UI/UX and once you have entered the credential information as the one you stored in the MySQL, you should be presented with an App ID access token as well as an identity token.
Step 4. Setup LDAP as the authentication source
With the confirmation that your App ID and simpleSAMLphp setup work properly, you just need to change the authentication source from MySQL to LDAP. This tutorial assumes that you already familiar with LDAP such as OpenLDAP.
Open again the authsources configuration file:
$ nano /var/simplesamlphp/config/authsources.php
This configuration file has samples of authorization sources including for LDAP. Search for ‘example-ldap’ to locate the sample LDAP authorization source and uncomment this section.
Modify the following two definitions to suit your LDAP server:
// The hostname of the LDAP server. 'hostname' => 'aaaa.bbbb.com', // Whether SSL/TLS should be used when contacting the LDAP server. 'enable_tls' => TRUE,
The following two definitions are needed to match the minimum attributes required by App ID, that is username and email id. It is similar to what you put in the SQL authorization source.
// As an alternative to specifying a pattern for the users DN, it is possible to
// search for the username in a set of attributes. This is enabled by this option.
‘search.enable’ => True,
// The attribute(s) the username should match against.
//
// This is an array with one or more attribute names. Any of the attributes in
// the array may match the value the username.
‘search.attributes’ => array(‘uid’,’mail’),
Leave the others as it is. Close and save the file.
The last one, open again the IdP configuration file:
$ nano /var/simplesamlphp/metadata/saml20-idp-hosted.php
Change ‘auth’ => ‘example-sql‘ into ‘auth’ => ‘example-ldap‘.
Close and save the file.
That’s all, you can test by clicking on the Test button again. However, now you should enter your credential as stored in your LDAP server.
Step 5. App ID sample app
You could build and run the preconfigured sample apps to get familiar with App ID in a language in which you feel comfortable working. You can choose from iOS Swift, Android, Node.js, and Java.
Follow the steps in the Overview page to build and run the sample app. Once your app is built and deployed, you can open it in a browser and log in by using your credentials. As you can see from the sample app login page below, the one that you need is, of course, the Login with SAML which will authenticate to your simpleSAMLphp dan LDAP.
You could remove the identity providers that you don’t want to show simply by switch it off in the Manage Identity Providers page. You can also use the login widget feature to customize a sign-in page and see how quickly the updates that you make are shown in your app.
Step 6. Network configuration consideration
As stated at the beginning of this tutorial, your organization most likely has the LDAP server secured behind the firewalls. SAML basically just need HTTPS so you could just open up port 443 in your firewall for App ID to communicate with simpleSAMLphp that you also should treat it as back-end server as LDAP.
However, the recommended approach is to have a reverse proxy as an intermediary server in the demilitarized zone (DMZ) that directs App ID requests to the simpleSAMLphp server. The two most popular reverse proxy servers are NGINX and Apache which you could easily find the corresponding setup tutorial.