SAML 2.0

Enterprise Tester with SAML 2.0 capable identity provider services

Enterprise Tester supports SAML 2.0 connections to an external Identity Provider (IdP).

While ET should work with most IdPs that support SAML 2.0, we currently only test with the following IdPs:

This article will cover the basics, from the Enterprise Tester side of the configuration, and then provide an example of setting up Okta with Enterprise Tester showing both Okta and Enterprise Tester configuration.

Tips

  • While a SAML 2.0 configuration is enabled, it will also be enforced when attempting to log into the application GUI. This means that local user accounts and passwords will no longer work for this purpose.
  • Enterprise Tester API requests do not support SAML 2.0. The existing API authentication methods will continue to work as normal whether SAML 2.0 is configured or not.
  • Enterprise Tester SAML 2.0 connections only handle authentication. User accounts, groups and permissions must be configured in Enterprise Tester separately.

SAML 2.0 Configuration Basics

Currently, a SAML 2.0 connection cannot be configured via the Enterprise Tester user interface; It must, instead, be configured via a configuration file located on the server Enterprise Tester is running on.  This is done by adding several key/value pairs to the appSettings section of the web.config file.  For more information about appSettings, please refer here.

To be able to configure several of the following properties, the IdP must be prepared first.  The process will differ in different IdPs, an example of configuring Okta is given further down in this article.

KeyPurposeDefault ValueExampleNotes
SAML.EnabledTo turn SAML support on or offfalse<add key="SAML.Enable" value="true"/>Required setting
SAML.ProviderUsed to switch between implementation styles of SAML 2.0n/a<add key="SAML.Provider" value="Microsoft" />Required setting (for most situations)
This should usually be set to "Microsoft" but you may need to omit this setting all-together, depending on IdP
SAML.IssuerIDP Issuer URLn/a<add key="SAML.Issuer" value="http://www.okta.com/cKZ3800234nlvM8s"/>Required setting
Requires IdP configuration first
SAML.IDPIDP SSO URLn/a<add key="https://cust.okta.com/app/appname/cKZ3800234nlvM8s/sso/saml"/>

Required setting
Requires IdP configuration first

SAML.CertificateX.509 Certificaten/a<add key="-----BEGIN CERTIFICATE----- certificate body -----END CERTIFICATE-----"/>Required setting
Should be entered as a single line and should include the begin and end certificate tags
Requires IdP configuration first
SAML.LogoutURL that a user will be redirected to if they choose to log out of Enterprise TesterEnterprise Tester Login URL<add key="SAML.Logout" value="https://myapps.microsoft.com"/>Optional setting
If not configured, a user choosing the logout option will be automatically logged back in again provided there session is still active with the IdP.

SAML.SignRequest

To turn SAML request signing support on or offfalse

<add key="SAML.SignRequest" value="true" />

Optional setting
Some IdPs support/require SAML request signing while other Idps ignore the signed status of a request.  If this option is set to true the following properties must also be configured:
SAML.SigningCertificateFile
SAML.SigningCertificatePassword
SAML.SigningCertificateFileLocation of the Signing Certificate.  The signing certificate should be a pkcs12 certificate and have the private key embeddedn/a<add key="SAML.SigningCertificateFile" value="d:\certs\saml_exp_2022.10.01.pfx" />

Required if SAML.SignRequest is set to true
Some cryptographic providers that might be used to encrypt the private key require a user profile in order to function properly.  As such please make sure that the "Load User Profile" option in the Advanced Settings of the Application Pool (in IIS) that runs Enterprise Tester is set to "True"

SAML.SigningCertificatePasswordPassword for the private key in the pkcs12 certificate identified in the SAML.SigningCertificateFile propertyn/a<add key="SAML.SigningCertificatePassword" value="changeit" />

Required if SAML.SignRequest is set to true
As the web.config file is in XML format, some special characters will need to be escaped if they are used in the password

CharacterEscaped value
"
&quot;
'
&apos;
<
&lt;
>
&gt;
&
&amp;


Example of the configuration as it might appear in the web.config file alongside other settings

<appSettings>
    <add key="site.root.url" value="https://apps.corp.com/et" />
    <add key="Licensing.ServerKey.GenerationMode" value="Stable" />
    <add key="migration.providerName" value="Migrator.Providers.SqlServer.SqlServer2005Dialect" />
    <add key="PathService.PackagePathSeparator" value="|" />
    <add key="aspnet:MaxHttpCollectionKeys" value="10000" />
    <add key="attachment.storage.method" value="FileSystemCas" />
