Single Sign-On

Overview

SmartSimple offers Single Sign-On (SSO) integration via SAML 2.0. It is important to recognize that SSO is a subset of federated identity management, focusing solely on authentication and not on account management or synchronization with SmartSimple.

The implementation of SSO necessitates configuration within both SmartSimple and the authentication-providing system.

In SmartSimple's SSO implementation, it functions as the Service Provider, assuming that the client possesses the necessary infrastructure and resources to host, configure, and manage the Identity Provider service. For further assistance, please reach out to your account manager or SmartSimple Support.

SAML 2.0

SmartSimple supports SAML (Security Assertion Markup Language) 2.0 as the Service Provider through our proprietary implementation of this standard.

Identity Provider-initiated authentication is supported, allowing the end user to first authenticate on the client-side system/infrastructure before being redirected to SmartSimple. The client Identity Provider service will generate a base64-encoded SAML assertion and transmit this to the user's browser, which will subsequently relay the assertion to the SmartSimple server for SSO authentication.

Following the upgrade in November 2022, Service Provider-initiated authentication is now also supported. The Service Provider sends the SAML Authorization Request message and redirects the user to the client Identity Provider service for authentication. After the end user has successfully authenticated, the client Identity Provider service will redirect them back to the SmartSimple instance along with a base64-encoded SAML assertion response. The user's browser will then relay this assertion to the SmartSimple server for SSO authentication.

Prerequisites

• You must provision your own Identity Provider service, whether third-party or otherwise, to utilize this feature. The responsibility for enabling and maintaining the Identity Provider lies with you.
• You are required to provide SmartSimple with a public key in base64-encoded X.509 Certificate format for digital signature validation.

Service Provider Configuration - SmartSimple

In SmartSimple, SSO settings can be accessed through the Global Settings → Integration tab.

You will be directed to the List View of the SSO configuration page. Click on the “+” icon to create a new SSO configuration within the instance:

Mandatory Settings

• SSO Alias - utilized to identify the SSO connection, and it should be configured by default to 'SAML2'. If multiple SSO connections are to be configured, you may include an additional element on the client-side assertion named 'SSOModule' to specify the SmartSimple connection by matching a unique "SSO Alias" value.
• Unique Identifier Field (UID) - employed to identify the user account and must be an attribute that is unique to each user in SmartSimple. The value for the attribute "NameID" from the SSO assertion should correspond to the value from the field selected in the dropdown list (typically an email address or employee ID).
• X509Certificate (SAML2 Only) - the signing certificate to be provided by the client. The format should consist of the certificate value without the "begin certificate" and "end certificate" header and footer lines. Depending on how the client-side system transmits this value within the SAML assertion, the certificate value may typically be formatted as a single line or possibly multiple lines, and must be entered into SmartSimple in the same format.
• Timestamp Time Zone - used to interpret the incoming SSO message timestamp from the Identity Provider's configured time zone. The default value is "--UTC/GMT--". Settings should be adjusted if the error "SAML response expired" appears in the log file during debug mode.
• Third-Party Identity Provider - specify the SSO authentication method being used (Identity Provider-initiated or Service Provider-initiated)
  • Endpoint - specify the redirect IdP-initiated or SP-Initiated endpoint. This redirect will be rendered on the Login Page.
• It is also advisable to disable the Session Timeout Alert setting within the Global Settings → Security section, as this feature would not be applicable to users logged in via single sign-on.
• By default, SSO serves as an additional method of authentication. If you wish to mandate the use of SSO and restrict regular username and password authentication, this can be achieved through the Global Settings → Integration → Enforce SSO setting, which allows you to restrict a specific set of user roles to only log in via SSO.

Additional Settings

• Bypass Two Factor Authentication - bypass Two Factor Authentication when logged in with SSO.
• Enable Debug Mode - when enabled, this option disregards the SSO timestamp and outputs the SSO assertion message in the Configuration Error Log.

• Default Landing Page - used to specify an initial landing page within the SmartSimple instance. This should be a relative path (e.g., /iface/ex/ax_index.jsp).

• Logout Redirect URL - redirect URL when SSO users log out.
• Enable Logout Assertion - will send a logout assertion to the Identity Provider to terminate that session.

Additional settings for Enable Logout Assertion:

Assertion Target URL - target site URL.

Assertion Private Key - private key to establish a connection with the target site.

User Creation Option (JIT Provisioning)

