Latest revision as of 15:29, July 29, 2022

Configuring SSO

DO NOT PUBLISH

You can configure Gplus Adapter to use either your own IDP or Salesforce as an IDP. You can choose one of these two options:

Gplus Adapter configured with SSO and your own Identity Provider (IDP).
Gplus Adapter integrated with Salesforce SSO as the IDP.

This option provides an improved experience over the first option.

Gplus Adapter configured with SSO and your own IDP

To configure Gplus Adapter with SSO and your own Identity Provider (IDP), perform the following steps:

Ensure that SSO for Workspace Web Edition Agent Workspace release 9 has been enabled in your environment by following the instructions in the Setting up agents on the system article and the SAML authentication article.
To ensure that your IDP page is not blocked by the browser and successfully opens in the Gplus Adapter iframe, verify your IDP response headers configuration:
- For the Chrome, Firefox, and Microsoft Edge browsers:
  If the IDP server response contains the obsolete X-Frame-Options header, consider replacing it with the Content-Security-Policy header setting.
  
  For example (Lightning):
  
  Content-Security-Policy: frame-ancestors 'self' https://*.genesyscloud.com https://*.lightning.force.com;
  
  For example (Classic):
  
  Content-Security-Policy: frame-ancestors 'self' https://*.genesyscloud.com https://*.slaesforce.com;
- For the Internet Explorer 11 browser:
  
  If IDP server response contains X-Frame-Options header, add ALLOW-FROM URI to the header setting.
  For example (Lightning):
  
  X-Frame-Options: ALLOW-FROM https://<your-server-name>.genesyscloud.com/ https://<your-server-name>.lightning.force.com/;
  
  For example (Classic):
  
  X-Frame-Options: ALLOW-FROM https://<your-server-name>.genesyscloud.com/ https://<your-server-name>.salesforce.com/;
For more information about Gplus Adapter configuration for IDP, see this Salesforce Knowledge Article.

Gplus Adapter follows the security rules for iFrame embedded applications in Chrome, Firefox, and Microsoft Edge browsers, if the SameSite by default cookies flag in the agent's browser is enabled by default or by the agent and the IDP provider did not set SameSite=None for cookies, the agent's IDP login page might get blocked by the browser.

To solve this problem, you must reconfigure the IDP responses so that the SameSite=None cookie is present in the IDP response.

If you have your agents' browser configured to treat cookies as SameSite=Lax by default, then you likely also have the Cookie without SameSite must be secure rule enabled as well. In this case, the cookie from the same IDP must have the Secure flag set.

For more information about configuring browser security settings, refer to the documentation for the browsers used by your organization.
For SSO logout configuration, use the following Workspace Web Edition Logout options:
- auth.session.invalidate-on-logout
- login.show-change-account-link
Adapter is now ready to use with SSO.

Salesforce as SSO and IDP

You can simplify your agent log in process by integrating Gplus Adapter with Salesforce to use Salesforce as your single sign-on (SSO) identity provider (IDP). This means that your agent only has to provide their Username and Tenant to log in to Gplus Adapter after they have logged into Salesforce using Salesforce as your SSO identity provider.

Follow these steps to set up SSO with Salesforce as the identity provider:

Enable Salesforce as an Identity Provider

Prerequisites

You must have an Admin role in your organization's Salesforce account
User email address (username) that you use to login to Salesforce. Note: Username email addresses must be the same in both Salesforce and Gplus Adapter.

Enable Salesforce as an Identity Provider

Follow the steps in the Enable Salesforce as an Identity Provider article in the Salesforce Help.
In the Identity Provider view, click Download Metadata to obtain a copy of the IDP metadata XML.

Enable SSO on Genesys tenants

Employing SAML for SSO requires two parts, a Service Provider (Genesys Auth Service) and an Identity Provider (Salesforce). To complete your Service Provider configuration, you must upload the Salesforce Identity Provider IDP-metadata XML file you created in the previous procedure to xxx.

Download and open the SP-Metadata XML file in an XML viewer and find the Location parameter. You will need this parameter for the Entity ID and the ACS URL when you define Gplus Adapter as a Connected App in Salesforce. The Location URL looks something like this: https://gws-usw1.genhtcc.com/auth/v3/saml/SSO/alias/<string representing the Entity ID>.
In the interaction-workspace section of the Workspace application object, set the value of the auth.session.invalidate-on-logout option to false. This ensures that when an agent exits Gplus Adapter, only the session is removed and the agent is redirected to a session ended page.
In the interaction-workspace section of the Workspace application object, set the value of the login.show-change-account-link to false to hide the Change login account link on the login error page and the second step login page.