<!-- SAML CONFIGURATION START -->
    <add key="SAML.Enabled" value="True" />
    <add key="SAML.Provider" value="Microsoft"/>
    <add key="SAML.Issuer" value="http://www.okta.com/cKZ3800234nlvM8s" />
    <add key="SAML.IDP" value="https://cust.okta.com/app/appname/cKZ3800234nlvM8s/sso/saml" />
    <add key="SAML.Logout" value="https://catchsoftware.com" />
    <add key="SAML.Certificate" value="-----BEGIN CERTIFICATE----- LIIC2jCCAkMCAg38MA0GCSqGSIb3DQEBBQUAMIGbMQswCQYDVQQGEwJKUDEOMAwGA1UECBMFVG9reW8xEDAOBgNVBAcTB0NodW8ta3UxETAPBgNVBAoTCEZyYW5rNEREMRgwFgY4VQQLEw9XZWJDZXJ0IFN1cHBvcnQxGDAWBgNVBAMTD0ZyYW5rNEREIFdlYiBDQTEjMCEGCSqGSIb3DQEJARYUc3VwcG9ydEBmcmFuazRkZC5jb20wHhcNMTIwODIyMDUyNzQxWhcNMTcwODIxMCUyNzQxWjBKMQswCQYDVQQGEuJKUDEOMAwGA1UECAwFVG9reW8xETAPBgNVBAoMCEZyYW5rNEREMRgwFgYDVQQDDA93d3cuZXhhbXBsZS5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC0z9FeMynsC8+udvX+LciZxnh5uRj4C9S6tNeeAlIGCfQYk0zUcNFCoCkTknNQd/YEiawDLNbxYqutbMDZ1aarys1a0lYmUeVLCIqvzBkPJTSQsCopQQ9V8WuT252zzNzs68dVGNdCJd5JNRQykpwexmnjPPv0mvj7i8XgG379TyW6P+WWV5okeUkXJ9eJS2ouDYdR2SM9BoVW+FgxDu5BmXhozW5EfsnajFp7HL8kQClI0QOc79yuKl3492rH6bzFsFn2lfwWy9ic7cP8EpCTeFp1tFaD+vxBhPZkeTQ1HKx6hQ5zeHIB5ySJJZ7af2W8r4eTGYzbdRW24DDHCPhZAgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAQMv+BFvGdMVzkQaQ3/+2noVz/uAKbzpEL8xTcxYyP3lkOeh4FoxiSWqy5pGFALdPONoDuYFpLhjASZaEwuvjI/TrrGhLV1pRG9frwDFshqD2Vaj4ENBCBh6UpeBop5+285zQ4SI7q4U9oSebUDJiuOx6+tZ9KynmrbJpTSi0+BM= -----END CERTIFICATE-----" />     <add key="SAML.SignRequest" value="true" />
    <add key="SAML.SigningCertificateFile" value="d:\certs\saml_exp_2022.10.01.pfx" />
    <add key="SAML.SigningCertificatePassword" value="changeit" />
<!-- SAML CONFIGURATION END -->
</appSettings>


Example - Enterprise Tester with Okta

Okta is an enterprise-grade, identity management service, built for the cloud, but compatible with many on-premises applications. With Okta, IT can manage any employee's access to any application or device. Okta runs in the cloud, on a secure, reliable, extensively audited platform, which integrates deeply with on-premises applications, directories, and identity management systems.

https://www.okta.com/

Configuring Okta

1) In Okta, create Enterprise Tester integration using SAML 2.0.



2) In Okta the SAML General Settings need to contain the following.

  • Single Sign URL - this must be your Enterprise Tester instance e.g https://enterprisetester/authentication/SAML2.rails
  • Audience URI - this is A9CC4713-F3D5-4321-9C19-14A58E117364




3) Make sure you record IDP information when selecting the "View Setup Instructions".




Configuring Enterprise Tester to use Okta

Add the following keys to the appSettings section in the Enterprise Tester web.config file.  Note: Values used within these appsettings will be available after completing the Okta configuration above.

 

1) Enable SAML Support


<add key="SAML.Enabled" value="true" />


2) IDP Issuer


<add key="SAML.Issuer"value="<IDP Issuer>"/>


3) IDP SSO URL


<add key="SAML.IDP"value="<IDP SSO URL>"/>


4) X.509 Certificate


<add key="SAML.Certificate"value="<X.509 Certificate>"/>


5) Specify logout url

Do not add an Enterprise Tester URL here or users will be automatically logged back into Enterprise Tester.

The Okta applications page is a suggested url that could be added.


<add key="SAML.Logout"value="https://your_selected_logout_page"/>



SHA-256 XML Signature Support

SAML 2.0 uses the SHA-256 encryption protocol if this is not enabled on your server you will need to enable it.