SAML-based Single Sign On (SSO)

<< Click to Display Table of Contents >>

EQuIS 7  >>  Enterprise > Installation and Configuration > Configuration > Additional Authentication Options >

SAML-based Single Sign On (SSO)

Security Assertion Markup Language (SAML) is "...a standard, XML-based framework for creating and exchanging security information between online partners" (see OASIS Security Services). Using SAML, an external Identity Provider (IdP) can authenticate a user and then push that authentication to EQuIS Enterprise via a SAML Assertion. A SAML Assertion is a fragment of digitally signed XML that is pushed to EQuIS Enteprise via an HTTP/S post. You may want to use SAML to configure single-sign-on for EQuIS Enterprise. Any SSO system that supports SAML v2.0 assertions may be used. OneLogin, PingOne, and CA Single Sign-On are just a few of the many identity management systems that support SAML-based single sign on. The following sections describe how to configure EQuIS Enterprise to use SAML-based SSO.

 

Configure EQuIS Enterprise as a SAML Consumer

 

The detailed steps for configured EQuIS Enterprise as a SAML Consumer in your identity management system are outside the scope of this article. Please refer to the documentation of your identity management system for further instructions. The most important step is to point the IDP to the correct EQuIS Enterprise URL. Look for a setting called "Application URL" or "SAML Consumer URL" and paste in the full URL to your EQuIS Enterprise ./default.aspx page. For example, if your EQuIS Enterprise URL is http://equis.mycompany.com/equis7, then your SAML Consumer URL is http://equis.mycompany.com/equis7/default.aspx.

 

Configure EQuIS Enterprise to Accept Assertions from your IdP

 

For security purposes, SAML assertions will be ignored unless you properly configure EQuIS Enterprise to accept them. This is done by creating a record in the ST_CONFIG table as follows:

 

ST_CONFIG

VALUE

REMARK

EXAMPLE

CONFIG_SECTION

Authorization

This value must be Authorization as shown.

 

CONFIG_KEY

SAML

This value must be SAML as shown.

 

OBJECT_TYPE

Issuer

This value must be Issuer as shown.

 

OBJECT_VALUE

<IDP Issuer URL>

This is the full URL of the SAML issuer as provided by your identity provider.

https://app.onelogin.com/saml/metadata/405382

STRING_VALUE

<IDP Logout URL>

This value is optional (may be left null); if provided, this is the full logout URL as provided by your identity provider.

https://app.onelogin.com/logout

 

If desired, you can configure EQuIS Enterprise to accept assertions from multiple SAML IDPs by creating multiple records in ST_CONFIG as described above.

 

Configure EQuIS Enterprise to use your custom SSL certificate when validating SAML Assertions

 

If your SAML IdP uses a custom SSL certificate to encrypt SAML assertions, you need to add the public key of that certificate into the EQuIS Enterprise Web.config file (or the Azure Web App Application Settings). For example, suppose your IdP SAML metadata (*.xml) contains the following certificate key (example key shortened for brevity; an actual key would be much longer) :

 

<ds:X509Certificate>

PshasyIIGaDCCBVCgAwIBAgIQC5NyrEUu46OTMuUq2xbfHjANBgkqhkiG9w0BAQsFADBBMQswCQYDVQQGrmShYL8uePeHM6/lslahselkazKZaseh

</ds:X509Certificate>

 

To configure this public key in EQuIS Enterprise, you would go into your Web.config file and add the following appSetting:

 

<add key="{Issuer}" value="PshasyIIGaDCCBVCgAwIBAgIQC5NyrEUu46OTMuUq2xbfHjANBgkqhkiG9w0BAQsFADBBMQswCQYDVQQGrmShYL8uePeHM6/lslahselkazKZaseh" />

 

The key (e.g. "{Issuer}" should be the actual issuer (i.e. the same value you put into ST_CONFIG.OBJECT_VALUE as explained in the previous section).

 

 

Ensure that IDP Users Match EQuIS Users

 

In order for the SAML assertion to be processed (and associated with the proper EQuIS user), the user name and/or email address of each user defined in the IDP must match the same user defined in EQuIS. For example, suppose the IDP defines a user with a name of jsmith with an email address of jsmith@company.com. If EQuIS defines the same user as john.smith with an email address of john.smith@company.com, the SAML assertion will not be accepted. The user name and email address should match in both IDP and EQuIS. When configured properly, a user that has already logged into the IDP and then accesses EQuIS Enterprise, will not be prompted to log in.

 

Exceptions

 

SAML is designed to be used by web applications that interact over HTTP (or HTTPS). As such, SAML-based SSO may be used to authenticate a user to EQuIS Enterprise. However, SAML SSO may not be used with:

 

EQuIS Professional (e.g. when logging in via ALS)

EDP (when doing Sign and Submit)