When users need to be created on-the-fly following SSO authentication, the following configuration settings are available:

• Create New User on No Match – when enabled, this option will create a new user if no match is found and will permit login for the new user upon successful authentication.
• Define User Roles Through Custom Attribute – when enabled, this option will utilize the SSO assertion “Roles” attribute to define users’ system roles.
• Default User Role When No Matching Role Found * – the selected role from this dropdown will be assigned to newly created users only if the “Roles” attribute in the assertion is empty, excluded, or if the role name value does not match any existing role in your SmartSimple instance.
• Default New User Status  – assigned user status for new users only.
• Create New Organization When No Match Found  – when enabled, this option will create a new parent organization if no matching organization exists in your SmartSimple instance.
• Default Organization * – assigned user’s parent organization for new users.
• Default New Organization Status – assigned status for new organizations.

* - mandatory fields when creating users through SSO.
Additionally, optional attributes can be included in the assertion to create the user, ensuring that standard fields (First name, Last name, Email) will be populated. If the selected Unique Identifier Field (UID) is not the standard email address, the custom field selected will also be populated during JIT provisioning.

Optional Attributes

The following optional attributes may be utilized in the assertion. It is important to note that these attributes are case sensitive and must be labeled precisely.

• SSOModule - utilized to specify the SmartSimple SSO connection when multiple connections are configured, e.g., "SAML2" for production, "SSOBK" for backup instance, "SSODEV" for development instance, "SSOTest" for test instance. Please be aware that both the attribute name and the attribute value are case sensitive.
• Email
• First Name
• Last Name
• Department - utilized to update the user's organization. This will attempt to match an organization by name and will relocate the user to that organization if found.
• Roles - utilized to update the user's roles in SmartSimple for new users. This should be a comma-delimited list of SmartSimple user roles (by name) to be assigned to the user.
• Language - utilized to specify the initial language displayed to the user. This should be an integer value that corresponds with a language ID value in SmartSimple (e.g., 1=English).

Role Mapping

Implement Role Mapping for both new and existing users to manage user roles within your SmartSimple system. Define the list of system roles you wish to monitor during each SSO authentication by a user. With external role mapping enabled, a user's roles within the system will be adjusted according to the role attributes explicitly provided by the assertion. Based on the role mapping outlined below, the user will be provisioned with all roles as defined by the assertion attributes and will also be stripped of any roles that they may currently possess that are listed in this setting but were not defined in the assertion attributes system.

• Roles to be Monitored – define the list of system roles you wish to monitor during each SSO authentication by a user.
• Mapping – map all roles indicated above to the external role name from the client Identity Provider service.

Detailed expected behavior of these settings can be found in Section 4.

Example of Attribute Values in Roles

Example 1 - Attribute format from ADFS

<Attribute Name="Roles">
<AttributeValue>Role 1</AttributeValue>
<AttributeValue>Role 2</AttributeValue>
</Attribute>

Example 2 - Attribute format from Azure

<Attribute Name="Roles">
<AttributeValue>Role 1,Role 2</AttributeValue>
</Attribute>

Multi-Environment Support

When multiple environments with distinct SSO configurations exist (such as production, testing, development, and backup), group them under the same MES group identifier. This will provide a consistent configuration of your login page across multiple environments. The system will then detect and render the appropriate SSO login link using the MES Environment Identifier.

• MES Group Identifier – assign the same MES Group Identifier name to the SSO configuration for your development, production, testing, and backup environments.
• MES Environment Identifier – enter the domain of the SmartSimple environment that will display this SSO service endpoint on the login page, e.g., alias.smartsimple.com or alias.smartsimplebk.com.

Additional settings to be configured can be found on the main login page (Waffle → Global Settings → Branding → Login Pages) under the Single Sign-On section. Select the MES Group Identifier from the dropdown list and add a button label, e.g., Employee Login.

X.509 Certificate on the SP-Initiated SSO

In the July 2023 upgrade, a new feature to support X.509 signing certificates for single sign-on (SSO) authorization requests has been introduced. If you are utilizing a service provider-initiated SSO, a signed authentication request embedded with the signed value and the X.509 certificate will be sent to the identity provider (IdP). The new setting can be found at Global Settings > Integrations tab > Single Sign-on > Edit a SP-initiated SSO and toggle on "Sign authentication request sent to identity provider (IdP)."

Identity Provider Configuration - Client-Side System

The elements required for the setup of the client-side identity provider connection are listed below.

