SSO Integration via SAML with Developer Portal

[gitesh]

The instructions below are for Pantheon hosted developer portals. For Private Cloud please refer to this article

We have been getting a lot of requests for SSO integration with Developer portal.

So I wanted to document the procedure to do this.

Here are the steps :

1. Download the latest version of the SimpleSAMLphp library from https://simplesamlphp.org/download and extract it into Drupal_Root/private/simplesamlphp.
2. Create a symlink ln -s ./private/simplesamlphp/www ./simplesaml from Drupal_Root/
3. Install and enable simpleSAMLphp Authentication module from https://www.drupal.org/project/simplesamlphp_auth to sites/all/modules/contrib directory
4. Enable the simplesaml_support custom module [download and unzip simplesaml-support.zip to sites/all/modules/custom/simplesaml_support folder] to get the simplesamlphp_auth module working with Apigee devconnect module’s user registration requirements (First Name, Last Name, Email address).
5. Edit Drupal_Root/private/simplesamlphp /config/config.php
   • change the 'auth.adminpassword' value to a different value
   • Change the ‘baseurlpath’ to https://<yourportaldomain>/simplesaml/
   • Set the value of ‘tempdir’ to a directory where the simplesamlphp library can write temporary files to.
   • Set ‘store.type’ to sql
   • Set the value of the 'store.sql.dsn' key as 'mysql:host=<dbhost>;port=<port>;dbname=<database>,
   • Set 'store.sql.username' to <database_username>
   • Set 'store.sql.password' to <database_password>
   • Here is the sample patch file with the diff of changes from my config.php file on pantheon simplesamlphp-configpatch.txt
6. Edit Drupal_Root/private/simplesamlphp/config/authsources.php
   
   • Set the value of the ‘entityID’ which is the unique id of the SP under default-sp, say for Example set ‘entityID’ => 'developer.client-portal.com', this should be some thing unique to your portal e.g. developer.apigee.com. (This is the entity ID that you would provide during SP definition in your SSO provider)
7. Give the above entity id and the metadata URL i.e https://developer.client-portal.com/simplesaml/module.php/saml/sp/metadata.php/default-sp to the Identity provider and ask for the identity provider metadata XML and the name of attributes for email, firstname lastname, username and unique identifier for the users.
8. Once you receive the metadata from the identity provider navigate to https://developer.client-portal.com/simplesaml/ and you will see the simplesamlphp library’s UI
9. Next click on the federations tab on the page and under the Tools section click “XML to simpleSAMLphp metadata converter” link and paste the XML metadata from the IDP in the form and click parse
10. This will convert the metadata from XML to PHP array. It will also provide you the names of the files that need to be modified under Drupal_Root/private/simplesamlphp /metadata/ directory
    
    • If it says saml20-idp-remote on the top of the page, Copy the metadata in PHP format and paste it in Drupal_Root/private/simplesamlphp /metadata/saml20-idp-remote.php
    • There might be additional config files under the metadata folder that may need to be updated. Please confirm by scrolling through the metadata generator page.
    • The key of the metadata array (e.g. $metadata['https://openidp.feide.no']) in this case , “https://openidp.feide.no" is the entity ID of the identity provider.
    • Copy the key and paste it as the value of ‘idp’ key in Drupal_Root/private/simplesamlphp /config/authsources.php under default-sp eg: ‘idp’ => "https://openidp.feide.no"
11. Navigate to https://developer.client-portal.com/admin/config/people/simplesamlphp_auth and configure the settings as follows:
    
    • Select Activate authentication via SimpleSAMLphpSet
    • Installation directory to, path to Drupal_Root/private/simplesamlphp
    • Set Authenticaton source for this SP (default: default-sp) as default-sp
    • Select Force https for login links if you have https enabled for your developer portal
    • Under User Info and Syncing enter the names of the respective attributes received from the in step 7
    • Under User provisioning Select “Register Users” if you would like the users to be registered in the developer portal if the account does not exists.
    • Under Drupal Authentication select the roles for whom you would like to give login access using Drupal Credentials. It is always good to allow administrator role to login using Drupal credentials.
12. The set up is complete and now you will have to test the setup
13. Navigate to https://developer.client-portal.com/saml_login and immediately you should be redirected to the SSO login page of the IDP.
14. Once you enter the login credentials and login you will be redirected back to the developer portal and will be logged in if everything worked fine.

[rajeshmi]

1. The attached configpatch is for devportal hosten on pantheon. In case of OPDK, one needs to specify db settings in the config.php

[gitesh]

Yes that is correct

[williamssean]

@Gitesh Koli @rajeshmishra

Do we need to install

simpleSAMLphp Authentication to the modules folder?

I install both the auth module and the support module, but when I go to Modules in my dev portal It tells me that the support module is missing.

[Surabhi_gupta]

Gitesh,

I am working with Sean on this. We are stuck at "enable module". it's not active in Drupal Modules. Can you please help!!!

Thanks,

Surabhi

[gitesh]

This was because the module files werent uploaded . This should be fixed now.

