This article defines all settings available in the Single Sign-On (SSO) via SAML 2.0 configuration in SmartSimple.
IN THIS ARTICLE
Mandatory Settings
The following settings are required when creating a new SSO configuration in SmartSimple.
| Setting | Description |
|---|---|
| SSO Alias | Identifies the SSO connection. Set to SAML2 by default for the production instance. If multiple SSO connections are configured, include an additional element named SSOModule in the client-side assertion to specify the connection by matching the unique SSO Alias value. |
| Unique Identifier Field (UID) | Identifies the user account. Must be an attribute that is unique to each user in SmartSimple. The value of the NameID attribute in the SSO assertion must match the field selected in this drop-down menu, typically an email address or employee ID. |
| SSO Protocol | Determines if the protocol is SAML 2.0 or OpenID Connect (OIDC). |
| Identity Provider (IdP) X.509 Certificate (SAML 2.0 only) | The signing certificate provided by the client. Enter the certificate value without the begin certificate and end certificate header and footer lines. Depending on how the client-side system transmits this value in the SAML assertion, it may be formatted as a single line or multiple lines. Enter the value 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--. Adjust this setting if the error SAML response expired appears in the log file during debug mode. |
| Third-Party Identity Provider | Specifies the SSO authentication method: Identity Provider-initiated or Service Provider-initiated. |
| Endpoint | The redirect URL for the selected authentication method. This redirect renders on the Login Page. The exact caption depends on the selected Third-Party Identity Provider. |
Additional Settings
The following settings are optional and control session behavior, logging, and logout behavior.
| Setting | Description |
|---|---|
| Enable Debug Mode | When enabled, disregards the SSO timestamp and outputs the SSO assertion message in the Configuration Error Log. Use this setting to troubleshoot SSO failures. |
| Enable Social Login (Google, Microsoft, Apple) | Allows users to sign in using their existing Google, Microsoft, or Apple accounts via secure Single Sign-On (SSO). This simplifies login and enhances security by leveraging trusted identity providers. |
| Encrypt Assertion | When toggled on, the assertion will be encrypted. Subsequent options depend on the selected Identity Provider Method. |
| Bypass Two Factor Authentication | Bypasses two-factor authentication for users who log in via SSO. |
| Default Landing Page | Specifies an initial landing page within the SmartSimple instance. Enter a relative path (for example: /iface/ex/ax_index.jsp). |
| Logout Redirect URL | The URL to which SSO users are redirected when they log out. |
| Enable Logout Assertion | Sends a logout assertion to the Identity Provider to terminate that session. |
| Assertion Target URL | The target site URL. Visible only when Enable Logout Assertion is on. |
| Assertion Private Key | The private key used to establish a connection with the target site. Visible only when Enable Logout Assertion is on. |
| Attach Policies | Allows users to select Privacy and Security Policies. The user will be required to accept or acknowledge any attached policies when using SSO. |
| Encryption Certificate | Required for both Identity Provider (IdP) initiated and Service Provider (SP) initiated. |
| Provider Name | Required when Service Provider (SP) initiated is selected. |
| NameID Policy Format | Required when Service Provider (SP) initiated is selected. This field specifies the format of the returned NameID. |
| Authentication Context | Required when Service Provider (SP) initiated is selected. This field specifies the authentication context. |
| Sign authentication request sent to IdP | Required when Service Provider (SP) initiated is selected. Toggle on to send a signed authentication request (RSA-SHA256) embedded within the signed value and SP Signing Certificate. |
User Creation Options (JIT Provisioning)
The following settings control whether new users are created automatically following successful SSO authentication. This is known as just-in-time (JIT) provisioning.
| Setting | Description |
|---|---|
| Create New User on No Match | When enabled, creates a new user if no matching account is found and permits login for the new user upon successful authentication. |
| Define User Roles Through Custom Attribute | When enabled, uses the Roles attribute in the SSO assertion to assign system roles to the user. |
| Default User Role When No Matching Role Found | The role assigned to newly created users when the Roles attribute in the assertion is empty, absent, or does not match an existing role in SmartSimple. Required when creating users through SSO. This is a required field. |
| Default New User Status | The status assigned to newly created users. |
| Create New Organization When No Match Found | When enabled, creates a new parent organization if no matching organization exists in SmartSimple. |
| Default Organization | The parent organization assigned to newly created users. Required when creating users through SSO. This is a required field. |
| Default New Organization Status | The status assigned to newly created organizations. |
Optional attributes can be included in the assertion to populate standard fields (First Name, Last Name, Email) for newly created users. If the selected Unique Identifier Field is not the standard email address, the custom field selected is also populated during JIT provisioning.
Optional Assertion Attributes
The following optional attributes may be included in the SSO assertion. All attribute names are case sensitive and must be entered exactly as shown.
| Attribute | Description |
|---|---|
| SSOModule | Specifies the SmartSimple SSO connection when multiple connections are configured. For example, SAML2 for production, SSOBK for backup, SSODEV for development, SSOTest for test. Both the attribute name and value are case sensitive. |
| The user's email address. | |
| First Name | The user's first name. |
| Last Name | The user's last name. |
| Department | Updates the user's organization. Attempts to match an organization by name and relocates the user to that organization if found. |
| Roles | Updates the user's roles in SmartSimple for new users. Enter a comma-delimited list of SmartSimple user role names. |
| Language | Specifies the initial language displayed to the user. Enter an integer value corresponding to a language ID in SmartSimple (for example, 1 = English). |
Role Mapping Settings
Role mapping manages user roles for both new and existing users during SSO authentication. When role mapping is enabled, user roles are updated based on the role attributes provided in the assertion.
| Setting | Description |
|---|---|
| Roles to be Monitored | The list of system roles to monitor during each SSO authentication. Roles in this list may be added or removed based on the assertion attributes. Roles not in this list are not affected. |
| Mapping | Maps each monitored role to its corresponding external role name from the client Identity Provider service. |
Expected Role Mapping Behavior
The table below describes user and role behavior based on the combination of Role Mapping and Create New User on No Match settings.
| Role Mapping | Create New User on No Match | Define Roles Through Custom Attribute | Behavior |
|---|---|---|---|
| Disabled | Off | N/A | Only existing users can log in. No users are created. No role or status updates for existing users. |
| Disabled | On | Off | New users are created with the default user role and default user status. No role or status updates for existing users. |
| Disabled | On | On | New users are created with the roles listed in the assertion Roles attribute. Role names must match system role names. No role or status updates for existing users. |
| Enabled | Off | N/A | Existing users: roles within the Roles to be Monitored list are updated based on role mapping. Roles not in the list are unchanged. New users are not created. |
| Enabled | On | N/A | New users are created with the default user role and status. Existing users: roles within the Roles to be Monitored list are updated. Roles not in the list are unchanged. |
Multi-Environment Support Settings
When multiple SmartSimple environments use distinct SSO configurations (such as production, backup, development, and testing), group them under the same MES Group Identifier to provide a consistent login page experience across environments.
| Setting | Description |
|---|---|
| MES Group Identifier | Assign the same MES Group Identifier to the SSO configuration for each environment (development, production, testing, backup). The system uses this to group configurations and render the correct SSO login link. |
| MES Environment Identifier | Enter the domain of the SmartSimple environment that displays this SSO service endpoint on the login page. For example, alias.smartsimple.com or alias.smartsimplebk.com. |
NOTE Configure the MES Group Identifier and a button label (for example, Employee Login) on the Login Pages settings page. Click the Menu icon, select Global Settings, click the Branding tab, and click Login Pages. Select the MES Group Identifier from the drop-down menu in the Single Sign-On section.
Configuration Examples
Production Instance Example
The following table shows a sample SSO configuration for a production instance.
| Field | Example Value |
|---|---|
| SSO Alias | SAML2 (default for production) |
| Unique Identifier Field | |
| Timestamp Time Zone | --UTC/GMT-- (default) |
| MES Group Identifier | SSOProd |
| MES Environment Identifier | alias.smartsimple.com |
| Method | Identity Provider-initiated (default) |
Multi-Environment Configuration
When a client operates multiple environments, replicate SSO settings across all instances so that a Transition to Production (T2P) does not require post-migration changes. The SSO Alias for the production instance is the only mandatory/default value.
| # | SSO Alias | Description | MES Group Identifier | MES Environment Identifier |
|---|---|---|---|---|
| 1 | SAML2 | Production instance | SSOID1 | alias.smartsimple.com |
| 2 | BKSSO | Backup instance | SSOID1 | alias.smartsimplebk.com |
| 3 | DevSSO | Development instance | SSOID1 | aliasdev.smartsimple.com |
| 4 | TestSSO | Testing instance | SSOID1 | aliastest.smartsimple.com |
NOTE For configurations 2 through 4, the SSOModule attribute and its corresponding SSO Alias value must be included in the Identity Provider configuration. The SSO Alias value is case sensitive.
Two Identity Providers within a Single Production Instance
The following table shows a configuration for a client with two Identity Provider services, both for the production instance.
| # | SSO Alias | Description | MES Group Identifier | MES Environment Identifier |
|---|---|---|---|---|
| 1 | SAML2 | Identity Provider Service 1 | SSOID1 | alias.smartsimple.com |
| 2 | SSOProd2 | Identity Provider Service 2 | SSOID2 | alias.smartsimple.com |
NOTE For configuration 2, the SSOModule attribute and its corresponding SSO Alias value must be included in the Identity Provider configuration. The SSO Alias value is case sensitive.
SAML Examples
SAML Assertion Example
The following is an example of a SAML assertion sent by the Identity Provider to SmartSimple.
<?xml version="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>
...
<saml:AttributeStatement>
<saml:Attribute Name="Email">
<saml:AttributeValue>david@email.com</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="First Name">
<saml:AttributeValue>David</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="Last Name">
<saml:AttributeValue>Smith</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="Roles">
<saml:AttributeValue>Clerk</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
</samlp:Response>Role Attribute Formats
Different Identity Providers format the Roles attribute differently. Both formats are supported.
ADFS format: Multiple AttributeValue elements, one per role.
<Attribute Name="Roles"> <AttributeValue>Role 1</AttributeValue> <AttributeValue>Role 2</AttributeValue> </Attribute>
Azure format: Comma-delimited list in a single AttributeValue element.
<Attribute Name="Roles"> <AttributeValue>Role 1,Role 2</AttributeValue> </Attribute>
SAML Authorization Request Example (SP-Initiated)
The following is an example of the SAML authorization request sent by SmartSimple (Service Provider) to the Identity Provider in an SP-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"
IssueInstant="2023-01-05T13:56:36Z"
ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" 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:AuthnRequest>