• Unique user identifier - within the SAML assertion, this value can be sent in the standard element: "NameID."
• Assertion Consumer Service URL - this will be equal to '/SAML2/' appended to your SmartSimple instance URL, e.g., https://alias.smartsimple.com/SAML2/.
• Service Provider's Entity ID - this can be the URL to your SmartSimple system, e.g., https://alias.smartsimple.com/.
• Service Provider metadata XML - the following is an example of service provider metadata that can be utilized; however, you must first replace every instance of 'alias.smartsimple.com' with the URL to your SmartSimple system.

<?xml version="1.0"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="https://alias.smartsimple.com/">
   <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
      <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
      <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://alias.smartsimple.com/SAML2/" index="1"/>
   </md:SPSSODescriptor>
   <md:ContactPerson contactType="technical">
      <md:GivenName>SmartSimple Support</md:GivenName>
      <md:EmailAddress>support@smartsimple.com</md:EmailAddress>
   </md:ContactPerson>
   <md:ContactPerson contactType="support">
      <md:GivenName>SmartSimple Support</md:GivenName>
      <md:EmailAddress>support@smartsimple.com</md:EmailAddress>
   </md:ContactPerson>
</md:EntityDescriptor>

The following steps provide a high-level approximation and example of how one may establish minimal SSO functionality. Additional steps may be required for your Identity Provider. These may constitute recommended best practices, and it is advisable to consult the documentation provided by your Identity Provider.

Active Directory Federation Services (ADFS)

If utilizing ADFS, please refer to the steps below as they pertain to SmartSimple for setup. Some steps unrelated to your SmartSimple configuration have been omitted.

• Add a new "Relying Party Trust."
• "Select Data Source" - Import the Service Provider metadata XML file obtained from SmartSimple.
• "Display Name" - Provide the trust with a display name, e.g., 'SmartSimple.'
• Complete the setup, then return to the "Claim Rules" editor, select the "Issuance Transform Rules" tab, and add a new rule. Set the "Rule Type" to utilize the 'Send LDAP Attributes as Claims' template and configure the mapping to the agreed-upon user identifier (e.g., LDAP attribute 'E-Mail-Addresses' to Outgoing Claim Type 'NameID'). Depending on your ADFS version and configuration, you may instead need to create two rules: one to map the attributes E-mail to E-mail, and a second rule to transform the E-mail to the outgoing NameID.
• To test or utilize this connection, use your internal ADFS URL and specify the loginToRp parameter as the SmartSimple SAML entity ID, e.g., https://adfs.yourlocaldomain.com/adfs/ls/idpinitiatedsignon.aspx?loginToRp=https://alias.smartsimple.com/.
  If you are not automatically redirected into SmartSimple, you may need to enable RelayState in ADFS and then use a RelayState parameter to achieve this, e.g., https://adfs.yourlocaldomain.com/adfs/ls/idpinitiatedsignon.aspx?RelayState=https://alias.smartsimple.com/.

Azure Identity Provider

The configuration items listed are specific for SSO to function within SmartSimple:

• Log into Azure as an administrator.
• Navigate to Azure Active Directory → Enterprise Application → Create a new application.
• Select Non-Gallery Application and then add your new application, entering the name of your application, i.e., "SmartSimple SSO," and then press ADD.
• Select Single Sign-On and then select SAML.

Basic SAML Configuration:

Identifier (Entity ID): https://alias.smartsimple.com 

Reply URL (Assertion Consumer Service URL): https://alias.smartsimple.com/SAML2/

• User Attributes & Claims

1. Required claim

Unique User Identifier (Name ID): This can be the user.mail, user.employeeid, or any unique identifier in the user profile fields.

2. Additional claims - additional attributes are necessary when a user will be created on the fly

First Name: user.givenname

Last Name: user.lastname

Email: user.mail

Department: user.department

Roles: user.assignedroles

SSOModule: constant value that will be utilized in the SmartSimple configuration "SSO Alias."

Please note that all attribute names are case sensitive and should be designated as indicated above. First Name, Last Name, and Email are mandatory for creating a new user.

• To test, navigate to Single sign-on, click on Test this application from the tab header. Select "Sign in as current user" and click on the Test sign in button. Please ensure that the current user exists in the SmartSimple instance for a successful SSO login.

Upon completion of the configuration, please provide the following to SmartSimple:

