For more information on our SSO Integration please see our What is Pentana Risk SSO? guide or contact the Support Team.

Section 1. What needs to be done before SSO is configured? 

Pentana Risk site-admins will need to: 

• Ensure that no duplicate email addresses are used in the system.  

This is because SSO uses email addresses to identify the User profile for login. This can be done by running a User Report on their Pentana Risk system.  

The report must look at all Users (including inactive) and the layout must include ‘User First Name’, ‘User Last Name’, and ‘Email address’ fields. Exporting this into Excel and searching for duplicates in the email address field will identify any problem Users. This can be done with the formula “=IF(COUNTIF(C:C, C)>1, "Duplicate", "")” where C is the column containing the email field.  

• Decide whether a test site should be used to minimise disruption to end users.  

SSO can only be enabled on a site-wide basis. Once enabled, users accessing the site via any URL other than ‘<sitename>.pentanarpm.uk/login’ will be directed to the SSO login if they are not currently logged in. Test sites are available for use, the only difference is a change in URLs and the need to set up test users to check access. These test sites are cleansed after each use, and all customer data is removed. 

Your IT team/contact will need to:

• Ensure that your Identity Provider (IdP) can be configured manually, without the use of metadata.  

Our SSO implementation doesn’t publish or consume metadata, and so the connection must be manually configured.  Current implementations include Azure AD, Microsoft AD, Google IdP and Shibboleth, but any form of active directory which uses SAML 2.0 should be compatible.  

• Provide us with a copy of your IdP URL and your public encryption certificate (this may be self-signed) or your IdP metadata XML file. 

This allows us to configure the connection settings on our end and enable SSO. Exporting the certificate is covered under each implementation guide in the second part of this document. 

 Pentana Risk Support will provide you with: 

• Your SP/Application URL and the POST binding SP URL.  

These are used to configure the connection between your Penatana Risk site and your IdP. If a Test site has been used, then upon completion of testing these URLs will need to be changed to your Live site.  

• A copy of our public signing certificate.  

This is used to authenticate and encrypt your login requests. This will be stored in your IdP against the connection settings. This can be found attached to this guide or on request from Pentana Risk Support. 

Section 2. Configuring SSO 

Active Directory Federated Services SSO (ADFS) 

ADFS SSO is configured via a relaying party.  

The relaying party configuration must be as follows: 

1. On the ‘Select Data Source’ screen, you must choose to enter data about the relaying party manually. 
2. On the ‘Specify Display Name’ screen, enter a Display name of your choosing and any notes. 
3. On the ‘Choose Profile’ screen, select must be ADFS type. 
4. On the ‘Configure Certificate’ screen, you must include out token encryption certificate which will be provided by the support team. 
5. On the ‘Configure URL’ screen, you must use the SAML 2.0 SSO protocol. The service URL created here will be the IdP URL used in our internal configuration process. 
6. On the ‘Configure Identifiers’ screen, the relaying party trust identifier will be https://<yoursitename>.pentanarpm.uk 
7. On the ‘Finish’ screen select ‘Open the Edit Claims rule’  
8. In the ‘Edit Claims’ editor, select ‘Add Rule’ and create the following claim rules: 
   1. LDAP Attribute: E-Mail-Addresses  
   2. Outgoing Claim Type: E-Mail Address 
9. Access the relaying party properties, and select the ‘Endpoints’ tab. Her you will need to add a SAML Consumer type POST-binding endpoint, using the following URL: https://<yoursitename>.pentanarpm.uk/cpmweb/sso/samlresponse 

To export your ADFS public encryption certificate: 

1. Open AD FS 2.0 and navigate to Service > Certificates.  
2. Here, you will find the Token-signing certificate for your AD FS server that is used to authenticate your Security Assertion Markup Language (SAML) connection.  
3. Click the Token-signing certificate.  
4. In the Actions section, click View Certificate.  
5. Click the Details tab, click Copy to File, and then click Next.  
6. Select Base-64 encoded X.509 (.CER) and click Next.  
7. Click Browse, select a location, enter a file name, and then click Save.  
8. Click Next, and then click Finish. 

You will then need to provide the Support Team with a copy of your certificate and your IdP URL for them to configure your SSO Implementation. 

Azure AD SSO 

Azure AD SSO is configured as a non-gallery app. The configuration stages are as follows: 

1. To add an unlisted application, go to: Active Directory > Application Gallery. Search for Pentana Risk and then select ‘Non-Gallery Application’.  
2. Select ‘Configure Single Sign-on’ and choose ‘SAML-based Sign-On’. 
3. You will need to manually enter the metadata as follows: 
   • ‘Identifier’: https://<yoursitename>.pentanarpm.uk 
   • ‘Reply URL’: https://<yoursitename>.pentanarpm.uk/cpmweb/sso/samlresponse 
   • ‘Sign on URL’: https://<yoursitename>.pentanarpm.uk/cpmweb/login 
