Skip to main content

Configure Single Sign-On via SAML 2.0

Updated

Single Sign-On (SSO) via SAML 2.0 connects SmartSimple to an organization's Identity Provider, allowing users to authenticate through existing systems rather than maintaining a separate SmartSimple login. SmartSimple acts as the Service Provider and receives and validates the SAML assertion the Identity Provider generates after a user authenticates. For field definitions, see Single Sign-On via SAML 2.0 Settings Reference.

Who: Global Administrators.

When to Use Single Sign-On via SAML 2.0

Configure Single Sign-On via SAML 2.0 when:

  • The organization has an existing Identity Provider and wants users to authenticate with SmartSimple through it.
  • A new SmartSimple instance needs the initial SSO connection configured.
  • A new Identity Provider connection needs to be added alongside an existing one.
  • SSO is being configured across multiple environments (production, backup, development, testing).

↑ Back to top

Prerequisites

Before configuring SSO, confirm the following requirements are met:

  • An Identity Provider service, whether a third-party service or an internally hosted one, has been provisioned. Responsibility for enabling and maintaining the Identity Provider rests with the client organization.

  • A public key in base64-encoded X.509 Certificate format has been provided to SmartSimple for digital signature validation.

↑ Back to top

Configure SmartSimple as the Service Provider

The following steps create an SSO configuration in SmartSimple and establish the Service Provider settings.

  1. Click the System Administration gear in the upper navigation bar, and then select Global Settings from the drop-down menu.
  2. Click the Integration tab, locate the Authentication section, and click Single Sign-On.
  3. Click the New Single Sign-On [+] button to create a new SSO configuration.
  4. Click the SSO Alias field and enter SAML2 for a production instance. This is the default.
    • For non-production instances, enter a unique alias and include the SSOModule attribute in the Identity Provider configuration.
  5. Click a SSO Protocol from the options, which are SAML 2.0 or OpenID Connect (OIDC).
  6. Click the Identity Provider (IdP) X.509 Certificate field and paste the signing certificate provided by the Identity Provider, without the begin certificate and end certificate header and footer lines.
  7. Select a Timestamp Time Zone from the drop-down menu. The default is UTC/GMT.
  8. Locate the Third-Party Identity Provider section and click a Method from the options, which are Identity Provider (IdP) initiated or Service Provider initiated.
  9. Click the IdP Service Endpoint field and enter the redirect URL from the Identity Provider for the selected authentication method.
  10. Locate the Authentication section and select a Unique Identifier Field (UID) from the drop-down menu.
    • The Unique Identifier is the user attribute that matches the NameID value in the SAML assertion, typically Email.
  11. Complete the fields in the Multi-Environment Support (MES) section to group this configuration with other environments under the same login page.
    • The MES Group Identifier is a shared identifier for all environments in this group. For example, SSOID1.
    • The MES Environment Identifier is the domain of this specific environment. For example, alias.smartsimple.com.
  12. Configure additional settings as needed:
    • The Default Landing Page is a relative path if users should land on a specific page after login.
    • Toggle on Create New User When No Match Found if new users should be created automatically on successful SSO authentication.
  13. Click Save.
NOTE  It is recommended to disable the session timeout alert. Click the System Administration gear in the upper navigation bar, then select Global Settings, and click the Security tab. Locate the System Security section and toggle on Disable Session Timeout Login Prompt.
NOTE  To restrict specific user roles to SSO-only login, enable the Enforce SSO setting. Click the System Administration gear in the upper navigation bar, then select Global Settings, and click the Integration tab. Locate the Authentication Settings section and toggle on Enforce SSO.

↑ Back to top

Configure the Identity Provider

The following sections provide configuration steps for three common Identity Provider services. Additional steps may be required depending on the Identity Provider in use. Consult the Identity Provider's documentation for complete guidance.

Before configuring the Identity Provider, gather the following values from the SmartSimple instance:

  • Assertion Consumer Service URL: https://alias.smartsimple.com/SAML2/
  • Service Provider Entity ID: https://alias.smartsimple.com/
NOTE  Replace all instances of alias in example URLs with the instance URL.

Configure Active Directory Federation Services (ADFS)

