Page tree

Salesforce SAML Integration

Use this topic to assist you in configuring Agiloft with SAML using Salesforce as the Identity Provider. This way, you can establish a single sign-on connection between Salesforce and Agiloft, where Salesforce acts as the Identity Provider for SAML-based SSO. For more information on Salesforce configuration, see Salesforce Help. For more detailed information on configuring SAML in  Agiloft, see SAML 2.0 SSO.

Prerequisites

To complete these steps, you need a Salesforce account with administrator access. You can sign up for a free trial account to use for testing. You also need admin access to your Agiloft Knowledgebase.

Register the Salesforce Domain

The full setup requires you to switch between  Agiloft and Salesforce, so open each one in its own browser window so you can easily switch between them.

To begin:

  1. In the Salesforce account, click the Setup icon to open the Setup Home.

    Note: You may need to switch to the new Salesforce Lightning interface at https://<domain name>.lightning.force.com/one/one.app#/home
  2. In the Quick Find search box in the left pane, enter "my domain", then select the search result.
  3. Add a domain name in the field, and click Check Availability. 
  4. Once you find an available domain, click Register Domain
  5. When the domain has been registered, you will receive an email to confirm that it is ready to use. 

Configure Salesforce as an Identity Provider

  1. In Salesforce Setup, enter "identity provider" in the Quick Find search box, then select the search result.
  2. In the Identity Provider window, click Enable Identity Provider. 
  3. This opens the Identity Provider Setup window, which contains the necessary information to configure  Agiloft.
  4. Click Download Certificate and save the file to a location on your system. 
  5. Open the file in a text editor such as Notepad++ so that you can copy the contents. 

Enable SAML in Agiloft

  1. Click the Setup gear in the top-right corner and go to Access > Configure SAML 2.0 Single Sign-On.
  2. In the General tab:
    1. Select Enable SAML SSO.
    2. Select Create SAML IdP Authenticated user in Agiloft, if you wish to provision a new user on login if one does not exist.
    3. Select Employees in the drop-down to add users to the Table/Subtable shown below.
    4. Select the last checkbox only if you want to synchronize the user attributes in  Agiloft with those in Salesforce every time a user logs in. If you leave this deselected, the user's attributes will be synchronized only when the user is first created. 
      General tab options
  3. Select the Service Provider Details tab.
    1. For the Keystore file path, Java KeyStore Password, and Alias to add the certificate to the Java KeyStore...
      1. If you are using Agiloft's hosted service, the fields will be populated by Support.
      2. If you are using an in-house server where Agiloft is installed,  see Generate a Keystore File, and refer to the further information in the SAML 2.0 SSO topic to populate the fields.
  4. Click Finish. 
  5. Download the  Agiloft X.509 Certificate and and save it to your disk. 
  6. Click Configure SAML 2.0 Single Sign-On to reopen the SAML configuration wizard.
  7. Leave the Service Provider Details tab open while you continue with the steps below. 

Create a Connected App in Salesforce

  1. In the Quick Find search box, enter "app manager", then select the search result. 
  2. In the Lightning Experience App manager window, click New Connected App. 
  3. Enter the app details in the Basic Information section based on your system.
  4. In the Web App Settings, select Enable SAML. This will open additional fields which you must populate from the  Agiloft Service Provider Details tab:
    1. Start URL - enter the base URL for the  Agiloft knowledgebase. Whenever possible, make sure to use the domain name for your server, such as example.agiloft.com, rather than the specific server hostname, such as ps108.agiloft.com.
    2. Entity ID - enter the Agiloft (SP) Entity ID.
    3. ACS URL -  enter the  SAML V2 Assertion Consume Service (ACS) Endpoint.
    4. IdP Certificate - select the Default IdP Certificate. This will populate the Issuer and Name ID Format. 
    5. Select Verify Request Signatures, then click Choose File to locate the  Agiloft X.509 certificate from earlier.
    6. Click Save at the bottom. 
  5. In the Quick Find search box, enter "connected apps", then select the search result. 
  6. In the list of apps in the Connected Apps window, select the Master Label of the app you just created. This opens a view of the app details. 
  7. Click Download Metadata to download the app metadata XML file, and save it to a location on your system. 
  8. Open the metadata file in your text editor and copy the contents. 
  9. Click Manage Profiles. 
  10. Select the System Administrator profile, then click Save. This will give access to your current user profile which will enable you to test that the connection was established successfully. 

Add Identity Provider Details in  Agiloft

  1. In the SAML Configuration wizard, select Identity Provider Details. 
  2. In "SAML Metadata XML contents obtained from your IdP", paste the contents of the Salesforce app metadata file. 
  3. Click Finish. This will automatically populate all of the Identity Provider Details fields, including the X.509 certificate, which is included in the metadata. 

Establish the SAML Connection

  1. To test the SAML connection from the IdP-initiated side, in the Salesforce window click the IdP Initiated Login URL. If the connection has been established successfully, this will open the  Agiloft knowledgebase, with the user created.  
  2. To test the Agiloft-initiated login, point your browser to: https://{server}/gui2/samlssologin.jsp?project={kbName}, where {server} is the IP Address or FQDN of the server hosting the Agiloft instance and kbName is replaced by the name of your knowledgebase. Whenever possible, make sure to use the domain name for your server, such as example.agiloft.com, rather than the specific server hostname, such as ps108.agiloft.com.
    1. This URL forwards the login assertion to the IdP. You will be directed to the Salesforce SAML login page. 

    2. If the user does not exist in the ADFS server, they will automatically be provisioned once ADFS authenticates the user successfully if you selected Create SAML IdP Authenticated user in Agiloft during the setup.
    3. If you are already logged in and authenticated, you will be forwarded directly to the Agiloft interface.

Force SSO Login

To force users to log in with SSO, you can prevent them from accessing Agiloft with their username and password. Follow the steps below to make the Password field optional in the Employees table and then remove passwords for employees who should log in with SSO.

  1. First, make the Password field optional in the Employees table:
    1. Go to Setup Employees and go to the Fields tab.
    2. Edit the Password field and go to the Options tab.
    3. Find the Make this a required field setting and change the value from Yes to No.
    4. Click Finish to save the change.
  2. Next, for employees who should always use SSO to log in, reset their passwords to a null value:
    1. Go to the Employees table and select each user who should use SSO from this point on.
      Don't select every user in your system. It's best to leave at least one administrator unchanged, if not the whole admin team, in case you encounter SSO issues in the future that prevent users from logging in with SSO.
    2. Click Edit Fields in the action bar.
    3. Select Password, then click Next.
    4. On the Update tab, select A formula.
    5. In the Password field, enter the variable $global.null and click Next.
    6. On the Confirm tab, clear the Run rules and Update defaults checkboxes, then click Finish.

Now, users whose passwords were reset can only log in with SSO.

If you also allow some external users to log in with SSO, repeat the process for the External Users table.