integrates with a variety of SAML authentication providers, or Identity Providers (IdPs). SAML-based SSO is a leading method for providing federated access to multiple applications for your users or end users. This short guide assists you in configuring SAML authentication with your knowledgebase.
The following highlights the steps needed to integrate any SAML 2.0 IdP with an knowledgebase. Please refer to your IdP for instructions on how to configure access to a service provider, where acts as the SP.
To complete the setup, you need:
|
Follow these steps in to configure the SAML connection.
{server}/{KBName}
, e.g. example.agiloft.com/mykb
. Replace any spaces in the Entity Id with the plus (+) symbol.SAML V2 Assertion Consumer Service (ACS) Endpoint: The value in this field should be in the form:
http(s)://{server}/gui2/spsamlsso?project={KBName} |
Write down these two values—they will be used to configure your Identity Provider (IdP). 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
.
Java Key Store (JKS) details. The Private Keys for HTTPS communication with are stored in the Java Key Store (JKS) file on the Server. The same Key pair will be used to digitally sign the SAML XML exchanged between the server and IdP. For more assistance, see: Generate a Keystore File. Enter the following values:
Java Keystore (.jks) file path on the Server. Configurations vary by server. The default path for servers is /opt/server/Agiloft/etc/certs/agiloft.keystore
Java KeyStore Password.
Alias used to add certificate to Java KeyStore.
Name identifier in SAML Assertion sent by IdP: In SAML 2.0 protocol, the NameID XML tag is used to send the details of the authenticated user in the SAML Assertion XML sent by an IdP to the service provider. From the drop-down, specify which format your IdP uses: User Name, Email, or Federation ID.
Then, select the field name in the People table to match against the NameID value. If the NameID value in the XML assertion matches the value of the chosen field, then the user is allowed to log in to .
Below is an example of a NameID TAG in SAML Assertion XML, which provides the email address of the authenticated user:
<saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:email">salesuser1@mydomain.com</saml:NameID> |
If your IdP sends a Federation Id for authenticated users, be sure to create a corresponding field in the People table and populate it with the correct value for the users accessing via SAML.
Name Identifier location in SAML Assertion: Choose the XML tag - NameID
or Attribute -
used by the IdP to send user information. NameID
is the most commonly used XML tag.
If your IdP sends user details in the Attribute TAG, enter the value of the Name
or FriendlyName
attribute. In the example below, USERID_ATTRIB_NAME
is the value of the Name
attribute:
<saml:Attribute FriendlyName="fooAttrib" Name="USERID_ATTRIB_NAME" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string"> salesuser1@mydomain.com </saml:AttributeValue> </saml:Attribute> |
SAML Authentication Profile:
This option determines how interacts with the IdP when a user tries to access .
Select Passive Web Single Sign On with IdP to allow users who are already authenticated by the IdP to access directly. If the user is not already authenticated, shows an error message.
Select Forced Authentication to require a user name and password every time, even if the user has a valid login session with the IdP.
The Default behavior lets users who are already authenticated by the IdP to access . If the user is not authenticated, the IdP prompts a login screen for the user.
If you have a SAML Metadata XML file, paste the contents in the box under SAML Metadata XML contents obtained from your IdP. Leave remaining fields blank and click Next.
When the SAML configuration is saved, automatically populates the remaining fields based on the XML contents.
IdP Entity ID / Issuer: Enter the name or URL identifying the IdP.
IdP Login URL: Enter the URL where should forward login requests.
IdP Logout URL: Enter the URL where should forward logout assertions.
These logout assertions can be used for Single Logout (SLO), which is to say they can not only log a user out of their current Agiloft session, but out of all sessions for the browser that initiated the logout, requiring that the user then log into SSO again before beginning a new session with or another SP. It may be necessary to leave this field blank in order to enable these logout assertions. |
IdP Provided X.509 Certificate Contents: If your IdP provides the X.509 certificate in a file, open the file with a text editor and paste the contents of the certificate file in the input box.
https://test.agiloft.com/gui2/samlssologin.jsp?project=demokb&State=Edit:case&record=350&record_access=view&exiturl=leaveLoggedIn&cancelurl=leaveLoggedIn
. Note that SAML SSO Messages sent to are encrypted using public key cryptography. Agiloft supports the following standard cipher transformations to prepare a message for encryption:
While these cipher transformations should suffice for most commonly used IdPs, if you find that your IdP uses a special cipher transform, you can configure to use it with the Custom Cipher transform for decrypting SAML Keys global variable.
In cases where the Java Keystore file and corresponding private key are required for the SAML installation, which is typically needed when is installed on a server which is not hosted by , use the following steps to generate the Keystore file from the CA certificate and corresponding private key for your organization.
To configure 's SAML SSO Keystore file for servers hosted by , please contact support.
Note that the OpenSSL tool is not present on Windows systems by default. You can download it here on the server and use the same commands in Windows, after logging into the Windows server as an Administrator user.
Create a PKCS 12 file using your private key and CA signed certificate. The following OpenSSL command can be used to do this:
openssl pkcs12 -export -in [path to CA certificate] -inkey [path to private key] -certfile [path to CA certificate ] -out mykeystore.p12 |
Create a JKS file using the Keytool command. Note that you may append the output file as either .jks or .keystore.
<Agiloft_install_dir>/jre/bin/keytool -importkeystore -srckeystore mykeystore.p12 -srcstoretype pkcs12 -destkeystore mycompany.keystore -deststoretype JKS |
The next step is to provide the Service Provider details to the IdP. Configuration steps for SAML 2.0 vary depending on the Identity Provider. Usually, you can import the SAML 2.0 Service Provider Metadata file to the IdP to populate these details, but below are the typical configuration items you are required to supply for the IdP:
(SP) Entity Id, found in step 7.a. The default value is in the form:
{server}/{KBName} |
Login Assertion Consumer Service URL, found in step 7.b. The default value is in the form:
http(s)://{server}/gui2/spsamlsso?project={KBName} |
Logout URL: This value is in the form:
http(s)://{server}/gui2/samlv2Logout.jsp |
Logout Service End Point URL: This value is in the form:
http(s)://{server}/gui2/spsamlssologout?project={KBName} |
Finally, to make sure users log in with SSO after the transition, manually set new passwords for users who should use SSO instead. To do so:
Go to the People table and select every user who should use SSO from this point on.
Don't select every single 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. |
Next, go to Setup > System > Manage Global Variables and check the Customized Variables tab for the Hotlink Type variable. If it has been customized, edit it and reset it to the default value of STANDARD.
You might also notice a setting in the People table called SSO Authentication Method. This field is set automatically by the system when you enable SSO, and should not be modified.
Once the SAML 2.0 integration has been properly configured, users can log in to by authenticating with the IdP.
Point your browser to: http(s)://{server}/gui2/samlssologin.jsp?project={kbName}
, where {server} is the IP Address or FQDN of the server hosting the instance and kbName is replaced by the name of your knowledgebase. 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
. Most users either save this URL as a bookmark (or favorite), or add an HTML login block to an existing web page.
This URL forwards the login assertion to the IdP and directs you to the login page for your IdP:
If you are already logged in and authenticated, you are forwarded directly to the interface.
Note: supports SAMLv2 with Active Directory Federation Services (ADFS) version 2.0 and 3.0 in releases after 2015_02.