The following steps are specific to configuring SmartSimple within ADFS. Steps unrelated to SmartSimple configuration have been omitted.

  1. In ADFS, add a new Relying Party Trust.
  2. Select Data Source and import the Service Provider metadata XML file obtained from SmartSimple.
  3. Click Display Name and enter a name for the trust.
    • For example: SmartSimple.
  4. Complete the setup and then click Claim Rules editor.
  5. Select the Issuance Transform Rules tab and add a new rule.
  6. Click Rule Type and use the Send LDAP Attributes as Claims template.
  7. Configure the mapping to the agreed upon user identifier.
    • For example: LDAP attribute "E-Mail-Addresses" to Outgoing Claim Type "NameID."
    • Depending on the ADFS version and setup, two rules may be needed instead: one to map the attribute E-mail to E-mail, and a second rule to transform the E-mail to the outgoing NameID.
  8. To test or use this connection, use the internal ADFS URL and specify the loginToRp parameter as the SmartSimple SAML entity ID.
    • For example: https://adfs.yourlocaldomain.com/adfs/ls/idpinitiatedsignon.aspx?loginToRp=https://alias.smartsimple.com/.
    • If automatic redirection into SmartSimple does not occur, RelayState may need to be enabled in ADFS, then a RelayState parameter used to achieve this. For example: https://adfs.yourlocaldomain.com/adfs/ls/idpinitiatedsignon.aspx?RelayState=https://alias.smartsimple.com.

↑ Back to top

Configure Azure as the Identity Provider

The following steps cover the SmartSimple-specific configuration items required for SSO to function within Azure.

  1. Log in to Azure as an administrator.
  2. Navigate to Azure Active Directory, click Enterprise Applications, and then click Create a new application.
  3. Select Non-Gallery Application and then add the new application by entering the application name.
    • For example: SmartSimple SSO.
  4. Click Add.
  5. Select Single Sign-On, then select SAML.
  6. Complete the Basic SAML Configuration:
    • Identifier (Entity ID): https://alias.smartsimple.com
    • Reply URL (Assertion Consumer Service URL): https://alias.smartsimple.com/SAML2/
  7. Configure User Attributes and Claims. Under Required claim, enter the Unique User Identifier (Name ID).
    • The Unique User Identifier (Name ID) is any unique identifier in the user profile fields, such as user.mail or user.employeeid.
  8. Add the following additional claims. All attribute names are case sensitive.
    • First Name: user.givenname
    • Last Name: user.lastname
    • Email: user.mail
    • Department: user.department
    • Roles: user.assignedroles
    • SSOModule: A constant value matching the SSO Alias configured in SmartSimple.
  9. To test the configuration, navigate to Single Sign-On, click Test this application from the tab header, select Sign in as current user, and then click the Test sign in button.
  10. After configuration is complete, provide SmartSimple with the following:
    • X.509 certificate: Download the Federation Metadata XML. Click SAML Certificates under Single Sign-On.
    • NameID value: The value used as the identifier between the Service Provider and Identity Provider.
    • URL Redirect for IdP-initiated SSO: User Access URL, found under Properties.
    • URL Redirect for SP-initiated SSO: Login URL. Click Set Up [Application Name] under Single Sign-On.
NOTE  Confirm that the current user is an existing contact in the SmartSimple instance.

↑ Back to top

Configure OKTA as the Identity Provider