1. X.509 certificate - download the Federation Metadata XML (found under Single Sign-on → SAML Certificates)
2. Value used for the NameID - this will serve as the identifier between the SP and IdP.
3. URL Redirect
   • "User Access URL" for IdP-initiated SSO (found under "Properties").
   • "Login URL" for SP-initiated SSO (found under Single Sign-on → Set up 'Application Name').

OKTA

• Log in to the OKTA administrator account.
• Navigate to the Application tab and select Applications.
• Click on the Add Application button and select Create New App to establish a new application for SmartSimple.
• Designate the Platform as Web, set the Sign on method to SAML 2.0, and proceed to create the new application.
• On the General Settings page, assign a name to the application, such as SmartSimple SSO.
• In the Configure SAML tab, under SAML Settings,
  • Single sign-on URL: https://alias.smartsimple.com/SAML2/
    • Ensure the checkbox is selected: Use this for 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 RelayState:
  • Name ID format: EmailAddress
  • Application username: Email

The following Configuration Settings have default values:

• Update application username on: Create and update
• Response: Signed
• Assertion Signature: Signed
• Signature Algorithm: RSA-SHA256
• Digest Algorithm: SHA256
• Assertion Encryption: Unencrypted
• Attribute Statements
• First name: user.firstName
• Last name: user.lastName
• Email: user.email
• Department
• Roles
• SSOModule

Please note that all attribute names are case sensitive and must be designated as specified above. The First name, Last name, and Email fields are required for the creation of a new user.

Upon completion of the configuration in OKTA, please provide the following information to SmartSimple:

1. x509 certificate - located under the Sign On tab, SAML Setup "View SAML setup instructions"
2. Value used for the NameID - this will serve as the identifier between SP and IdP
3. URL Redirect - "Embed Link" for IdP-initiated SSO (found under the "General" tab in the "App Embed Link" section)

SAML Assertion Example

The following is an example of a SAML Assertion :

<?xmlversion="1.0" encoding="UTF-8"?>
<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" Destination="https://alias.smartsimple.com/SAML2/" IssueInstant="2014-07-12T14:17:03.063Z" ID="BYavZkuNtRHC5rEPhIAEQrys1Wb" Version="2.0">

   <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">sso:saml2:alias:stage:SmartSimple:idp</saml:Issuer>

   <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
      <ds:SignedInfo>
         <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
         <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
         <ds:Reference URI="#BYavZkuNtRHC5rEPhIAEQrys1Wb">
            <ds:Transforms>
               <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
               <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
            </ds:Transforms>
            <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
            <ds:DigestValue>+2uvXQh+d65mNWs0G6FBf4igIxU=</ds:DigestValue>
         </ds:Reference>
      </ds:SignedInfo>
      <ds:SignatureValue>LEOCPec/eNBMqBV7A99...</ds:SignatureValue>
   </ds:Signature>

   <samlp:Status>
      <samlp:StatusCodeValue="urn:oasis:names:tc:SAML:2.0:status:Success"/>
   </samlp:Status>

   <saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Version="2.0" IssueInstant="2014-07-12T14:17:03.246Z" ID="X14MvZtPaqyUjfFCbehto32uDTG">
      <saml:Issuer>sso:saml2:alias:stage:SmartSimple:idp</saml:Issuer>
      <saml:Subject>
         <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">T5014CD</saml:NameID>
         <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
            <saml:SubjectConfirmationData NotOnOrAfter="2014-07-12T14:22:03.246Z" Recipient="https://alias.smartsimple.com/SAML2/"/>
         </saml:SubjectConfirmation>
      </saml:Subject>
      <saml:Conditions NotOnOrAfter="2014-07-12T14:22:03.246Z" NotBefore="2014-07-12T14:12:03.246Z">
         <saml:AudienceRestriction>
           <saml:Audience>sso:saml2:alias:stage:SmartSimple:sp</saml:Audience>
         </saml:AudienceRestriction>
      </saml:Conditions>
      <saml:AuthnStatement AuthnInstant="2014-07-12T14:17:03.246Z" SessionIndex="X14MvZtPaqyUjfFCbehto32uDTG">
         <saml:AuthnContext>
           <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified</saml:AuthnContextClassRef>
         </saml:AuthnContext>
      </saml:AuthnStatement>
      <saml:AttributeStatement xmlns:xs="http://www.w3.org/2001/XMLSchema">
         <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="Email">
            <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">david@email.com</saml:AttributeValue>
         </saml:Attribute>
         <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="First name">
            <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">David</saml:AttributeValue>
         </saml:Attribute>
         <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="Last name">
            <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Smith</saml:AttributeValue>
         </saml:Attribute>
         <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="Department">
            <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Shipping</saml:AttributeValue>
         </saml:Attribute>
         <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="Roles">
            <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Clerk</saml:AttributeValue>
         </saml:Attribute>
      </saml:AttributeStatement>
   </saml:Assertion>

