Difference between revisions of "Single Sign-On"

From SmartWiki
Jump to: navigation, search
(→‎SAML Authorization Request Example)
(→‎Identity Provider Configuration - Client-Side System)
Line 71: Line 71:
 
The elements required for setup of the client-side identity provider connection are listed below.
 
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, or optionally within an element named 'UID'.
+
* 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/'''.
 
* 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's Entity ID - this can be the URL to your SmartSimple system, e.g. '''https://alias.smartsimple.com/'''.
Line 95: Line 95:
 
</pre>
 
</pre>
  
−
====Active Directory Federation Services====
+
====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.
 
If using ADFS refer to the below steps as related to SmartSimple for setup. Some steps unrelated to your SmartSimple configuration have been omitted.
  
Line 103: Line 103:
 
* 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.
 
* 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'''.
 
* 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====
 +
 +
====OKTA====
  
 
===SAML Assertion Example===
 
===SAML Assertion Example===

Revision as of 14:07, 5 January 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 Setting -> 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. This needs to be an attribute common to both the SmartSimple and the client-side system (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

To enable adding new users/organizations, the following Options should be enabled:

  • Bypass Two 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 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).
  • 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.
Role Mapping
User Creation Option
Multi Environment Support (MES)

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.
  • 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).

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>

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

OKTA

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://whateveristheidentityproviderurl/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>

Troubleshooting

Expected Behaviour for Role Mapping

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