Salesforce does not take into account configuration of enforceAuthN in SAML authentication requests as described in SAML settings.

Define Gplus Adapter as a Connected App in Salesforce

To configure a new Connected App follow the instructions in the Salesforce Help Defining Service Providers as SAML-Enabled Connected Apps document.
Specify the required fields under Basic Information:
- Connected App Name (for example, Gplus Adapter)
- API Name (for example, GWS)
- Contact email (the email address of the Admin user)
Under Web App Settings, select Enable SAML
Use the Location string from the SP-Metadata xml file of the Enable Salesforce as an Identity Provider procedure to provide Entity ID and ACS URL:
- Entity ID: The long string of numbers and letters at the end of the Location parameter URL after the last "/".
- ACS URL: The URL from the Location parameter that you obtained from the SP-Metadata in step 2 of the Enable SSO on Genesys tenants procedure.
Use the identity provider event log to troubleshoot errors when trying to log in to Gplus Adapter.

Agent SSO login workflow

This is the general workflow when Gplus Adapter initiates the login process and uses Salesforce to identify the user:

An agent logs in to Salesforce.
The agent provides their Username and Tenant name in Gplus Adapter and clicks Next.
GPlus Adapter sends a request to Salesforce to authenticate the user.
Salesforce identifies the agent specified in the request and sends an authentication response.
Gplus Adapter authenticates the response sent by Salesforce.
If the agent is authenticated, they are logged in to Gplus Adapter while logged in to Salesforce.

