Skip to main content

Configuring SAML SSO Using Federated Authentication

With Agility, you can now configure SAML SSO (Security Assertion Markup Language with Single-Sign-On) using the Federated Authentication Module. The following procedure helps you to setup SAML SSO with your company's Identity Provider (IdP), such as Office 365, OKTA, and so on.

Information Needed to Configure Your IdP​

Service Provider (SP) Endpoints:

  • Single Sign-On URL (Assertion Consumer Service): https://{webhost}/{webinstance}/SamlAuth.mvc/Assertion
  • Single Log Out URI (Optional): https://{webhost}/{webinstance}/SamlAuth.mvc/LoggedOut
  • Audience URI / SP Entity ID (Suggested): urn:digitalai:agility
    (You can use a different value, but it must match the Saml2:Issuer configuration)

Required from IdP:

  • IdP Metadata: Either a metadata XML file or a URL that provides the metadata
  • Signature Validation Certificate: Typically included in IdP metadata, so manual configuration is rarely needed

Configure Agility​

Add the following configuration lines to Agility user.config: {app-root}\user.config

<add key="IsFederatedAuthModuleEnabled" value="true" />
<add key="Saml2:IdPMetadata" value="{path-to or url}{idp-metadata.xml}" />
<add key="Saml2:Issuer" value="urn:digitalai:agility" />
<add key="Saml2:SignatureAlgorithm" value="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />
<add key="Saml2:RevocationMode" value="NoCheck" />
<add key="Saml2:CertificateValidationMode" value="None" />
<add key="WebRoot" value="https://{webroot}" />

 <!-- optional 
<add key="Saml2:SignatureValidationCertificate" value="{pathto}/certificate.pem" />
<add key="Saml2:SignatureValidationPassword" value="{password}" />
<add key="Saml2:SigningCertificateFile" value="{path-to-Signing-Certificate-File}" />
<add key="Saml2:SigningCertificatePassword" value="{password}" />
<add key="Saml2:DecryptionCertificate" value="{path-to-Decryption-Certificate-File}" />
<add key="Saml2:DecryptionCertificatePassword" value="{password}" />
<add key="Saml2:IdentityClaim" value="{custom-identity-claim}"/>
<add key="FederatedSsoSessionLifetime" value="{seconds as int}>
-->

Configuration parameters:

Optional parameters:

  • Saml2:SignatureValidationCertificate: The path to your certificate used when IdP assertions are signed. ^
  • Saml2:SignatureValidationPassword: The certificate password.
  • Saml2:SigningCertificateFile: The path to your certificate for SP to sign its Authn requests with. ^
  • Saml2:SigningCertificatePassword: The certificate password.
  • Saml2:DecryptionCertificate: The path to your certificate when IdP assertions are encrypted. ^
  • Saml2:DecryptionCertificatePassword: The certificate password.
  • Saml2:IdentityClaim: By default Agility will use the Name Identifier claim to map incoming SAML identity to its application user. You may specify a different custom claim attribute from the assertion payload.
  • FederatedSsoSessionLifetime: If a session lifetime is not specified in the assertion payload via SessionNotOnOrAfter attribute of <AuthnStatement> element, a lifetime value may be set explicitly for SessionSecurityToken expiration. By default, once authenticated, SSO session has an indefinite lifetime.

^ You must keep it outside of the application directory

Configure SP-initiated Log Out Action (Optional)​

Add the following configuration lines to Agility user.config: {app-root}\user.config

<add key="DelegatedLogoutAllowed" value="true" />
<add key="LogoutRedirectUrl" value="https://{webhost}/{webinstance}/SamlAuth.mvc/LogOut" />
<add key="FederatedLogoutRedirectUrl" value="{url}" />

Configuration parameters:

  • LogoutRedirectUrl: Update this with your web instance.
  • FederatedLogoutRedirectUrl: The URL where users are redirected to after they log out.

Additional configuration:

In the IIS application pool for your site, you may need to update Advanced Settings > Load User Profile from False to True.