[williamssean]

Step 3 should read:

Install and enable simpleSAMLphp Authentication module from https://www.drupal.org/project/simplesamlphp_auth.

It should be installed into the sites/all/modules/contrib directory.

[williamssean]

@Gitesh Koli, @rajeshmishra

For step 11:

• Installation directory to, path to Drupal_Root/private/simplesamlphp

Do we put the full path? i.e. /srv/bindings/[hash code]/code/private/simplesamlphp? Will this break if we check-in new code?

When I access https://developer.client-portal.com/saml_login I receive an access denied error message.

[gitesh]

Thanks Sean . This is done

[gitesh]

You can add the full path or in the settings.php file you can add this

$conf['simplesamlphp_auth_installdir'] = DRUPAL_ROOT .'/private/simplesamlphp';

This will set the path correctly based on which server you are on.

[gitesh]

It also seems like on pantheon sometimes with the 1.14.x version of the library in case of an SP initiated SSO there was a problem with the site redirecting to a random port.

To fix that problem please follow what is suggested here https://pantheon.io/docs/server_name-and-server_port/

[williamssean]

I also made the following change:

a) In the [dev portal parent directory]/private/simplesamlphp/config/config.php

I set

'enable.saml20-idp' => true,

[williamssean]

Assuming that you use the 7.x-3.x-dev development release of https://www.drupal.org/project/simplesamlphp_auth

The following link should be configured as shown below:

https://env-orgname.devportal.apigee.com/admin/config/people/simplesamlphp_auth

You will also have to set the first and last name variables via cli as shown below:

terminus --site=jll-nonprod drush vset simplesamlphp_auth_fname firstName
terminus --site=jll-nonprod drush vset simplesamlphp_auth_lname lastName

If you use the alpha version 7.x-2.0-alpha2 then you do not have to set the first and last name via the cli. You will be able to set those values from the configuration screen shown above.

[Surabhi_gupta]

@swilliams, we tried configuring OKTA using JLL OKTA environemnt. It let's me and Andrew in since we already exist as user in dev portal but doesn't let other users in. Coupld of people tried and they are getting access denied. I had one user test using simplesaml test page, and it shows her authentication. When I checked users, the account wasn't created.

How do we investigataleris-simplesamltest.pnge it?

[williamssean]

hey @Surabhi.gupta,

I think this should be a new question, but I will answer here.

Make sure that "Register Users" is selected in the simplesaml configuration. This setting should be on the Basic Settings tab.