@@ Line 1: / Line 1: @@
-= Single sign-on (SSO) integration to connect Workspace with SalesForce services =
+=Configuring SSO =
+{{Chgbar_open}}DO NOT PUBLISH{{Chgbar_close}}
+{{#ponycomment:Mwest|Waiting for SSO availability in PREM|GAPI-20136}}
+You can configure Gplus Adapter to use either your own IDP or Salesforce as an IDP. You can choose one of these two options:
+<ol>
+<li><p>'''Gplus Adapter configured with SSO and [[GPlusSSO90#OwnIDP|your own Identity Provider (IDP)]]'''.</p></li>
+<li>
+<p>'''Gplus Adapter integrated with [[GPlusSSO90#SFSSO|Salesforce SSO as the IDP]]'''.</p>
+<p>This option provides an improved experience over the first option.</p>
+</li>
+</ol>
+{{AnchorDiv|OwnIDP}}
+==Gplus Adapter configured with SSO and your own IDP==
+To configure Gplus Adapter with SSO and your own Identity Provider (IDP), perform the following steps:
+<ul>
+<li>Ensure that SSO for Workspace Web Edition Agent Workspace release 9 has been enabled in your environment by following the instructions in the [[SettingUpAgents|Setting up agents on the system article]] and the [[Documentation:HTCC:Dep:SecuredConnectionsSAML|SAML authentication article]].</li>
+<li>To ensure that your IDP page is not blocked by the browser and successfully opens in the Gplus Adapter iframe, verify your IDP response headers configuration:
+<ul>
+<li>
+<p>For the Chrome, Firefox, and Microsoft Edge browsers:</p><p>If the IDP server response contains the obsolete '''X-Frame-Options''' header, consider replacing it with the '''Content-Security-Policy''' header setting.</p>
+<p>For example (Lightning):</p>
+<p><tt>Content-Security-Policy: frame-ancestors 'self' <nowiki>https://*.genesyscloud.com https://*.lightning.force.com;</nowiki></tt></p>
+<p>For example (Classic):</p>
+<p><tt>Content-Security-Policy: frame-ancestors 'self' <nowiki>https://*.genesyscloud.com https://*.slaesforce.com;</nowiki></tt></p>
+</li>
+<li><p>For the Internet Explorer 11 browser:</p>
+<p>If IDP server response contains '''X-Frame-Options''' header, add '''ALLOW-FROM URI''' to the header setting.</p><p>For example (Lightning):</p>
+<p><tt>X-Frame-Options: ALLOW-FROM <nowiki>https://<your-server-name>.genesyscloud.com/ https://<your-server-name>.lightning.force.com/;</nowiki></tt></p>
+<p>For example (Classic):</p>
+<p><tt>X-Frame-Options: ALLOW-FROM <nowiki>https://<your-server-name>.genesyscloud.com/ https://<your-server-name>.salesforce.com/;</nowiki></tt></p>
+</li>
+</ul>
+<p>For more information about Gplus Adapter configuration for IDP, see this [https://help.salesforce.com/articleView?id=000354489&language=en_US&type=1&mode=1 Salesforce Knowledge Article].</p>
+</li>
+{{AnchorDiv|SameSite}}
+<li>
+<p>Gplus Adapter follows the security rules for iFrame embedded applications in Chrome, Firefox, and Microsoft Edge browsers, if the '''SameSite by default cookies''' flag in the agent's browser is enabled by default or by the agent and the IDP provider did not set '''SameSite=None''' for cookies, the agent's IDP login page might get blocked by the browser.</p>
+<p>To solve this problem, you must reconfigure the IDP responses so that the '''SameSite=None''' cookie is present in the IDP response.</p>
+<p>If you have your agents' browser configured to treat cookies as '''''SameSite=Lax''''' by default, then you likely also have the '''Cookie without SameSite must be secure''' rule enabled as well. In this case, the cookie from the same IDP must have the '''Secure''' flag set.</p>
+<p>For more information about configuring browser security settings, refer to the documentation for the browsers used by your organization.</p>
+</li>
+<li>For SSO logout configuration, use the following Workspace Web Edition [[SettingUpAgents#SSOLogout|Logout]] options:
+<ul>
+<li>{{Optionslink|link=Options:Genesys_Web_Services:interaction-workspace:auth-session-invalidate-on-logout|auth.session.invalidate-on-logout}}</li>
+<li>{{Optionslink|link=Options:Genesys_Web_Services:interaction-workspace:login-show-change-account-link}}</li>
+</ul>
+</li>
+<li>Adapter is now ready to use with SSO.</li>
+</ul>
-. Follow the Word doc (can I get the screen shots without the arrows?) SF is the only IDP for now?
+{{AnchorDiv|SFSSO}}
-. Follow the format of this doc https://help.mypurecloud.com/articles/add-salesforce-as-a-single-sign-on-provider/
+==Salesforce as SSO and IDP==
-. Customer has to get info from GWS site entity ID and ACS URL -- provided by API? ASk Eugene (and Yuriy) how this occurs. Maybe as a reference to the API docs?
+You can simplify your agent log in process by integrating Gplus Adapter with Salesforce to use Salesforce as your single sign-on (SSO) identity provider (IDP). This means that your agent only has to provide their Username and Tenant to log in to Gplus Adapter after they have logged into Salesforce using Salesforce as your SSO identity provider.
-Only scren shots for Connected App
+Follow these steps to set up SSO with Salesforce as the identity provider:
+# [[GPSSO#IDP|Enable Salesforce as an Identity Provider]]
+# [[GPSSO#ConnectedApp|Define Gplus Adapter as a Connected App in Salesforce]]
+<!--
+{{NoteFormat|SSO is applicable to both test and production environments. Genesys recommends that you test SSO in your testing environment before using it in a production environment.|1}}-->
+===Enable Salesforce as an Identity Provider===
+====Prerequisites====
+* You must have an Admin role in your organization's Salesforce account
+* User email address (username) that you use to login to Salesforce. '''Note:''' Username email addresses must be the same in both Salesforce and Gplus Adapter.
+{{AnchorDiv|IDP}}
+====Enable Salesforce as an Identity Provider====
+<ol>
+<li>Follow the steps in the [https://help.salesforce.com/articleView?id=identity_provider_enable.htm Enable Salesforce as an Identity Provider] article in the '''Salesforce Help'''.</li>
+<li>In the '''Identity Provider''' view, click '''Download Metadata''' to obtain a copy of the IDP metadata XML.</li>
+</ol>
+===Enable SSO on Genesys tenants===
+<ol>
+{{Chgbar_open}}
+<li>Employing [https://developers.onelogin.com/saml SAML] for SSO requires two parts, a Service Provider (Genesys Auth Service) and an Identity Provider (Salesforce). To complete your Service Provider configuration, you must upload the Salesforce Identity Provider IDP-metadata XML file you created in the previous procedure to {{Editgrn_open}}xxx{{Editgrn_close}}. {{#ponycomment:Mwest|Point to PREM Auth guide that Julie is working on|GAPI-18448}}</li>
+{{Chgbar_close}}
+<li>Download and open the SP-Metadata XML file in an XML viewer and find the '''Location''' parameter. You will need this  parameter for the Entity ID and the ACS URL when you define Gplus Adapter as a Connected App in Salesforce. The '''Location''' URL looks something like this: <tt><nowiki>https://gws-usw1.genhtcc.com/auth/v3/saml/SSO/alias/<string representing the Entity ID></nowiki></tt>.</li>
+<li>In the '''interaction-workspace''' section of the Workspace application object, set the value of the {{Optionslink|link=Options:Genesys_Web_Services:interaction-workspace:auth-session-invalidate-on-logout|auth.session.invalidate-on-logout}} option to <tt>false</tt>. This ensures that when an agent exits Gplus Adapter, only the session is removed and the agent is redirected to a session ended page.</li>
+<li>In the '''interaction-workspace''' section of the Workspace application object, set the value of the {{Optionslink|link=Options:Genesys_Web_Services:interaction-workspace:login-show-change-account-link|login.show-change-account-link}} to <tt>false</tt> to hide the '''Change login account''' link on the login error page and the second step login page.</li>
+</ol>
+Salesforce does not take into account configuration of '''enforceAuthN''' in SAML authentication requests as described in [https://all.docs.genesys.com/PEC-Admin/Current/Admin/SSO#SAML_settings SAML settings].
+{{AnchorDiv|ConnectedApp}}
+===Define Gplus Adapter as a Connected App in Salesforce===
+<ol>
+<li>To configure a new Connected App follow the instructions in the Salesforce Help [https://help.salesforce.com/articleView?id=service_provider_define.htm&type=5 Defining Service Providers as SAML-Enabled Connected Apps] document.</li>
+<li>Specify the required fields under '''Basic Information''':
+<ul>
+<li>Connected App Name (for example, Gplus Adapter)</li>
+<li>API Name (for example, GWS)</li>
+<li>Contact email (the email address of the Admin user)</li>
+</ul>
+</li>
+<li>Under Web App Settings, select '''Enable SAML'''</li>
+<li>Use the '''Location''' string from the SP-Metadata xml file of the Enable Salesforce as an Identity Provider procedure to provide Entity ID and ACS URL:
+<ul>
+<li>Entity ID: The long string of numbers and letters at the end of the '''Location''' parameter URL after the last "/". </li>
+<li>ACS URL: The URL from the '''Location''' parameter that you obtained from the SP-Metadata in step 2 of the ''Enable SSO on Genesys tenants'' procedure.</li>
+<p>For example (Lightning):</p>
+<p>[[File:Gplus_900_Salesforce_Setup_New_Connected_App_View.png|500px]]</p>
+<p>For example (Classic):</p>
+<p>[[File:Gplus_900_Salesforce_Setup_New_Connected_App_View_Classic.png|500px]]</p>
+</ul>
+</li>
+<li>Use the [https://help.salesforce.com/articleView?id=identity_provider_error_log.htm&type=5 identity provider event log] to troubleshoot errors when trying to log in to Gplus Adapter.</li>
+</ol>
+===Agent SSO login workflow===
+This is the general workflow when Gplus Adapter initiates the login process and uses Salesforce to identify the user:
+# An agent logs in to Salesforce.
+# The agent provides their Username and Tenant name in Gplus Adapter and clicks '''Next'''.
+# GPlus Adapter sends a request to Salesforce to authenticate the user.
+# Salesforce identifies the agent specified in the request and sends an authentication response.
+# Gplus Adapter authenticates the response sent by Salesforce.
+# If the agent is authenticated, they are logged in to Gplus Adapter while logged in to Salesforce.
+====Useful links====
+* [https://developer.salesforce.com/docs/atlas.en-us.externalidentityImplGuide.meta/externalidentityImplGuide/external_identity_provide_sso.htm Salesforce guide]
+* [http://salesforce.vidyard.com/watch/I6j0O6jqr8ZTtoj5Wm_Fjg Video example from Salesforce]
+<!--* [https://help.mypurecloud.com/articles/about-single-sign-on-sso/ Example of the same SSO implementation in Genesys Cloud]-->
 [[Category:V:HTCC:9.0.0DRAFT]]

Latest revision as of 15:29, July 29, 2022

Configuring SSO

Gplus Adapter configured with SSO and your own IDP

Salesforce as SSO and IDP

Enable Salesforce as an Identity Provider

Prerequisites

Enable Salesforce as an Identity Provider

Enable SSO on Genesys tenants

Define Gplus Adapter as a Connected App in Salesforce

Agent SSO login workflow

Useful links

Contact

Genesys

Customer Care

Legal