</samlp:Response>

SAML Authorization Request Example

Example below is sent by the Service Provider (SmartSimple) to the Identity Provider in the SP-SSO initiated flow.

 <?xml version="1.0" encoding="UTF-8"?>
 <samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" AssertionConsumerServiceURL="https://alias.smartsimpleqa.com/SAML2/" Destination="https://adfs.yourlocaldomain.com/adfs/ls/spinitiatedsignon" ID="alias.smartsimple.com_QADEV_6CD95AEAD41525F565318B82A46B022E" IssueInstant="2023-01-05T13:56:36Z" ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" ProviderName="aliasname" Version="2.0">
	<saml:Issuer>https://alias.smartsimple.com</saml:Issuer>
	<samlp:NameIDPolicy AllowCreate="true" Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"/>
	<samlp:RequestedAuthnContext Comparison="exact">
		<saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml:AuthnContextClassRef>
	</samlp:RequestedAuthnContext>
</samlp:AuthnRequest>

Adding URL Redirect on the Login Page

From the Login Page, the SSO URL redirect can be configured to direct internal users to the client's Identity Provider login page.

To configure, please proceed to:

1. Waffle → Global Settings → Branding → Login Pages

2. In the Login Pages list view, select the default login page to which the SSO URL redirect will be added.

3. Navigate to the Single Sign-On section, select the MES Group Identifier, and add the Link Label, e.g., Employee Login.

4. Click Save.

Variables to utilize in a custom page layout:

• @ssodisplaylink@ - the variable used to add the Link Label and hyperlink in the login template.
• @ssotargetlink@ - the variable utilized to retrieve the SSO login URL.

Troubleshooting

To obtain information regarding the reasons for SSO failure, first enable the "Debug Mode" option within the SSO configuration in SmartSimple, and subsequently test the SSO to generate log data within the Configuration Error Log.

• SAML failed. No user account found.

This indicates that a corresponding active user was not located in the SmartSimple instance. Please verify the [Unique Identifier Field] configured in the SSO settings and compare the value of the "NameID" node sent within the SAML assertion to determine if a user with that field value exists in SmartSimple. Ensure that the user is activated and permitted to log in.

• SAML failed. Login session is null / Invalid SAML Response.

Confirm that a matching user account exists.

Inspect the x509 certificate.

Verify that the endpoint in the SSO assertion is accurate. There should be a Response node with a parameter such as Destination="https://alias.smartsimple.com/SAML2/."

• SAML signature validation failed.

This indicates that the x509 certificate does not match between the SAML Assertion and the value configured in the instance's SSO settings.

• SAML response expired.

Examine the datetime values of the parameters named NotAfter and NotBefore within the SAML Assertion and compare these with the expected datetime when the assertion was sent. It is possible to adjust the Timestamp Time Zone dropdown settings.

• Invalid response format. Unparseable date.

Ensure that the SAML Assertion contains both parameters: NotAfter and NotBefore.

• SAML processing error.

Verify that the value for the SSO Alias is "SAML2" for SSO in the production instance.

If it pertains to a Multi Environment, the value in the SSO Alias should correspond to the attribute SSOModule.

• No log file found in SmartSimple.

Verify the parameter: Destination="https://alias.smartsimple.com/SAML2/" from the SSO Assertion.

Ensure that the value for the SSO Alias is "SAML2" for SSO in the production instance.

If it relates to a Multi Environment, the value in the SSO Alias should correspond to the attribute SSOModule.

• After logging in through SSO, you are redirected to "mesagetype=30."

Confirm that the alias of the instance is correct. To verify the alias, navigate to Waffle → Global Settings → Branding → Web Alias. Ensure that the Web Alias value matches the domain alias.

• SAML InResponseTo does not match any of the possible Request IDs.

Confirm that the alias of the instance is correct.

Verify that the SSO configuration for multiple environments does not contain duplicate MES Environment Identifiers.

Expected Behavior for Role Mapping

  Role Mapping set to Disabled / Create New User on No Match is OFF.

