Sunday, January 24, 2016

Configure SAML SSO to PeopleHR using WSO2 Identity Server

I wanted PeopleHR to do SAML SSO with WSO2 Identity provider, but couldn't find any documentation that gave generic steps on how to configure SAML SSO in PeopleHR. I hope this blog will help you through. I will try to keep it as generic as possible and use WSO2 Identity Server as an example only.

1 - Create a metafile in the following format

<?xml version="1.0"?>
<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" entityID="dimuthul.local">
  <IDPSSODescriptor xmlns:ds="" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="">
    <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://localhost:9443/samlsso"/>
    <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://localhost:9443/samlsso"/>
    <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="https://localhost:9443/samlsso"/>
  <ContactPerson contactType="technical">

2 - Upload it to PeopleHR by Going to Settings-->Company

3 - Now at the SAML Provider side here are the parameters. These parameters are found by studying the AuthnRequest.
  • EntityId/Issuer (relying party or service provider Id) is "test-app-peopleweb"
  • ACS (Assertion Consumer) URL is https://{replace-with-your-domain-name}
  • NameID format is urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
  • Enable assertion signing 
  • Supports IdP initiated SSO
  • Supports SP initiated SSO

Important points to know,
  • According to the SAML specification the EntityId given in the metadata.xml file and the "Issuer" of the SAML response should be equal. But in PeopleHR implementation it need not checked. 
  • The Issuer in AuthnRequest must be "test-app-peopleweb" and it is not changeable.
  • Not possible to enable Federation Only SSO. The system sends an invitation mail that will ask people to create passwords. And even when this is avoided, when an user sign into PeopleHR for the first time (via SSO) a username/password is requested
  • If employees need the mobile app, then native logins must be used
  • The UI should not say "Upload one login meta-data file". The meta-data file comes from SAML specifications
  • The EntityIds must be properly checked at the PeopleHR side
  • The EntityId should be configurable and definitely not carry a name as "test-app-peopleweb" as this is a production system