4. Under the ‘Attributes’ tab set the SAML Token Attributes to a one claim rule for email. This is used by Pentana Risk to identify the user logging in.  
5. Under the ‘SAML Signing Certificate’ panel you can access your App Federation Metadata URL and your application certificate. You will need to provide these to the Pentana Risk Support team so that they can configure your sites SSO.  
6. You will then need to manage your user groups to grant access to the application. Any users on the IdP without a Pentana Risk user account will not be able to login to the application.  

Google Authentication Services SSO 

Google Authentication Services SSO is configured by creating a ‘Custom App’ in the Admin directory.  

1. Sign into your Google Admin console. 
2. From the Admin console Home page, go to Apps, SAML Apps. To see Apps on the Home page, you might have to click More controls at the bottom.  
3. Click the plus (+) icon in the bottom corner. 
4. Click Set up my own custom app. 
   The Google IDP Information window opens, and the Single Sign-On URL and the Entity ID URL fields automatically populate. 
5. You will need to record/store this information for the Pentana Riskimplementation: 
   • Entity ID, 
   • Single Sign-On URL, 
   • Download the X.509 Certificate. 
6. Click Next. 
7. In the Basic Application Information window, add an application name and description for the Pentana Risk application. 
8. (Optional) Click ‘Choose file’ next to the Upload Logo field to upload a PNG or GIF file to serve as an icon. The file size should be 256 pixels square. The Pentana Risk logo is available on request from the support team. 
9. In the Service Provider Details window, you will need to add the following fields: 
   • Assertion Consumer Service URL: https://<yoursitename>.pentanarpm.uk/cpmweb/sso/samlresponse 
   • Entity ID: https://<yoursitename>.pentanarpm.uk 
   • Start URL: https://<yoursitename>.pentanarpm.uk/cpmweb/login 
10. Leave Signed Response unchecked. Change the ‘Name ID’ format from ‘Unspecified’ to ‘Email Address’. 
11. Click Next. 
12. Click Add new mapping. Select ‘Basic Information’ and then ‘Primary Email’ from the dropdown boxes and name the Mapping ‘mail’. 
13. Click Finish. 
14. Click ‘OK’ on the final window and provide Pentana Risk Support with your IdP information.  

Section 3: Troubleshooting SSO 

Site Admin Users in Pentana Risk have view-only access to our SSO configuration page, allowing them to see the error logs, the IdP URL and the certificate used. This can be accessed by clicking on the ‘Go To..’ menu, selecting ‘Site Admin’ and then ‘Manage SSO’.  

This page can be used to troubleshoot configuration and investigate login issues for end-users. 

Using the Error Log 

Specific User(s) failure: 

When SSO login fails for a specific User(s), this is usually due to issues with the User profile itself. The error logging and the Audit Trail can be used to diagnose these issues: 

A standard error message for this issue will look like:  

“[Time/Date stamp]- No user found with email address [email address]; SSO Failed”. 

This is due to the User attempting to login via SSO not having a valid User profile in Pentana Risk. Common things to check are: 

1. There is no User profile configured for this User. 
2. A User existing without an email address. 
3. The User not being in a valid state to login (inactive).  
4. The email address has been used for multiple Users in the system. 

All Users Failure:

When all Users are unable to login via SSO, this generally indicates an issue with the SSO configuration. There are several variations on how this will fail, and each one is a symptom of a different configuration error: 

1. The redirect from the IdP login page fails:  
   • If there is an error log indicating a failure for an individual User, troubleshoot using the above section.  
   • If there are no SSO error logs, check that the IdP endpoint is set to ‘SAML Consumer’ type, with a ‘POST’ binding and that the URL is correct (‘https://<yoursitename>.pentanarpm.uk/cpmweb/sso/samlresponse’.)  
2. There is a login failure referencing invalid attributes in the SSO error logs:  
   • Ensure that the IdP has been configured to use email/mail claim only, as this is the only claim our system accepts.  
   • Check the URL config in the IdP  to ensure that the redirect is configured correctly to our POST-binding endpoint. 
3. There is an invalid encryption error in the SSO Error logs:  
   • Ensure that both parties are using valid, in date certificates (this can be checked in the metadata at the top of the SSO Admin page).   
   • Ensure that the customer certificate being used is a valid signing certificate (this can be primary or secondary, provided it is valid and in date).  
   • Refresh certificates in both the IdP configuration and the SSO configuration to ensure that there are no errors.   
4. Users being forced to login to the IdP each time they access the site, even when they have a valid session open:  
   • Sessions time out, prompting a refresh of the login, so ensure that the open session is still active. 
   • If the session is still active, check that the User is not accessing the application via the SSO login URL (<sitename>.pentanarpm.uk/cpmweb/login) as this will always take Users via the re-login process.  
   • If this is correct, check the ‘Global Encryption settings’ in your IdP, looking for the ‘Integrated authentication on Intranet sessions’ option. This ensures that your IdP isn’t configured to request a new session every time the User tries to access the resource.