The following steps cover the SmartSimple-specific configuration items required for SSO to function within OKTA.

  1. Log in to the OKTA administrator account.
  2. Click the Application tab and select Applications.
  3. Click Add Application, then click Create New App to create a new application for SmartSimple.
  4. Set Platform to Web, set Sign on method to SAML 2.0, and click Create.
  5. On the General Settings page, enter an application name.
    • For example: SmartSimple SSO.
  6. Click the Configure SAML tab, and complete the following SAML settings:
    • Single sign-on URL: https://alias.smartsimple.com/SAML2/
      • Check the checkbox for Use this Recipient URL and Destination URL.
    • Recipient URL: https://alias.smartsimple.com/SAML2/
    • Destination URL: https://alias.smartsimple.com/SAML2/
    • Audience URI (SP Entity ID): https://alias.smartsimple.com/SAML2/
    • Default Relay State
    • Name ID format: EmailAddress
    • Application username: Email
    • Update application username on: Default value is Create and update.
    • Response: Default value is Signed.
    • Assertion Signature: Default value is Signed.
    • Signature Algorithm: Default value is RSA-SHA256.
    • Assertion Encryption: Default value is Unencrypted.
  7. Under Attribute Statements, add the following attributes. All attribute names are case sensitive.
    • First name: user.firstName
    • Last name: user.lastName
    • Email: user.email
    • Department
    • Roles
    • SSOModule
  8. After configuration is complete, provide SmartSimple with the following:
    • X.509 certificate: Located under the Sign On tab, in SAML Setup > View SAML setup instructions.
    • NameID value: The value used as the identifier between the Service Provider and Identity Provider.
    • URL Redirect for IdP-initiated SSO: Embed Link, found under the General tab in the App Embed Link section.

↑ Back to top

Add the SSO URL Redirect to the Login Page

The SSO URL redirect sends internal users from the login page to the Identity Provider login page. Complete this step after configuring the SSO connection in SmartSimple.

  1. Click the System Administration gear in the upper navigation bar, select Global Settings, and click the Branding tab.
  2. Click Login Pages.
  3. Click the edit [pencil] icon next to the default login page.
  4. Locate the Single Sign-On section and select the MES Group Identifier from the drop-down menu.
  5. Enter a Link Label.
    • For example: Employee Login.
  6. Click Save.
NOTE  To add the SSO link to a custom login page template, use the @ssodisplaylink@ variable to render the Link Label and hyperlink, or @ssotargetlink@ to retrieve the SSO login URL.

↑ Back to top

SSO Troubleshooting: Frequently Asked Questions

To generate troubleshooting log data, enable Debug Mode in the SSO configuration in SmartSimple, then test the SSO connection to populate the Configuration Error Log.

Why does SmartSimple say "SAML failed. No user account found"?

A matching active user was not found in SmartSimple. Verify the Unique Identifier Field configured in the SSO settings and compare the NameID value in the SAML assertion to confirm a user with that field value exists in SmartSimple. Confirm the user is active and permitted to log in.

↑ Back to top

Why does SmartSimple say "Login session is null" or "Invalid SAML Response"?

  • Confirm a matching user account exists in SmartSimple.
  • Verify the X.509 certificate.
  • Confirm the endpoint in the SSO assertion is correct. The assertion should contain a Response node with a parameter such as Destination="https://alias.smartsimple.com/SAML2/".

↑ Back to top

Why does SmartSimple say "SAML signature validation failed"?

The X.509 certificate in the SAML assertion does not match the certificate configured in the SSO settings in SmartSimple. Update the certificate to match.

↑ Back to top

Why does SmartSimple say "SAML response expired"?

Check the NotAfter and NotBefore datetime values in the SAML assertion and compare them to the expected datetime when the assertion was sent. Adjust the Timestamp Time Zone setting in the SSO configuration if needed. 

↑ Back to top

Why does SmartSimple say "Invalid response format. Unparseable date"?

Confirm the SAML assertion contains both the NotAfter and NotBefore parameters.

↑ Back to top

Why does SmartSimple say "SAML processing error"?

  • Verify the SSO Alias value is SAML2 for the production instance.
  • For a multi-environment configuration, confirm the SSO Alias value matches the SSOModule attribute in the assertion.

↑ Back to top

Why does SmartSimple show no log file?

  • Verify the Destination parameter in the SSO assertion: Destination="https://alias.smartsimple.com/SAML2/".
  • Verify the SSO Alias value is SAML2 for the production instance.
  • For a multi-environment configuration, confirm the SSO Alias matches the SSOModule attribute.

↑ Back to top

Why am I redirected to messagetype=30 after logging in through SSO?

The alias of the instance is incorrect. Click the System Administration gear in the upper navigation bar, select Global Settings, click the Branding tab, and then click Web Alias. Confirm the Web Alias value matches the domain alias.

  • Confirm the alias of the instance is correct.
  • Verify the SSO configuration for multiple environments does not contain duplicate MES Environment Identifiers.

↑ Back to top

Helpful Links