[#16]

@swilliams Yes, the "Register Users" is selected in the simplesaml configuration. I can submit this as a new question if you'd like.

[#17]

Has anyone integrated the same IdP twice, different contexts (users verses admins)? Since the IdP returns the same entityID simpleSAMLphp gets confused…

[#18]

Hi @Marc Boschma

If the role is defined in IdP and returned, it can be sent as attribute to SP and SP can take action based on the role returned from Idp, that way you can avoid 2 integrations.

[#19]

That would be lovely, but SecureAuth applies different authentication policies per realm (username password for users, username, password and RSA 2FA for admins). So it can't be attribute driven… more the pity...

[gitesh]

@Marc Boschma

Wouldn't it be the IdP's responsibility to force the 2FA for admin's since it knows which user is trying to login ?

The portal does not know this information before authentication.

If the IdP cannot identify users as admin's and force 2FA then there should be 2 entity ID's defined one for regular users and one for Admin's and there should be two different buttons to let user's login as per their role.

Two different entities will allow you to force the correct set of users you who can login against that configuration

Entity 1 -> All users who are not Admins (and this being strictly enforced to make sure admins can't login)

Entity 2 -> All users who are Admins

I do not see how you will achieve this behavior with one entity ID (which may allow admins to login without 2FA, which in my opinion could be a security loophole)

[vagrawal]

This is very useful @Gitesh Koli. We have a similar requirement with one of our enterprise customer where we can leverage this right way. I am wondering if there is way to package it in a form of some custom module (as a part of product), to make it easy to integrate.

[#22]

We have managed to make it work with some simple modifications of simpleSAMLphp to trigger a switch to the other realm if detecting the user is an admin. That is the non-privledged user context returns assertions as to whether or not the user is an admin and if so redirects the authentication to the admin context. With SSO the only extra user interaction is to provide the 2FA RSA token…

simpleSAMLphp seems to be structured to allow this to be handled via one of its plugin / filter capabilities, but utilising that will be on the back log...

[#23]

Hi @Gitesh Koli,

We have been following this post and tried to get the symlink as instructed under DRUPAL_ROOT/private/simplesamlphp/www.

When I visit http://mysite/simplesaml it throws following error:

Warning: require_once(/srv/bindings/<DROPID_HASH>/code/lib/_autoload.php): failed to open stream: No such file or directory.

Looks like the path that we created under symlink is not able to find the respective files for simplesamlphp.

We used following command:

ln -s ./private/simplesamlphp/www ./simplesaml in Drupal root.

We are stuck on this step as we have completed the POC on the local system using apache, but looks like pantheon uses Nginx so "alias" methodology may not work in this system.

We have also used the configpatch and the local.settings.php to setup the variable for installation directory.

Please let me know how can I resolve this.

Thanks,

Prath

[#24]

@swilliams @Gitesh Koli

For step 11:

• Installation directory to, path to Drupal_Root/private/simplesamlphp
  
  I have put full path i.e. /srv/bindings/[hash code]/code/private/simplesamlphp and added to the settings.php file :
  
  # Decode Pantheon Settings
  $ps = json_decode($_SERVER['PRESSFLOW_SETTINGS'], TRUE);
  # Provide universal absolute path to the installation.
  $conf['simplesamlphp_auth_installdir'] = '/srv/bindings/'. $ps['conf']['pantheon_binding'] .'/code/private/simplesamlphp;
  
  as mentioned here.
  
  Still on going to https://developer.client-portal.com/saml_login I receive an access denied error message.

[jan]

If you're using Edge for Private Cloud v. 4.17.x with nginx, I've posted some required config changes here: https://community.apigee.com/questions/44115/sso-integration-via-saml-with-developer-portal-417.html

[Surabhi_gupta]

@gkoli@apigee.com,

We have been using this module to SSO with OKTA for a year now. It has been working fine but from last few weeks, developer portal is running very slow with I use SSO. I tried using local developer portal account and performance is much better.

Can you please provide any help to investigate/identify the issue?

[sunilmewada]

Hi,

We have installed OPDK 4.17.09 Developer Drupal portal with nginx

We are following all the steps as mentioned in this thread, but got stuck at step-8

8. Once you receive the metadata from the identity provider navigate to https://developer.client-portal.com/simplesaml/ and you will see the simplesamlphp library’s UI

For us the https://<devportal-host>:<port>/simplesaml>; is not working and gives error"Page Not Found"

We have done all the steps, I guess the step-1 itself is wrong that's why step-8 (simplesamlphp library’s UI) is not working

Can anyone please confirm,

- if simplesamlphp need to be copied to /opt/apigee/apigee-drupal/wwwroot/sites/all/libraries/simplesamlphp

- And the symLink should be created at this location /opt/apigee/apigee-drupal/wwwroot as below

ln -s /opt/apigee/apigee-drupal/wwwroot/sites/all/libraries/simplesamlphp/www ./simplesaml

Thanks

Sunil

[franklino]

@Sunil, i too am working with OPDK 4.17.09 but have configured simplesamlphp differently as shown below. however, i'm also having similar problem you are so i think clarity on the EXACT location this module requires for OPDK is needed.

• extract simplesamlphp to /opt/apigee/apigee-drupal/wwwroot/private/simplesamlphp
• symlink file located /opt/apigee/apigee-drupal/wwwroot/simplesaml
• ln -s /opt/apigee/apigee-drupal/wwwroot/private/simplesamlphp/www ./simplesaml

[nikhi_pk]

Can someone help me how to call SLO here?

I tried the below steps but it is not working, After succesfull authentication once the user clicks on the logout link First i called the normal drupal user logout and then redirected to the IDP SLO logout url.

[#30]

Using this module effectively kills Edge->DevPortal developer sync, because it overwrites the to-be-created user's email, firstName and lastName properties with something it cannot fetch from the SAML session since there is no such thing during an Edge->DevPortal developer sync. This problem can be recognized by having Drupal users without email at all.

@Gitesh Koli, could you please create a GH repository for this and move (initiate) code maintenance there?

[bbhatia]

Thanks for the article. On step 7 i was stuck because we use microsoft active directory adfs and there was no info about the claims. So i referred article here which helped me alot. Also there was issue in simplesamlphp library about the redirection. Apply patch from here

[bbhatia]

after enabling saml as well as local accounts, support module was causing the empty name and email address when new user registers and copies existing user's name and email address if saml enabled administrator add new user. I fixed issue by modifying code as below by checking empty before setting the values.

if($account->is_new){
	  if(empty($edit['mail'])) {
		$edit['mail'] = _simplesamlphp_auth_get_mail();
	  }
	  if(empty($edit['field_first_name'][LANGUAGE_NONE][0]['value'])) {
		$edit['field_first_name'][LANGUAGE_NONE][0]['value'] = _simplesaml_support_get_fname();
	  }
	  if(empty($edit['field_last_name'][LANGUAGE_NONE][0]['value'])) {
		$edit['field_last_name'][LANGUAGE_NONE][0]['value'] = _simplesaml_support_get_lname();
	  }
  }  
<br>

[edgaralfonsomen]

Is this guide still valid for Drupal 8 portals on Pantheon? Besides some path modifications and the simplesamlphp_auth module upgrade, is this a viable guide for SSO via SAML? Or is there another method needed for D8?

[karlscheirer]

Its roughly the same, but there are new docs available for Drupal 8-based portals here: https://www.drupal.org/docs/8/modules/apigee-developer-portal-kickstart/integrate-simplesamlphp-auth...