• A user will not be created if the user does not exist in the SmartSimple instance.
• Only existing users in the SmartSimple instance will be able to log in, and there will be no role/status updates for existing users.

Role Mapping set to Disabled / Create New User on No Match is ON.

• Define User Roles Through Custom Attribute is OFF. A user will be created with default new user role / default new user status settings if the user does not exist in the SmartSimple instance.
• Define User Roles Through Custom Attribute is ON. A user will be created with the roles listed in the SSO assertion 'Roles' if the user does not exist in the SmartSimple instance (role names should align with system role names in the instance).
• No role/status updates for existing users.

Role Mapping set to Enabled / Create New User on No Match is OFF.

• Create New User on No Match is OFF. A user should not be created in the system if not already created when using SSO to access the system.
• Create New User on No Match is ON. A user will be created with default new user role / default new user status settings if the user does not exist in the SmartSimple instance.
• For existing users: no change for existing roles that are NOT within the list of "Roles to be Monitored".
• For existing users: roles that are in the list of "Roles to be Monitored" will be updated based on Role Mapping. The user will be provisioned with all roles as defined by the assertion attributes and will lose any roles that they may currently possess that are listed in this setting but were not defined in the assertion attributes.

Example of SSO Configuration in SmartSimple

Configuration for SSO in Production Instance

SmartSimple SSO Configuration as the Service Provider in the client's SmartSimple production instance.

A. SSO Configuration

1. Navigate to Global Settings → Integrations tab → Single Sign-On section.

2. Click on the “+” icon to create a new SSO configuration in the instance.

3. Complete the mandatory fields:

SSO Alias: SAML2 (default alias for production instance).

Signing Certificate (X.509): Paste the x509 certificate after configuring the client's Identity Provider.

Timestamp Time Zone: --UTC/GMT-- (default from the dropdown).

MES Group Identifier: SSOProd (open text field).

MES Environment Identifier: alias.smartsimple.com (client's URL for the production instance).

Method: Identity Provider-initiated (default setting).

Identity Provider Service Endpoint: This is the URL for the login redirect.

For Azure, the value in User Access URL (found under Properties).

For OKTA, the value in Embed Link (found under General tab in the App Embed Link section).

For ADFS, the redirect is https://adfs.yourlocaldomain.com/adfs/ls/idpinitiatedsignon.aspx?loginToRp=https://alias.smartsimple.com/.

Unique Identifier Field (UID): From the dropdown, select *E-Mail (default value, but it can also be the Employee ID or any unique identifier in the user profile).

Bypass Multi-Factor Authentication (MFA): enabled.

4. Click Save.

B. Login Page Configuration

1. Navigate to Global Settings → Branding tab → Login Pages section.

2. From the Primary tab, click on the pencil icon for the first item in the list view - the default Login Page.

3. From the General tab, navigate to the Single Sign-On section and complete the fields:

MES Group Identifier: From the dropdown, select SSOProd.

Link Label: Employee Login (open text field).

4. Click Save. Upon logout, the SSO button will be visible below the username/password fields.

Configuration for Multi-Environment Single Sign-On (SSO)

In the event that a client operates four environments (Production, Backup, Development, Testing), the aforementioned settings will be established for each individual environment.

It is important to note that these settings must be replicated across different instances to ensure that when a Transition to Production (T2P) occurs, all settings are present and transferred, thereby eliminating the need for any modifications post-T2P.

Notes:

1. All columns listed above are open text fields and can be renamed as necessary. The alias name for Item 1 is the only default/mandatory value for the production environment.

2. For Items 2 through 4, the attribute name "SSOModule" along with the associated SSO Alias value must be included in the Identity Provider configuration. It is essential to note that the SSO Alias is case sensitive and must be labeled precisely.

3. From the Login Page, the MES Group Identifier will correspond to the value "SSOID1". This will redirect to the appropriate Redirect URL Endpoint as it will recognize the specific instance the user is attempting to access via SSO.

Configuration for Two Identity Providers within the Production Instance

The example configuration provided below pertains to a scenario where a client has two existing Identity Provider Services.

All SSO configurations listed below are applicable to the client's production instance:

Notes:

1. Item 1 corresponds to the client's first Identity Provider Service.

2. Item 2 represents the second configuration for the client's second Identity Provider Service. The attribute name "SSOModule" along with the associated SSO Alias value must be included in the Identity Provider configuration. Please note that the SSO Alias is case sensitive and must be labeled precisely.