Summary

This Step by Step Guide covers the installation of PhenixID SAML SP Filter for Password Self Service. The SAML SP filter is used in scenarios where the PSS users should be authenticated on an external SAML Identity Provider.

System Requirements

• NordicEdge/PhenixID Password Self Service 4.8 or above
• SAML Identity Provider Metadata available (file or URL)

Instruction

Download the software

Click the link to download installation files and documentation.

About the SAML SP Filter

• Supports POST-binding only.
  • SingleSignOnServer location with POST binding must be available in IdP Metadata.
  • SAML authnRequests will always be distributed using the HTTP-POST binding.

Installation of SAML SP

1. Make sure the service Password Self Service is stopped.
2. Unzip samlsp.zip (or untar samlsp.tgz on Linux) to <pss_installation_folder_root>. (This will create the file <pss_installation_folder_root>/webapps/samlsp.war and the <pss_installation_folder_root>/endorsed/ dir including a set of jar-files.)
3. Start Password Self Service. (Password Self Service will now extract <pss_installation_folder_root>/webapps/samlsp.war to <pss_installation_folder_root>/webapps/samlsp/.)
4. Start a browser and point it to https://<hostname>/samlsp. The SAML SP should now present a status message.
5. Add samlspcommon.jar and samlspfilter.jar to Password Self Service lib directory (<pss_installation_folder_root>/webapps/phenixid/WEB-INF/lib)

Configuration of SAML SP

1. Open <pss_installation_folder_root>/webapps/samlsp/WEB-INF/nesp.properties.
2. Open the SAML Identity Provider Metadata and fetch the entityID value.
   
3. Add your idp. Set entityid to the value fetched in previous step.

   idp.1.entityid=<idp_entityID>
   idp.1.metadata.url=<idp_metadata_url>

   Example:

   idp.1.entityid=https://cstraining.local/idp
   idp.1.metadata.url=http://cstraining.local:8080/authenticate/startAuth?getIDPMeta

4. Add your SP.

   sp.1.entityid=<entityid_of_ppss>
   sp.1.contextpath=https://<ppss_server_domain>:<ppss_server_port>/ppss/
   sp.1.idp.entityid=<idp_entityID>
   

   Example:

   sp.1.entityid=pss-sp
   sp.1.contextpath=http://im.local:8098/ppss/
   sp.1.idp.entityid=https://cstraining.local/idp

5. Restart Password Self Service

Configuration of SAML Identity Provider

Get PSS SAML SP metadata: https://<ppss_server_domain>:<imppssserver_port>/samlsp/metadata/1
Example:

http://ppss.local:8098/samlsp/metadata/1

Set up trust to the PPSS SAML SP on the SAML Identity Provider.

Configuration instructions for the SAML Identity Provider is not provided in this document.

Configuration of Password Self Service

Add filtering rules to web.xml

1. Open <im_installation>/webapps/phenixid/WEB-INF/web.xml
2. Add xml (within <web-app> tag):

   <listener>
   <listener-class>se.nordicedge.sp.plugin.SamlSpFilter</listener-class>
   </listener>
   <filter>
   <filter-name>SamlSpFilter</filter-name>
   <filter-class>se.nordicedge.sp.plugin.SamlSpFilter</filter-class>
   <init-param>
   <param-name>entityid</param-name>
   <param-value><entityid_of_pss></param-value>
   </init-param>
   <init-param>
   <param-name>backend-url</param-name>
   <param-value><backend-url></param-value>
   </init-param>
   </filter>
   <filter-mapping>
   <filter-name>SamlSpFilter</filter-name>
   <url-pattern>/*</url-pattern>
   </filter-mapping>

   Change <entityid_of_pss> to the value defined in nesp.properties.
   Change <backend-url> to http://127.0.0.1:<tomcat-http-port>/samlsp/backend

   Example:

   <listener>
    <listener-class>se.nordicedge.sp.plugin.SamlSpFilter</listener-class>
    </listener>
    <filter>
    <filter-name>SamlSpFilter</filter-name>
    <filter-class>se.nordicedge.sp.plugin.SamlSpFilter</filter-class>
    <init-param>
    <param-name>entityid</param-name>
    <param-value>pss-sp</param-value>
    </init-param>
    <init-param>
    <param-name>backend-url</param-name>
    <param-value>http://127.0.0.1:8098/samlsp/backend/</param-value>
    </init-param>
    </filter>
    <filter-mapping>
    <filter-name>SamlSpFilter</filter-name>
    <url-pattern>/*</url-pattern>
    </filter-mapping>

Add parameter to dseditor.properties

The SAML SP will convert SAML2 assertion attributes to header values. The header value will be used by PPSS to perform the lookup against LDAP. The SAML SP will name the headers like this:

SAML Attribute Name -> Header name
nameid -> nesp.nameid
givenName -> nesp.givenNamex -> nesp.x

1. Open <im_installation>/webapps/ppss/WEB-INF/NEIDMgmt/dseditor.properties
2. Add parameter. The value match the Header name where the userid is found (see above).

   SERVLET_SSO_HEADER=<Header name>
   

   Example:

   SERVLET_SSO_HEADER=nesp.nameid

3. Add url to redirect the user to in case of errors.

   SERVLET_SSO_REDIRECT=<url_to_error_page>
   

   Example:

   SERVLET_SSO_REDIRECT=http://ppss.local:8098/ppss/jsp/custom/errors/ssoerror.jsp

Test

1. Browse to https://<ppss_server_domain>:<ppss_port>/ppss/NEIDMgmt
2. Browser should redirect to IdP for authentication
3. Autentication on the IdP
4. SAML assertion sent to PSS SAML SP
5. User is logged in

Logout

Add this to DSEditor.properties to perform a logout. This will destroy the SP session and redirect the browser to redirecturl. In this example, the webapp name is ppss.
LOGOFFURI=/ppss/neagent/sp/logout?redirecturl=https://<your_idp>/<logout_uri>

Advanced configuration

For all available configuration settings and an overview of PhenixID SAML SP filter, pls view the documents in the installation zip.