Difference between revisions of "Single Sign-On"

From SmartWiki
Jump to: navigation, search
m
(→‎User Creation Option (JIT Provisioning))
 
(141 intermediate revisions by 4 users not shown)
Line 1: Line 1:
−
==General Information==
+
==Overview==
−
SmartSimple offers one method of implementing Single Sign-On (SSO) integration:
+
SmartSimple provides Single Sign-On (SSO) integration through [[Single_Sign-On#SAML_2.0|SAML 2.0]]. It should be noted that SSO is just a subset of federated identity management, as it relates only to authentication, and not account management or synchronization with SmartSimple.
−
* [[Single_Sign-On#SAML_2.0|SAML 2.0]]
 
−
* Deprecated: [[Single_Sign-On#Cipher_encrypted_reference|Cipher encrypted reference]]
 
  
−
This page provides technical details of each solution.
+
Implementation of SSO requires configuration both within SmartSimple and within the system that will provide the authentication.
  
−
Implementation of Single Sign On using either method requires configuration by both SmartSimple and the administrator of the system that will provide the authentication. SmartSimple's implementation of Single Sign On acts as the service provider and assumes the client has the infrastructure and resources to host, configure, and manage the identity provider service. Please contact your account manager or [[How the SmartSimple Support Desk Works|SmartSimple Support]] for further information.
+
SmartSimple's implementation of SSO acts as the '''Service Provider''' and assumes the client has the infrastructure and resources to host, configure, and manage the '''Identity Provider''' service. Please contact your account manager or [[How the SmartSimple Support Desk Works|SmartSimple Support]] for further information.
  
 
==SAML 2.0==
 
==SAML 2.0==
 +
SmartSimple supports SAML ('''Security Assertion Markup Language''') 2.0 as the Service Provider through our own proprietary implementation of this standard.
  
−
SmartSimple supports SAML ('''Security Assertion Markup Language''') 2.0 at the recipient end of an authenticated login. For example, the user will log into the client side system/infrastructure and then SSO into SmartSimple, not vice versa.
+
Identity Provider-initiated authentication is supported, meaning the end user will first authenticate on the client-side system/infrastructure and then be forwarded to SmartSimple. The client Identity Provider service will construct a base64-encoded SAML assertion and send this to the user's browser. The user's browser will then relay this assertion to the SmartSimple server for SSO authentication.
  
−
The client system will construct a base64-encoded SAML response object and send this to the user’s browser. The user’s browser will then be forwarded to the SmartSimple server.
+
After the November 2022 upgrade, Service Provider-initiated authentication is now supported. The Service Provider sends the SAML Authorization Request message and forwarding the user to the client Identity Provider service for authentication. The end user will login from the client-side Identity Provider. After the end user has been 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===
 
===Prerequisites===
 +
* You must provision your own Identity Provider service, third-party or otherwise, for use with this feature. Enabling and maintaining the Identity Provider is your responsibility.
 +
* You must provide SmartSimple with a public key in base64-encoded X.509 Certificate format for digital signature validation.
 +
 +
===Service Provider Configuration - SmartSimple===
 +
Within SmartSimple, SSO settings are accessed through the '''''Global Settings''''' →''''' Integration''' ''tab.
 +
 +
[[File:sso-001.png|thumb|none|600px|Navigating to the SSO configuration.]]
 +
 +
 +
You will be redirected to the List View of the SSO configuration page. Click on the “+” icon to create a new SSO configuration on the instance:
 +
 +
 +
[[File:sso-002.png|thumb|none|800px|SSO configuration settings.]]
 +
 +
====Mandatory Settings====
 +
* '''SSO Alias''' - used to identify the SSO connection and should be configured by default to be 'SAML2'. If multiple SSO connections are to be configured then 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)''' - used to identify the user account and needs to be an attribute that is unique to each user in SmartSimple. The value for the attribute "NameID" from the SSO assertion should match the value from the field selected in the dropdown list.(typically e-mail address or employee ID).
 +
* '''X509Certificate (SAML2 Only)''' - the signing certificate to be provided by the client. The formatting of this should be the certificate value without the "begin certificate" and "end certificate" header and footer lines. Also, depending on how the client-side system sends this value within the SAML assertion the certificate value will typically be formatted to just a single line but could also be multiple lines and so must be entered into SmartSimple in the same format.
 +
* '''Timestamp Time Zone''' - used to read the incoming SSO message timestamp from Identity Provider configured time zone.  Default value is "--UTC/GMT--". Settings will need to be adjusted when the error "SAML response expired" is found in the log file during debug mode.
 +
<!--Ticket#Ticket#111554 - Single Sign On - timestamp challenge-->
 +
* '''Third-Party Identity Provider'''- specify what SSO authentication method is used  (Identity-Provider initiated  or  Service Provider-initiated)
 +
** '''Endpoint''' - specify the redirect IdP-initiated or SP-Initiated endpoint.  This redirect will be rendered in the [[Login Page]].
 +
* It is also recommended to disable the Session Timeout Alert setting within the '''''Global Settings''''' → '''''Security''' ''section as that feature would not be applicable to users logged in through single sign-on.
 +
* By default, SSO acts as an additional method of authentication. If you wish to enforce the use of SSO, and restrict the regular username and password authentication, you can do so with the '''''Global Settings''''' → '''''Integration''''' → '''''Enforce SSO''''' setting which allows you to restrict a set of user roles to only be able to login through SSO.
 +
 +
====Additional Settings====
 +
 +
* '''Bypass Two Factor Authentication''' - [[Multi-Factor Authentication|Bypass Two Factor Authentication]] when logged in with SSO
 +
* '''Enable Debug Mode''' - When enabled, it ignores the SSO time stamp and output SSO assertion message in the [[Configuration_Error_Log|Congifuration Error Log]]
 +
 +
* '''Default Landing Page''' - used to specify an initial landing page within SmartSimple instance. This should be a relative path (e.g. /iface/ex/ax_index.jsp).
 +
 +
<!--Ticket#52854 - SSO logout assertion SLO-->
 +
* '''Logout Redirect URL''' - redirect url when SSO users logout
 +
* '''Enable Logout Assertion''' - will send a logout assertion to the Identity Provider to log out of that session
 +
 +
: Additional settings for ''Enable Logout Assertion'':
 +
: '''Assertion Target URL''' - target site url
 +
: '''Assertion Private Key''' - private key to establish connection with the target site.
 +
=====User Creation Option (JIT Provisioning)=====
 +
When users need to be created on the fly after SSO authentication, the following configuration settings are available:
 +
 +
* '''Create New User on No Match'''– when enabled, it will create new user when no matching is found and will allow login for new user upon successful authentication
 +
* '''Define User Roles Through Custom Attribute'''– when enabled, it will use the SSO assertion “Roles” attribute to define users’ system roles.
 +
* '''Default User Role When No Matching Role Found <span style="color: #ff0000;">*</span>'''– selected role from this dropdown will be assigned to new created users only if “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’s status for new users only
 +
* '''Create New Organization When No Match Found '''– when enabled, it will create a new parent organization when no matching organization exists your SmartSimple instance.
 +
* '''Default Organization <span style="color: #ff0000;">*</span>'''– assigned user’s parent organization for new users
 +
* '''Default New Organization Status'''– assigned parent organization’s status for new organizations
 +
 +
'''<span style="color: #ff0000;">* <span style="color: #000000;">- mandatory fields when creating users thru SSO.</span></span>'''
 +
 +
 +
In addition, optional attributes can be added in the assertion to create the user and these 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 in the JIT provisioning.
 +
 +
 +
[[File:SSO_UserCreation.png|thumb|none|500px|SSO User Creation Settings.]]
 +
 +
=====Optional Attibutes=====
 +
The following optional attributes can be used in the assertion. Please note that they are case sensitive and should be labelled exactly.
 +
 +
* '''SSOModule''' - used to specify the SmartSimple SSO connection when there are multiple connections configured. i.e. "SAML2" for prod, "SSOBK" for backup instance, "SSODEV" for dev instance, "SSOTest" for test instance. Note that the attribute name and attribute value are case sensitive 
 +
* '''Email'''
 +
* '''First name'''
 +
* '''Last name'''
 +
* '''Department''' - used to update the user's organization. This will attempt to match an organization by name and will move the user to that organization if found.
 +
* '''Roles''' - used 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''' - used 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=====
 +
<!--Ticket#124791 - SSO to update roles for existing users for a fully federated SSO-->
 +
Apply Role Mapping to new and existing users to control user roles within your SmartSimple system. Define the list of system roles you wish to be monitored upon 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 upon the role mapping below, the user will be provisioned with all the 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 be monitored upon 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 behaviour of this settings can be found in Section 4
 +
 +
=====Multi Environment Support=====
 +
<!--Ticket# 134892 - Service Provider initiated Single Sign On (SP-initiated SSO)-->
 +
When you have multiple environments with unique SSO configurations (such as production, testing, development and backup), group them under the same MES group identifier. This will give you 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 tis SSO service endpoint on the login page i.e. alias.smartsimple.com or  alias.smartsimplebk.com
 +
 +
Additional settings to be configured is from 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 button label i.e. ''Employee Login''.
 +
 +
====X.509 Certificate on the SP-Initiated SSO====
 +
<!-- 148020 - Adding SP x509 signing certificate for SSO metadata and SSO authorization request -->
 +
In the July 2023 upgrade, a new feature to support X.509 signing certificate for single sign-on (SSO) authorization requests has been added.
 +
If you are using 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 is located 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 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 service provider metadata that can be used, however you must first replace every instance of 'alias.smartsimple.com' instead with the URL to your SmartSimple system.
 +
 +
<pre>
 +
<?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>
 +
</pre>
 +
 +
The following steps are a high-level approximation and example of how one may setup minimal SSO functionality.
 +
Additional steps may be needed for your Identity Provider.
 +
These do may constitute recommended best practices, and we recommend you consult the documentation offered by your Identity Provider.
 +
 +
====Active Directory Federation Services (ADFS)====
 +
If using ADFS refer to the below steps as related 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" - Give the trust a display name, e.g. 'SmartSimple'.
 +
* Finish the setup, and then return to the "Claim Rules" editor, and select the "Issuance Transform Rules" tab and add a new rule. Set the "Rule Type" to use 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 setup you may instead need to create two rules, one to map the attributes E-mail to E-mail, and then a second rule to transform the E-mail to the outgoing NameID.
 +
* To test or use 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/'''.<br/> If you aren't automatically redirected into SmartSimple you may need to have RelayState enabled in ADFS, and then use a RelayState parameter to achieve this, e.g. '''https://adfs.yourlocaldomain.com/adfs/ls/idpinitiatedsignon.aspx?RelayState=RPID%3Dhttps%3A%2F%2Falias.smartsimple.com%2F%26RelayState%3Dhttps%253A%252F%252Falias.smartsimple.com%252F'''.
 +
 +
====Azure Identity Provider====
 +
Configuration items listed are specifics SSO to work in SmartSimple:
 +
 +
* Log into Azure as admin
 +
* Go to Azure Active Directory → Enterprise Application → Create a new application
 +
* Select Non-Gallery Application and then add your new application, enter 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 or user.employeeid or any unique identifier in the user profile fields
 +
: 2. Additional claims - additional attributes are needed when 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 is going to be used in the SmartSimple configuration "SSO Alias"
 +
: Note that all attribute names are case sensitive and should be named as indicated above.  First name, Last name and Email are mandatory to create a new user. 
 +
* To test, go 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 make sure that the current user is existing in the SmartSimple instance to have a successful SSO login.
 +
 +
 +
After configuration has been completed, provide the following to SmartSimple:
 +
 +
# x509 certificate - download the ''Federation Metadata XML (''Found under ''Single Sign-on''  →  ''SAML Certificates'')
 +
# Value used for the NameID - this will be used as the identifier between SP and IdP
 +
# 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 OKTA admin account
 +
* Click on the '''Application''' tab and select Applications.
 +
* Click on the '''Add Application''' button and click on''' Create New App''' to create a new application for SmartSimple.
 +
* Set the '''Platform''' as '''Web''', the '''Sign on method''' as '''SAML 2.0''' and Create a new application.
 +
* In the '''General Settings''' page, provide a name for the application i.e. SmartSimple SSO
 +
* In the '''Configure SAML''' tab, under SAML Settings, 
 +
** '''Single sign-on URL''':     https://alias.smartsimple.com/SAML2/
 +
*** check on the tick box: 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
 +
* Configuration Settings below have default value: 
 +
** '''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'''
 +
 +
Note that all attribute names are case sensitive and should be named as indicated above. First name, Last name and Email are mandatory to create a new user.
 +
 +
 +
After configuration in OKTA has been completed, provide the following to SmartSimple:
 +
 +
# x509 certificate - found under ''Sign On'' tab, SAML Set up "''View SAML set up instructions''"
 +
# Value used for the NameID - this will be used as the identifier between SP and IdP
 +
# URL Redirect - "Embed Link" for IdP-initiated SSO (Found under "''General''" tab in the "''App Embed Link''" Section)
 +
 +
===SAML Assertion Example===
 +
The following is an example of a SAML Assertion :
  
−
* You must provision your own identity provider, third-party or otherwise, for use with this feature. Enabling and maintaining the identity provider is your responsibility.
+
<div id="mw-content-text" lang="en-GB" dir="ltr" class="mw-content-ltr">
−
* You must provide SmartSimple with a public key in base64-encoded X.509 Certificate format for digital signature validation.
+
<pre>
−
===Attributes===
+
<?xmlversion="1.0" encoding="UTF-8"?>
−
The following ''Assertion'' attributes are used:
+
<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">
−
<ul><li>UID (client system’s unique user id)      </li>
 
−
<li>Email (optional)                          </li>
 
−
<li>First name (optional)                    </li>
 
−
<li>Last name (optional)                      </li>
 
−
<li>Department (optional)                    </li>
 
−
<li>Comma delimited list of roles (by name) to be assigned to the user (optional)                          </li>
 
−
<li>Language (optional)                      </li>
 
−
<li>RedirectURL (optional)                    </li></ul>
 
  
−
===SAML Response Sample XML===
+
  <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">sso:saml2:alias:stage:SmartSimple:idp</saml:Issuer>
−
The following is an example of a valid SAML Response:
 
  
−
<pre style="white-space: pre-wrap;  white-space: -moz-pre-wrap;  white-space: -pre-wrap;  white-space: -o-pre-wrap;  word-wrap: break-word;"><?xmlversion="1.0" encoding="UTF-8"?>
+
   <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
−
<samlp:Responsexmlns: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:Issuerxmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">sso:saml2:alias:stage:SmartSimple:idp</saml:Issuer>
 
−
   <ds:Signaturexmlns:ds="http://www.w3.org/2000/09/xmldsig#">
 
 
       <ds:SignedInfo>
 
       <ds:SignedInfo>
−
         <ds:CanonicalizationMethodAlgorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
+
         <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
−
         <ds:SignatureMethodAlgorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
+
         <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
−
         <ds:ReferenceURI="#BYavZkuNtRHC5rEPhIAEQrys1Wb">
+
         <ds:Reference URI="#BYavZkuNtRHC5rEPhIAEQrys1Wb">
 
             <ds:Transforms>
 
             <ds:Transforms>
−
               <ds:TransformAlgorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
+
               <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
−
               <ds:TransformAlgorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
+
               <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
 
             </ds:Transforms>
 
             </ds:Transforms>
 
             <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
 
             <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
−
          <ds:DigestValue>+2uvXQh+d65mNWs0G6FBf4igIxU=</ds:DigestValue>
+
            <ds:DigestValue>+2uvXQh+d65mNWs0G6FBf4igIxU=</ds:DigestValue>
 
         </ds:Reference>
 
         </ds:Reference>
 
       </ds:SignedInfo>
 
       </ds:SignedInfo>
−
    <ds:SignatureValue>LEOCPec/eNBMqBV7A99...</ds:SignatureValue>
+
      <ds:SignatureValue>LEOCPec/eNBMqBV7A99...</ds:SignatureValue>
 
   </ds:Signature>
 
   </ds:Signature>
 +
 
   <samlp:Status>
 
   <samlp:Status>
−
       <samlp:StatusCodeValue="urn:oasis:names:tc:SAML:2.0:status:Success" />
+
       <samlp:StatusCodeValue="urn:oasis:names:tc:SAML:2.0:status:Success"/>
 
   </samlp:Status>
 
   </samlp:Status>
−
   <saml:Assertionxmlns: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: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:Subject>
−
         <saml:NameIDFormat="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">123456</saml:NameID>
+
         <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">T5014CD</saml:NameID>
−
         <saml:SubjectConfirmationMethod="urn:oasis:names:tc:SAML:2.0:cm:bearer">
+
         <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
−
             <saml:SubjectConfirmationDataNotOnOrAfter="2014-07-12T14:22:03.246Z" Recipient="https://alias.smartsimple.com/SAML2/"/>
+
             <saml:SubjectConfirmationData NotOnOrAfter="2014-07-12T14:22:03.246Z" Recipient="https://alias.smartsimple.com/SAML2/"/>
 
         </saml:SubjectConfirmation>
 
         </saml:SubjectConfirmation>
 
       </saml:Subject>
 
       </saml:Subject>
−
       <saml:Conditions NotOnOrAfter="2014-07-12T14:22:03.246Z"NotBefore="2014-07-12T14:12:03.246Z">
+
       <saml:Conditions NotOnOrAfter="2014-07-12T14:22:03.246Z" NotBefore="2014-07-12T14:12:03.246Z">
 
         <saml:AudienceRestriction>
 
         <saml:AudienceRestriction>
 
           <saml:Audience>sso:saml2:alias:stage:SmartSimple:sp</saml:Audience>
 
           <saml:Audience>sso:saml2:alias:stage:SmartSimple:sp</saml:Audience>
 
         </saml:AudienceRestriction>
 
         </saml:AudienceRestriction>
 
       </saml:Conditions>
 
       </saml:Conditions>
−
       <saml:AuthnStatementAuthnInstant="2014-07-12T14:17:03.246Z"SessionIndex="X14MvZtPaqyUjfFCbehto32uDTG">
+
       <saml:AuthnStatement AuthnInstant="2014-07-12T14:17:03.246Z" SessionIndex="X14MvZtPaqyUjfFCbehto32uDTG">
 
         <saml:AuthnContext>
 
         <saml:AuthnContext>
 
           <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified</saml:AuthnContextClassRef>
 
           <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified</saml:AuthnContextClassRef>
 
         </saml:AuthnContext>
 
         </saml:AuthnContext>
 
       </saml:AuthnStatement>
 
       </saml:AuthnStatement>
−
       <saml:AttributeStatementxmlns:xs="http://www.w3.org/2001/XMLSchema">
+
       <saml:AttributeStatement xmlns:xs="http://www.w3.org/2001/XMLSchema">
−
         <saml:AttributeNameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"Name="Email">
+
         <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="Email">
−
             <saml:AttributeValuexmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:type="xs:string">david@alias.com</saml:AttributeValue>
+
             <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">david@email.com</saml:AttributeValue>
−
        </saml:Attribute>
 
−
        <saml:AttributeNameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="UID">
 
−
            <saml:AttributeValuexmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:type="xs:string">T5014CD</saml:AttributeValue>
 
 
         </saml:Attribute>
 
         </saml:Attribute>
−
         <saml:AttributeNameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"Name="First name">
+
         <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="First name">
−
             <saml:AttributeValuexmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:type="xs:string">David</saml:AttributeValue>
+
             <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">David</saml:AttributeValue>
 
         </saml:Attribute>
 
         </saml:Attribute>
−
         <saml:AttributeNameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"Name="Last name">
+
         <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="Last name">
−
             <saml:AttributeValuexmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:type="xs:string">Smith</saml:AttributeValue>
+
             <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Smith</saml:AttributeValue>
 
         </saml:Attribute>
 
         </saml:Attribute>
−
         <saml:AttributeNameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"Name="Department">
+
         <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="Department">
−
             <saml:AttributeValuexmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:type="xs:string">Shipping</saml:AttributeValue>
+
             <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Shipping</saml:AttributeValue>
 
         </saml:Attribute>
 
         </saml:Attribute>
−
         <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"Name="Roles">
+
         <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="Roles">
−
             <saml:AttributeValuexmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:type="xs:string">Clerk</saml:AttributeValue>
+
             <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Clerk</saml:AttributeValue>
 
         </saml:Attribute>
 
         </saml:Attribute>
 
       </saml:AttributeStatement>
 
       </saml:AttributeStatement>
 
   </saml:Assertion>
 
   </saml:Assertion>
−
</samlp:Response></pre>
 
  
−
==Cipher encrypted reference==
+
</samlp:Response>
−
{{Template:Deprecated-sm}}
+
 
 +
</pre></div>
 +
 
 +
===SAML Authorization Request Example===
 +
Example below is sent by the Service Provider (SmartSimple) to the Identity Provider in the SP-SSO initiated flow.
 +
 
 +
<div id="mw-content-text" lang="en-GB" dir="ltr" class="mw-content-ltr">
 +
<pre>
 +
<?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>
 +
</pre></div>
 +
 
 +
==Adding URL Redirect in the Login Page==
 +
From the [[Login Page]], the SSO URL redirect can be added to redirect internal users to the client's Identity Provider login page.
 +
 
 +
 
 +
To configure, go to 
 +
 
 +
1. Waffle → Global Settings → Branding → Login Pages
 +
 
 +
2. From the Login Pages listview, select the default login page to add the SSO URL redirect to.
 +
 
 +
3. Go to the Singe Sign-On section, select the MES Group Identifier and add the Link Label i.e. Employee Login
 +
 
 +
4. Click Save
 +
 
 +
 
 +
Variables to use in a custom page layout:
 +
 
 +
*  @ssodisplaylink@    -   the variable to use to add the Link Label and hyperlink in the login template 
 +
* @ssotargetlink@   -   the variable to use to retrieve the SSO login URL<br /> <br /> 
 +
 
 +
==Troubleshooting==
 +
In order to retrieve information about why SSO is failing, first toggle the "Debug Mode" option within the SSO configuration in SmartSimple, and then test the SSO in order to generate log data within the Configuration Error Log.
 +
 
 +
* '''SAML failed. No user account found'''
 +
 
 +
: This means that a corresponding active user was not found in the SmartSimple instance. Check the [Unique Identifier Field] that is configured in the SSO setting, and then compare the value of the "NameID" node sent within the SAML assertion to see if a user with that field value exists in SmartSimple. Check that the user is activated and allows login.
 +
* '''SAML failed. Login session is null  /  Invalid SAML Response'''
 +
 
 +
: Check that a matching user account exist
 +
: Check x509 certificate
 +
: Verify that the endpoint in the SSO assertion is correct. There should be a Response node with a parameter like Destination="https://alias.smartsimple.com/SAML2/"
 +
* '''SAML signature validation failed'''
 +
 
 +
: This means that the x509 certificate does not match between the SAML Assertion and the value configured in the instance SSO settings.
 +
* '''SAML response expired'''
 +
 
 +
: Check the datetime value of the parameter named ''NotAfter'' and ''NotBefore'' within the SAML Assertion and compare these with the expected datetime that the assertion was sent. It is possible to adjust the '''Timestamp Time Zone''' dropdown settings.
 +
* '''Invalid response format. Unparseable date'''.
 +
 
 +
: Check that the SAML Assertion contains both parameters: ''NotAfter'' and ''NotBefore''
 +
* '''SAML processing error'''
 +
 
 +
: Check that the value for the ''SSO Alias'' is "SAML2" for SSO in production instance
 +
: If it is for a Multi Environment, value in the ''SSO Alias'' should be the value in the attribute ''SSOModule''
 +
* '''No log file is found in SmartSimple'''
 +
 
 +
: Verify the parameter: Destination="https://alias.smartsimple.com/SAML2/" from the SSO Assertion.
 +
: Check that the value for the ''SSO Alias'' is "SAML2" for SSO in production instance.
 +
: If it is for a Multi Environment, value in the ''SSO Alias'' should be the value in the attribute ''SSOModule''
 +
* '''After logging thru SSO, you are redirected to "mesagetype=30"'''
 +
 
 +
: Verify that the alias of the instance is correct. To verify the alias, go to '''''Waffle''''' → '''''Global Settings''''' → '''''Branding''''' → '''''Web Alias'''''. Make sure that the Web Alias value is the same as the domain alias.
 +
* '''SAML InReponseTo does not match any of the possible Request IDs'''
 +
 
 +
: Verify the alias of the instance is correct.
 +
: Verify that the SSO configuration for multiple environment do not have duplicate MES Environment Identifier.
 +
 
 +
==Expected Behaviour for Role Mapping==
 +
<!--Ticket#124791 - SSO to update roles for existing users for a fully federated SSO-->
 +
'''Scenerio 1:  ''User Access Mapping'' set to ''Disabled'' / ''Create New User'' on ''No Match'' is ''OFF'''''
 +
* User will not be created if user does not exist in the SmartSimple instance
 +
* Only existing users in the SmartSimple instance will be able to login and no role/status updates for existing users
 +
 
 +
 
 +
'''Scenerio 2:  ''User Access Mapping'' set to ''Disabled'' / ''Create New User'' on ''No Match'' is ''ON''  '''
 +
 
 +
* User will be created with default new user role / default new user status settings if users does not exist in the SmartSimple instance
 +
* No role updates based on default new user role / default new user status if user exists
 +
 
 +
 
 +
'''Scenerio 3:  ''User Access Mapping'' set to ''Enabled'' / ''Create New User'' on ''No Match'' is ''OFF'' / No Assertion defined  '''
 +
 
 +
* User will not be created if user does not exist in the SmartSimple instance
 +
* No role updates if accessing SSO with existing users
 +
 
 +
 
 +
'''Scenerio 4:  ''User Access Mapping'' set to ''Enabled'' / ''Create New User'' on ''No Match'' is ''OFF'' / Assertion is defined  '''
 +
 
 +
* User will not be created if user does not exist in the SmartSimple instance
 +
* No role updates if accessing with existing account
 +
* No role updates if it is not referenced in the defined assertion
 +
* Role updates if accessing with existing account only if they are defined in the ''User Roles Assertion Mapping''. Role update will be based on the mappings defined under ''Mapping''.
 +
 
 +
 
 +
'''Scenerio 5:  ''User Access Mapping'' set to ''Enabled'' / ''Create New User'' on ''No Match'' is ''ON''  / No Assertion defined'''
 +
 
 +
* User will be created with default new user role / default new user status settings if user does not exist in the SmartSimple instance
 +
* No role updates if accessing with existing account that does not have roles defined in the ''User Roles Assertion Mapping''
 +
 
 +
 
 +
'''Scenerio 6:  ''User Access Mapping'' set to ''Enabled'' / ''Create New User'' on ''No Match'' is ''ON'' / Assertion is defined  '''
 +
 
 +
* User will be created with roles defined in the assertion if user does not exists in the SmartSimple instance and assertion roles are defined in the ''User Roles Assertion Mapping''
 +
* User role updates based on the defined assertion if accessing with existing accounts that has roles defined in the assertion
 +
* No role updates if accessing with existing accounts that has no roles defined in the assertion or if roles in assertion was not mapped in the ''User Roles Assertion Mapping''
 +
 
 +
 
 +
'''Scenerio 7:  ''User Access Mapping'' set to ''Classic Mode'' / ''Create New User'' on ''No Match'' is ''ON''  / No Assertion is defined'''
 +
 
 +
* User will be created with default new user role / default new user status settings if user does not exist in the SmartSimple instance
 +
* No role updates if accessing with user account that already exists in the SmartSimple instance
 +
 
 +
 
 +
'''Scenerio 8:  ''User Access Mapping'' set to ''Classic Mode'' / ''Create New User'' on ''No Match'' is ''ON''  / Assertion is defined'''
 +
 
 +
* User will be created with roles defined in the assertion if user does not exist in the SmartSimple instance and assertion roles are defined in the ''User Roles Assertion Mapping''
 +
* User will be created with default new user role / default new user status settings if user does not exists in the SmartSimple instance and if assertion roles do not exist in the ''User Roles Assertion Mapping''
 +
* When Access Mapping is set to Classic Mode and there is no mapping section, role updates will only happen in user creation and the roles in assertion has to have the same user role names matching value with the SmartSimple role names. 
 +
 
  
−
The SmartSimple cipher-encrypted reference SSO is accessed by passing parameters in the URL, including an encrypted token, for authentication.
+
==Example of SSO configuration in SmartSimple==
−
<br /><br />''Example'':
+
===Configuration for SSO in production instance===
−
:<nowiki>http://myalias.smartsimple.com/QryAuth/?em=2&alias=myalias&message=dnnOBh9xvqPSC9uXZFAz10Tc</nowiki>
+
SmartSimple SSO Configuration as the Service Provider in the client's SmartSimple production instance.
  
−
===URL Request Parameters===
 
  
−
{|class="wikitable"
+
'''A. SSO Configuration'''
−
|'''Parameter Name'''
+
 
−
|'''Description'''
+
1. Navigate to '''Global Settings''' → '''Integrations''' tab → '''Single Sign-On''' section
−
|'''Sample'''
+
 
−
|-
+
2. Click on the “'''+'''” icon to create a new SSO configuration on the instance
−
|em
+
 
−
|Encryption method
+
3. Fill out the mandatory fields:
−
|1 or 2
+
 
−
|-
+
: '''SSO Alias''': '''''SAML2''''' (default alias for production instance)
−
|alias
+
: '''Signing Certificate (X.509)''': cut and paste the x509 certificate after configuration of the client's Identity Provider
−
|SSO alias
+
: '''Timestamp Time Zone''': '''''--UTC/GMT--''''' (default from the dropdown)
−
|ssoalias
+
: '''MES Group Identifier''': '''''SSOProd''''' (open text field)
−
|-
+
: '''MES Environment Identifier''': '''''alias.smartsimple.com''''' (client's url production instance)
−
|message
+
: '''Method''': '''''Identity Provider-initiated''''' (default setting)
−
|Encrypted String, encryption method is indicated by em parameter
+
: '''Identity Provider Service Endpoint''': this is the url login redirect.
−
|cm90YXJ5Oztjcm1 ……
+
:: 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'''
  
−
'''em (1 or 2)'''
+
1. Navigate to '''Global Settings''' → '''Branding''' tab → '''Login Pages''' section
−
1 – Message is encoded by base64 only (for systems that do not support DES encryption).
 
−
2 – Message is first encrypted by "DES" using a provided key and then encoded by base64.
 
  
−
'''alias'''
+
2. From the '''Primary''' tab, click on the pencil icon for the first item on the list view - the default Login Page
−
Identifies which SSO settings should be used. SmartSimple supports multiple SSO entries.
 
  
−
'''message'''
+
3. From the '''General''' tab, go to the '''Single Sign-On''' section and complete fields:
−
A string composed  of 11 elements delimited by two semi-colons (;;). For example,
 
−
88;;Id12345;;John;;Smith;;Contact,Internal Staff;;Toronto branch;;Canada Office;;abc@gmail.com;;Canada;;2011-11-08 12:30:00;;English
 
  
−
There must be no spaces between elements.
+
: '''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 the username/password.
  
−
Key used: AD789034 (example only)
 
  
−
Encrypted Message will be: I%2BA%2B/Qb73aUmJZyP5f3/9Lm90fIguwkAgKovK0626HxbeT7cGfdZfSGyDdAybGstBwHBZgDYqc3uhgS7YTQIxzQXIfAovKCzbHLhc/Nh/AizHemadQL1SNRQeNwKz9%2B37IR%2BrwQyvR2Qlh0On8zy7cDSZYm/QKL5EmGV3g9Z%2B10=
+
[[File:SSO_Login.png|thumb|none|300px|SSO User Creation Settings.]]
  
−
Note: When base64 encoding results include a '+' character, please replace '+' with '%2B'
+
===Configuration for multi-environment SSO===
 +
If client has 4 environments (Prod, Backup, Dev, Test), settings above will be created one for each environment.
  
−
===Element Position===
+
Note that these settings will need to be copied over to different instances so as when T2P occurs, all settings are existing and copied over and no editing is necessary after T2P.
  
−
{|class="wikitable"
+
{| class="wikitable"
−
|'''Element<br />Position'''
 
−
|'''Description'''
 
−
|'''Sample'''
 
−
|'''Options'''
 
 
|-
 
|-
−
|1
+
!| 
−
|Reserved Constant
+
!|SSO Alias
−
|Always 88
+
!|Description
−
|Mandatory
+
!|MES Group Identifier
 +
!|MES Environment Identifier
 
|-
 
|-
−
|2
+
||1
−
|Unique identifier of user. If this ID is not found in SmartSimple, either a new user will be created or the request will be rejected. This is controlled by the SSO settings within SmartSimple.
+
||<span style="color: #ff0000;">SAML2</span>
−
|Id12345
+
||This is used for production instance
−
|Mandatory
+
||SSOID1
 +
||alias.smartsimple.com
 
|-
 
|-
−
|3
+
||2
−
|First Name
+
||BKSSO
−
|John
+
||SSO for backup instance
−
|*Optional
+
||SSOID1
 +
||alias.smartsimplebk.com
 
|-
 
|-
−
|4
+
||3
−
|Last Name
+
||DevSSO
−
|Smith
+
||SSO for DEV instance
−
|*Optional
+
||SSOID1
 +
||alias-dev.smartsimple.com
 
|-
 
|-
−
|5
+
||4
−
|Comma delimited list of roles (by name) to be assigned to the user.
+
||TestSSO
−
|Contact, Internal Staff
+
||SSO for TEST instance
−
|*Optional
+
||SSOID1
 +
||alias-test.smartsimple.com
 +
|}
 +
 
 +
Notes:
 +
 
 +
1. All columns above are open text fields and can be renamed as desired.  Item 1's alias name is the only default/required value for prod.
 +
 
 +
2. For items 2 to 4, the attribute name "'''''SSOModule'''''"  with the  '''''SSO Alias''''' value should be included in the Identity Provider configuration. Note that the SSO Alias is case sensitive and should be labelled exactly.
 +
 
 +
3. From the Login Page, the MES Group Identifier will be the same as shown "'''''SSOID1'''''". It will redirect to the correct Redirect URL Endpoint as it will recognize what instance the user is trying to use the SSO in.
 +
 
 +
===Configuration for two IdP within production instance===
 +
Example configuration below is when a client has two existing Identity Provider Services.
 +
 
 +
All SSO configuration below are used for client's production instance:
 +
 
 +
{| class="wikitable"
 
|-
 
|-
−
|6
+
!| 
−
|Parent Company (one level above the user's company)
+
!|SSO Alias
−
|Canada Office
+
!|Description
−
|Optional
+
!|MES Group Identifier
 +
!|MES Environment Identifier
 
|-
 
|-
−
|7
+
||1
−
|Company
+
||<span style="color: #ff0000;">SAML2</span>
−
|Toronto Branch
+
||IdP Service 1
−
|*Optional
+
||SSOID1
 +
||alias.smartsimple.com
 
|-
 
|-
−
|8
+
||2
−
|E-mail address
+
||SSOProd2
−
|abc@gmail.com
+
||IdP Service 2
−
|*Optional
+
||SSOID2
−
|-
+
||alias.smartsimple.com
−
|9
 
−
|Country
 
−
|Canada
 
−
|*Optional
 
−
|-
 
−
|10
 
−
|Date Time Stamp (GMT). Login will only succeed if the server time is within +- 10 minutes of this timestamp. This is to prevent bookmarking the SSO URL and token. If the SSO settings within SmartSimple have “debug=on”, then the timestamp is ignored.
 
−
|2011-11-08 12:30:00
 
−
|Mandatory
 
−
|-
 
−
|11
 
−
|Language
 
−
|English
 
−
|Optional
 
 
|}
 
|}
  
 +
Notes:
  
−
* NOTE: Optional items listed with an asterisk are mandatory if this will result in creation of a new user (only relevant if the Single Sign-On setting “Create User” is enabled).
+
1. Item 1 is for client's first Identity Provider Service.
  
−
The 6th parameter (Parent Company) can result in changes to the organizational hierarchy. The Company (parameter 7) will be moved under the Parent Company, so this should be used with caution if this effect is not desired.
+
2.Item 2 is the second configuration for the client's second Identity Provider Service. The attribute name "'''''SSOModule'''''"  with the  '''''SSO Alias''''' value should be included in the Identity Provider configuration. Note that the SSO Alias is case sensitive and should be labelled exactly.
  
−
===Cipher Encrypted Reference Sample Code===
 
−
The following are examples of code for Cipher Encrypted Reference SSO configuration:
 
  
−
====PHP====
 
−
 
−
Sample and library: http://nl3.php.net/manual/en/mcrypt.ciphers.php
 
−
====Java====
 
−
No extra library required.
 
−
 
−
Sample code:
 
−
<pre style="white-space: pre-wrap;  white-space: -moz-pre-wrap;  white-space: -pre-wrap;  white-space: -o-pre-wrap;  word-wrap: break-word;">
 
−
 
−
import java.security.spec.KeySpec;
 
−
import javax.crypto.Cipher;
 
−
import javax.crypto.SecretKey;
 
−
import javax.crypto.SecretKeyFactory;
 
−
importjavax.crypto.spec.DESKeySpec;
 
−
import sun.misc.BASE64Decoder;
 
−
import sun.misc.BASE64Encoder;
 
−
 
−
/**
 
−
*
 
−
*@author  User
 
−
*/
 
−
public class DESEncrypt {
 
−
   
 
−
    /**Creates a new instance of DESEncrypt */
 
−
  public DESEncrypt() {
 
−
    }
 
−
   
 
−
  public static String encrypt(String keystr,String msg)
 
−
    {try{byte[] keyAsBytes = keystr.getBytes();
 
−
      KeySpec myKeySpec = new DESKeySpec(keyAsBytes);
 
−
      SecretKeyFactory mySecretKeyFactory =SecretKeyFactory.getInstance("DES");
 
−
      Cipher cipher Cipher.getInstance("DES/ECB/ PKCS5Padding");
 
−
      SecretKey  key =mySecretKeyFactory.generateSecret(myKeySpec);
 
−
      cipher.init(Cipher.ENCRYPT_MODE, key);
 
−
      byte[] plainText = msg.getBytes();
 
−
          byte[] encryptedText = cipher.doFinal(plainText);
 
−
          BASE64Encoder base64encoder = new BASE64Encoder();
 
−
          return base64encoder.encode(encryptedText);
 
−
    }catch (Exception e){return null;}
 
−
    }
 
−
   
 
−
  public static String decrypt(String keystr,String msg)
 
−
  {try{byte[] keyAsBytes = keystr.getBytes();
 
−
      KeySpec myKeySpec = new DESKeySpec(keyAsBytes);
 
−
      SecretKeyFactory mySecretKeyFactory =SecretKeyFactory.getInstance("DES");
 
−
      Cipher cipher = Cipher.getInstance("DES/ECB/ PKCS5Padding");
 
−
      SecretKey  key =mySecretKeyFactory.generateSecret(myKeySpec);
 
−
      cipher.init(Cipher.DECRYPT_MODE, key);
 
−
      BASE64Decoder base64decoder = new BASE64Decoder();
 
−
          byte[] encryptedText = base64decoder.decodeBuffer(msg);
 
−
          return new String(cipher.doFinal(encryptedText));
 
−
  }catch (Exception e){return null;}
 
−
    }
 
−
}
 
−
</pre>
 
−
 
−
====Vb.Net Sample====
 
−
<pre style="white-space: pre-wrap;  white-space: -moz-pre-wrap;  white-space: -pre-wrap;  white-space: -o-pre-wrap;  word-wrap: break-word;">Imports System.Security.Cryptography
 
−
 
−
Public Function SSOEncrypt(ByValstrkey As String,ByVal strMessage AsString)
 
−
 
−
        Dim inputByteArray() AsByte = StrToByteArray(strMessage)
 
−
 
−
        Dim key As Byte()
 
−
        key =StrToByteArray(strkey)
 
−
 
−
        Dim des As New DESCryptoServiceProvider
 
−
      des.Mode = CipherMode.ECB
 
−
      des.Key = key
 
−
        Dim ms As New MemoryStream
 
−
        Dim cs As New CryptoStream(ms,des.CreateEncryptor(), CryptoStreamMode.Write)
 
−
      cs.Write(inputByteArray, 0, inputByteArray.Length)
 
−
      cs.FlushFinalBlock()
 
−
 
−
        Return Convert.ToBase64String(ms.ToArray())
 
−
 
−
End Function
 
−
 
−
Public Shared FunctionStrToByteArray(ByVal str As String) As Byte()
 
−
 
−
        Dim encoding As New System.Text.UTF8Encoding
 
−
        Return encoding.GetBytes(str)
 
−
 
−
End Function
 
−
</pre>
 
  
−
==See Also==
 
−
* [[Password Policy]]
 
  
−
[[Category:Security]][[Category:Sign-Up Features]]
+
[[Category:Integration]][[Category:System Integration]]
 +
[[Category:Identity and Access Management]]
 +
[[Category:Security]]

Latest revision as of 15:33, 14 November 2023

Overview

SmartSimple provides Single Sign-On (SSO) integration through SAML 2.0. It should be noted that SSO is just a subset of federated identity management, as it relates only to authentication, and not account management or synchronization with SmartSimple.

Implementation of SSO requires configuration both within SmartSimple and within the system that will provide the authentication.

SmartSimple's implementation of SSO acts as the Service Provider and assumes the client has the infrastructure and resources to host, configure, and manage the Identity Provider service. Please contact your account manager or SmartSimple Support for further information.

SAML 2.0

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

Identity Provider-initiated authentication is supported, meaning the end user will first authenticate on the client-side system/infrastructure and then be forwarded to SmartSimple. The client Identity Provider service will construct a base64-encoded SAML assertion and send this to the user's browser. The user's browser will then relay this assertion to the SmartSimple server for SSO authentication.

After the November 2022 upgrade, Service Provider-initiated authentication is now supported. The Service Provider sends the SAML Authorization Request message and forwarding the user to the client Identity Provider service for authentication. The end user will login from the client-side Identity Provider. After the end user has been 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, third-party or otherwise, for use with this feature. Enabling and maintaining the Identity Provider is your responsibility.
  • You must provide SmartSimple with a public key in base64-encoded X.509 Certificate format for digital signature validation.

Service Provider Configuration - SmartSimple

Within SmartSimple, SSO settings are accessed through the Global Settings → Integration tab.

Navigating to the SSO configuration.


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


SSO configuration settings.

Mandatory Settings

  • SSO Alias - used to identify the SSO connection and should be configured by default to be 'SAML2'. If multiple SSO connections are to be configured then 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) - used to identify the user account and needs to be an attribute that is unique to each user in SmartSimple. The value for the attribute "NameID" from the SSO assertion should match the value from the field selected in the dropdown list.(typically e-mail address or employee ID).
  • X509Certificate (SAML2 Only) - the signing certificate to be provided by the client. The formatting of this should be the certificate value without the "begin certificate" and "end certificate" header and footer lines. Also, depending on how the client-side system sends this value within the SAML assertion the certificate value will typically be formatted to just a single line but could also be multiple lines and so must be entered into SmartSimple in the same format.
  • Timestamp Time Zone - used to read the incoming SSO message timestamp from Identity Provider configured time zone.  Default value is "--UTC/GMT--". Settings will need to be adjusted when the error "SAML response expired" is found in the log file during debug mode.
  • Third-Party Identity Provider- specify what SSO authentication method is used  (Identity-Provider initiated  or  Service Provider-initiated)
    • Endpoint - specify the redirect IdP-initiated or SP-Initiated endpoint.  This redirect will be rendered in the Login Page.
  • It is also recommended to disable the Session Timeout Alert setting within the Global Settings → Security section as that feature would not be applicable to users logged in through single sign-on.
  • By default, SSO acts as an additional method of authentication. If you wish to enforce the use of SSO, and restrict the regular username and password authentication, you can do so with the Global Settings → Integration → Enforce SSO setting which allows you to restrict a set of user roles to only be able to login through SSO.

Additional Settings

  • Default Landing Page - used to specify an initial landing page within SmartSimple instance. This should be a relative path (e.g. /iface/ex/ax_index.jsp).
  • Logout Redirect URL - redirect url when SSO users logout
  • Enable Logout Assertion - will send a logout assertion to the Identity Provider to log out of that session
Additional settings for Enable Logout Assertion:
Assertion Target URL - target site url
Assertion Private Key - private key to establish connection with the target site.
User Creation Option (JIT Provisioning)

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

  • Create New User on No Match– when enabled, it will create new user when no matching is found and will allow login for new user upon successful authentication
  • Define User Roles Through Custom Attribute– when enabled, it will use the SSO assertion “Roles” attribute to define users’ system roles.
  • Default User Role When No Matching Role Found *– selected role from this dropdown will be assigned to new created users only if “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’s status for new users only
  • Create New Organization When No Match Found – when enabled, it will create a new parent organization when no matching organization exists your SmartSimple instance.
  • Default Organization *– assigned user’s parent organization for new users
  • Default New Organization Status– assigned parent organization’s status for new organizations

* - mandatory fields when creating users thru SSO.


In addition, optional attributes can be added in the assertion to create the user and these 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 in the JIT provisioning.


SSO User Creation Settings.
Optional Attibutes

The following optional attributes can be used in the assertion. Please note that they are case sensitive and should be labelled exactly.

  • SSOModule - used to specify the SmartSimple SSO connection when there are multiple connections configured. i.e. "SAML2" for prod, "SSOBK" for backup instance, "SSODEV" for dev instance, "SSOTest" for test instance. Note that the attribute name and attribute value are case sensitive 
  • Email
  • First name
  • Last name
  • Department - used to update the user's organization. This will attempt to match an organization by name and will move the user to that organization if found.
  • Roles - used 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 - used 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

Apply Role Mapping to new and existing users to control user roles within your SmartSimple system. Define the list of system roles you wish to be monitored upon 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 upon the role mapping below, the user will be provisioned with all the 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 be monitored upon 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 behaviour of this settings can be found in Section 4

Multi Environment Support

When you have multiple environments with unique SSO configurations (such as production, testing, development and backup), group them under the same MES group identifier. This will give you 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 tis SSO service endpoint on the login page i.e. alias.smartsimple.com or  alias.smartsimplebk.com

Additional settings to be configured is from 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 button label i.e. Employee Login.

X.509 Certificate on the SP-Initiated SSO

In the July 2023 upgrade, a new feature to support X.509 signing certificate for single sign-on (SSO) authorization requests has been added. If you are using 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 is located 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 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 service provider metadata that can be used, however you must first replace every instance of 'alias.smartsimple.com' instead 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 are a high-level approximation and example of how one may setup minimal SSO functionality. Additional steps may be needed for your Identity Provider. These do may constitute recommended best practices, and we recommend you consult the documentation offered by your Identity Provider.

Active Directory Federation Services (ADFS)

If using ADFS refer to the below steps as related to SmartSimple for setup. Some steps unrelated to your SmartSimple configuration have been omitted.

Azure Identity Provider

Configuration items listed are specifics SSO to work in SmartSimple:

  • Log into Azure as admin
  • Go to Azure Active Directory → Enterprise Application → Create a new application
  • Select Non-Gallery Application and then add your new application, enter 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 or user.employeeid or any unique identifier in the user profile fields
2. Additional claims - additional attributes are needed when 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 is going to be used in the SmartSimple configuration "SSO Alias"
Note that all attribute names are case sensitive and should be named as indicated above.  First name, Last name and Email are mandatory to create a new user. 
  • To test, go 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 make sure that the current user is existing in the SmartSimple instance to have a successful SSO login.


After configuration has been completed, provide the following to SmartSimple:

  1. x509 certificate - download the Federation Metadata XML (Found under Single Sign-on  →  SAML Certificates)
  2. Value used for the NameID - this will be used as the identifier between 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 OKTA admin account
  • Click on the Application tab and select Applications.
  • Click on the Add Application button and click on Create New App to create a new application for SmartSimple.
  • Set the Platform as Web, the Sign on method as SAML 2.0 and Create a new application.
  • In the General Settings page, provide a name for the application i.e. SmartSimple SSO
  • In the Configure SAML tab, under SAML Settings, 
  • Configuration Settings below have default value: 
    • 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

Note that all attribute names are case sensitive and should be named as indicated above. First name, Last name and Email are mandatory to create a new user.


After configuration in OKTA has been completed, provide the following to SmartSimple:

  1. x509 certificate - found under Sign On tab, SAML Set up "View SAML set up instructions"
  2. Value used for the NameID - this will be used as the identifier between SP and IdP
  3. URL Redirect - "Embed Link" for IdP-initiated SSO (Found under "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 in the Login Page

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


To configure, go to 

1. Waffle → Global Settings → Branding → Login Pages

2. From the Login Pages listview, select the default login page to add the SSO URL redirect to.

3. Go to the Singe Sign-On section, select the MES Group Identifier and add the Link Label i.e. Employee Login

4. Click Save


Variables to use in a custom page layout:

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

Troubleshooting

In order to retrieve information about why SSO is failing, first toggle the "Debug Mode" option within the SSO configuration in SmartSimple, and then test the SSO in order to generate log data within the Configuration Error Log.

  • SAML failed. No user account found
This means that a corresponding active user was not found in the SmartSimple instance. Check the [Unique Identifier Field] that is configured in the SSO setting, and then compare the value of the "NameID" node sent within the SAML assertion to see if a user with that field value exists in SmartSimple. Check that the user is activated and allows login.
  • SAML failed. Login session is null  /  Invalid SAML Response
Check that a matching user account exist
Check x509 certificate
Verify that the endpoint in the SSO assertion is correct. There should be a Response node with a parameter like Destination="https://alias.smartsimple.com/SAML2/"
  • SAML signature validation failed
This means that the x509 certificate does not match between the SAML Assertion and the value configured in the instance SSO settings.
  • SAML response expired
Check the datetime value of the parameter named NotAfter and NotBefore within the SAML Assertion and compare these with the expected datetime that the assertion was sent. It is possible to adjust the Timestamp Time Zone dropdown settings.
  • Invalid response format. Unparseable date.
Check that the SAML Assertion contains both parameters: NotAfter and NotBefore
  • SAML processing error
Check that the value for the SSO Alias is "SAML2" for SSO in production instance
If it is for a Multi Environment, value in the SSO Alias should be the value in the attribute SSOModule
  • No log file is found in SmartSimple
Verify the parameter: Destination="https://alias.smartsimple.com/SAML2/" from the SSO Assertion.
Check that the value for the SSO Alias is "SAML2" for SSO in production instance.
If it is for a Multi Environment, value in the SSO Alias should be the value in the attribute SSOModule
  • After logging thru SSO, you are redirected to "mesagetype=30"
Verify that the alias of the instance is correct. To verify the alias, go to Waffle → Global Settings → Branding → Web Alias. Make sure that the Web Alias value is the same as the domain alias.
  • SAML InReponseTo does not match any of the possible Request IDs
Verify the alias of the instance is correct.
Verify that the SSO configuration for multiple environment do not have duplicate MES Environment Identifier.

Expected Behaviour for Role Mapping

Scenerio 1:  User Access Mapping set to Disabled / Create New User on No Match is OFF

  • User will not be created if user does not exist in the SmartSimple instance
  • Only existing users in the SmartSimple instance will be able to login and no role/status updates for existing users


Scenerio 2:  User Access Mapping set to Disabled / Create New User on No Match is ON  

  • User will be created with default new user role / default new user status settings if users does not exist in the SmartSimple instance
  • No role updates based on default new user role / default new user status if user exists


Scenerio 3:  User Access Mapping set to Enabled / Create New User on No Match is OFF / No Assertion defined  

  • User will not be created if user does not exist in the SmartSimple instance
  • No role updates if accessing SSO with existing users


Scenerio 4:  User Access Mapping set to Enabled / Create New User on No Match is OFF / Assertion is defined  

  • User will not be created if user does not exist in the SmartSimple instance
  • No role updates if accessing with existing account
  • No role updates if it is not referenced in the defined assertion
  • Role updates if accessing with existing account only if they are defined in the User Roles Assertion Mapping. Role update will be based on the mappings defined under Mapping.


Scenerio 5:  User Access Mapping set to Enabled / Create New User on No Match is ON  / No Assertion defined

  • User will be created with default new user role / default new user status settings if user does not exist in the SmartSimple instance
  • No role updates if accessing with existing account that does not have roles defined in the User Roles Assertion Mapping


Scenerio 6:  User Access Mapping set to Enabled / Create New User on No Match is ON / Assertion is defined  

  • User will be created with roles defined in the assertion if user does not exists in the SmartSimple instance and assertion roles are defined in the User Roles Assertion Mapping
  • User role updates based on the defined assertion if accessing with existing accounts that has roles defined in the assertion
  • No role updates if accessing with existing accounts that has no roles defined in the assertion or if roles in assertion was not mapped in the User Roles Assertion Mapping


Scenerio 7:  User Access Mapping set to Classic Mode / Create New User on No Match is ON  / No Assertion is defined

  • User will be created with default new user role / default new user status settings if user does not exist in the SmartSimple instance
  • No role updates if accessing with user account that already exists in the SmartSimple instance


Scenerio 8:  User Access Mapping set to Classic Mode / Create New User on No Match is ON  / Assertion is defined

  • User will be created with roles defined in the assertion if user does not exist in the SmartSimple instance and assertion roles are defined in the User Roles Assertion Mapping
  • User will be created with default new user role / default new user status settings if user does not exists in the SmartSimple instance and if assertion roles do not exist in the User Roles Assertion Mapping
  • When Access Mapping is set to Classic Mode and there is no mapping section, role updates will only happen in user creation and the roles in assertion has to have the same user role names matching value with the SmartSimple role names. 


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 on the instance

3. Fill out the mandatory fields:

SSO Alias: SAML2 (default alias for production instance)
Signing Certificate (X.509): cut and paste the x509 certificate after configuration of 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 production instance)
Method: Identity Provider-initiated (default setting)
Identity Provider Service Endpoint: this is the url 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 on the list view - the default Login Page

3. From the General tab, go to the Single Sign-On section and complete 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 the username/password.


SSO User Creation Settings.

Configuration for multi-environment SSO

If client has 4 environments (Prod, Backup, Dev, Test), settings above will be created one for each environment.

Note that these settings will need to be copied over to different instances so as when T2P occurs, all settings are existing and copied over and no editing is necessary after T2P.

  SSO Alias Description MES Group Identifier MES Environment Identifier
1 SAML2 This is used for production instance SSOID1 alias.smartsimple.com
2 BKSSO SSO for backup instance SSOID1 alias.smartsimplebk.com
3 DevSSO SSO for DEV instance SSOID1 alias-dev.smartsimple.com
4 TestSSO SSO for TEST instance SSOID1 alias-test.smartsimple.com

Notes:

1. All columns above are open text fields and can be renamed as desired.  Item 1's alias name is the only default/required value for prod.

2. For items 2 to 4, the attribute name "SSOModule"  with the  SSO Alias value should be included in the Identity Provider configuration. Note that the SSO Alias is case sensitive and should be labelled exactly.

3. From the Login Page, the MES Group Identifier will be the same as shown "SSOID1". It will redirect to the correct Redirect URL Endpoint as it will recognize what instance the user is trying to use the SSO in.

Configuration for two IdP within production instance

Example configuration below is when a client has two existing Identity Provider Services.

All SSO configuration below are used for client's production instance:

  SSO Alias Description MES Group Identifier MES Environment Identifier
1 SAML2 IdP Service 1 SSOID1 alias.smartsimple.com
2 SSOProd2 IdP Service 2 SSOID2 alias.smartsimple.com

Notes:

1. Item 1 is for client's first Identity Provider Service.

2.Item 2 is the second configuration for the client's second Identity Provider Service. The attribute name "SSOModule"  with the  SSO Alias value should be included in the Identity Provider configuration. Note that the SSO Alias is case sensitive and should be labelled exactly.

Retrieved from ‘https://wiki.smartsimple.com/index.php?title=Single_Sign-On&oldid=42062’