Smartstaff
1,385
edits
Changes
→User Creation Option (JIT Provisioning)
===Service Provider Configuration - SmartSimple===
Within SmartSimple, SSO settings are accessed through the '''''Global Setting -> Integration Settings''''' →''''' Integration''' ''tab.
[[File:sso-001.png|thumb|none|600px|Navigating to the SSO configuration.]]
* '''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]]
: '''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:
* '''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.]]
=====Role Mapping=====
Detailed expected behaviour of this settings can be found in Section 4
=====Multi Environment Support (MES)=====
<!--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 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 → '''''Waffle''''' → '''''Global Settings → Branding → 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''.
====Optional AttibutesX.509 Certificate on the SP-Initiated SSO====The following optional attributes can be used in <!-- 148020 - Adding SP x509 signing certificate for SSO metadata and SSO authorization request -->In the assertionJuly 2023 upgrade, a new feature to support X. Please note that they are case sensitive and should be labelled exactly. * '''SSOModule''' 509 signing certificate for single sign- used to specify the SmartSimple on (SSO connection when there are multiple connections configured) authorization requests has been added.* '''Email'''* '''First name'''* '''Last name'''* '''Department''' If you are using a service provider- used to update initiated SSO, a signed authentication request embedded with the user's organization. This will attempt to match an organization by name signed value and will move the user to that organization if foundX.* '''Roles''' - used 509 certificate will be sent to update the user's roles in SmartSimple for new users. This should be a comma delimited list of SmartSimple user roles identity provider (by nameIdP) to be assigned to the user.* '''Language''' The new setting is located at Global Settings > Integrations tab > Single Sign-on > Edit a SP- used initiated SSO and toggle on Sign authentication request sent to specify the initial language displayed to the user. This should be an integer value that corresponds with a language ID value in SmartSimple identity provider (e.g. 1=EnglishIdP).
===Identity Provider Configuration - Client-Side System===
</md:ContactPerson>
</md:EntityDescriptor>
</pre>
====Active Directory Federation Services (ADFS)====
# URL Redirect
#* "User Access URL" for IdP-initiated SSO (Found under "''Properties''")
#* "Logon Login URL" for SP-initiated SSO (Found under ''Single Sign-on'' → ''Set up 'Application Name')''
====OKTA====
</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==
: 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 nullnull / Invalid SAML Response'''
: Check that a matching user account exist
* '''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'''
==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.
==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.
[[File:SSO_Login.png|thumb|none|300px|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.
{| class="wikitable"
|-
!|
!|SSO Alias
!|Description
!|MES Group Identifier
!|MES Environment Identifier
|-
||1
||<span style="color: #ff0000;">SAML2</span>
||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:
{| class="wikitable"
|-
!|
!|SSO Alias
!|Description
!|MES Group Identifier
!|MES Environment Identifier
|-
||1
||<span style="color: #ff0000;">SAML2</span>
||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.
