|
|
| Line 1: |
Line 1: |
| − | {{Article | + | {{Glossaryterm|term=Key-Value Pair|text=key-value pairs (KVPs)}} |
| − | |Standalone=Yes | |
| − | |DisplayName=Provisioning PureEngage Hybrid Integrations
| |
| − | |Platform=PureEngage
| |
| − | |TocName=Provisioning
| |
| − | |ComingSoon=No
| |
| − | |Context=Complete the provisioning steps in this article to setup a hybrid integration between Genesys PureEngage On-Premises deployments and Genesys Cloud services. This integration gives you access to many of the great Genesys Cloud Services in your On-Premises deployments.
| |
| − | |Section={{Section
| |
| − | |sectionHeading=Supported Services
| |
| − | |Type=Unstructured
| |
| − | |anchor=SupportedServices
| |
| − | |freetext=The following [https://help.mypurecloud.com PureCloud services] are supported and have supplementary documentation:
| |
| − | * {{Link-AnywhereElse|product=ATC|display text=Genesys Altocloud}}
| |
| − | ** {{Link-AnywhereElse|product=ATC|version=Current|manual=WDEPlugin|topic=About|display text=Altocloud for Workspace Desktop Edition}}
| |
| − | ** {{Link-AnywhereElse|product=ATC|version=Current|manual=PacingServiceDeployment|topic=About|display text=Agent Pacing Service}}
| |
| − | |Status=No
| |
| − | }}{{Section
| |
| − | |sectionHeading=About Provisioning
| |
| − | |Type=Unstructured
| |
| − | |anchor=About
| |
| − | |freetext=Before doing anything described in this article, first consult your Genesys Professional Services team. proceeding with the information in this article you should consult with the Genesys Professional Services team that you are working with to obtain the information needed to complete the provisioning.
| |
| − | | |
| − | To support the different authentication mechanisms in PureCloud Integration, you must create a transaction object in Genesys PureEngage Configuration Server. PureEngage On-Premises Services, Components, and UIs will use this information to authenticate with the PureCloud Common Services and UIs.
| |
| − | | |
| − | Use Genesys Administrator Extension to manually create all of the PureCloud Common Service–related configuration information in Configuration Server at the Tenant level.
| |
| − | | |
| − | After you purchase a common cloud service, a PureCloud Organization is created for you and you will receive a welcome email to activate your admin accounts with PureCloud.
| |
| − | | |
| − | A '''PureCloud organization''' has been created for you to support your hybrid integration. This organization has been provisioned with the following:
| |
| − | * The base functionality required for your Common Cloud integration.
| |
| − | * An '''Admin console''' that you may use to configure your Common Cloud integration.
| |
| − | * A user with the '''PureCloud Admin''' role, which includes default admin permissions as well as Single Sign-On and any integration-specific permissions.
| |
| − | * A default '''AI Agent''' role (if required by your integration) that provides agent access to AI services, such as Altocloud.
| |
| − | | |
| − | As an administrator, you may access your PureCloud organization by logging in at https://login.mypurecloud.com (or a [https://developer.mypurecloud.com/api/rest/index.html region specific login] URL; The PureCloud welcome email directs you to the appropriate application URL for your region) with the credentials you set when you activate your PureCloud account from the welcome email you received.
| |
| − | | |
| − | Upon activation of your PureCloud account, perform the steps in the PureCloud Provisioning Steps section below using the PureCloud Admin UI or the [https://developer.mypurecloud.com/api/rest/v2/ PureCloud API].
| |
| − | | |
| − | With the credentials provided in the Welcome email, you can log in to the '''PureCloud Admin''' UI for [https://developer.mypurecloud.com/api/rest/index.html your region] to perform the provisioning steps described in the next section.
| |
| − | # In the '''PureCloud Admin''' UI, select '''Account Settings'''.
| |
| − | # Open '''Organization Settings'''.
| |
| − | # In the '''Organization Details''' tab, open '''Advanced'''.
| |
| − | # Copy the Company Name, Short Name, and Organization ID — you will need these values to complete your account configuration in the '''PureEngage On Premises: Transaction object for hybrid integrations''' section. For example:<br>[[File:Hybrid_Organization_Name_And_ID.png|500px]]
| |
| − | The following diagram provides an overview of how PureEngage utilizes PureCloud services such as Altocloud:<br>[[File:Hybrid_PureEngage_Premise_Integration_Phase_1.png|500px]]
| |
| − | |Status=No
| |
| − | }}
| |
| − | {{Section
| |
| − | |sectionHeading=PureCloud Provisioning Steps
| |
| − | |Type=Unstructured
| |
| − | |freetext=For ''each'' PureCloud Organization that is created for each of your tenants (for environments with multiple PureEngage tenants), perform the following steps using the PureCloud Admin UI or the PureCloud API.
| |
| − | <ol>
| |
| − | <li><p>For each PureEngage Service that uses a common service you must create an OAuth client to allow for better control and monitoring of the components using the PureCloud Services and for different rate limiting per client. (This does not mean that if you have ''n'' number of components on premises that are associated with one another, they cannot share a given client id.)</p>
| |
| − | <p>Genesys recommends that you consult architecture before performing this step.</p>
| |
| − | <p>Login to your [https://developer.mypurecloud.com/api/rest/index.html PureCloud Region], then follow these steps:</p>
| |
| − | <ol type="a">
| |
| − | <li>Create a Client Credential OAuth Client that is to based on the specific services you are using, such as the [https://all.docs.genesys.com/ATC/Current/PacingServiceDeployment/ProvisioningArticle Pacing Service]. It is required to create the PureCloud PureEngage Identity Provider (IDP). In your PureCloud Region, create a Client Credential Grant. Open '''Integrations''', select '''OAuth''', and enter '''PureEnagage Client Credentials''' as the App name in the '''Client Details''' tab. Select the '''Client Credentials''' grant type.<br>
| |
| − | [[File:Hybrid_Client_Credential_OAuth_Grant.png|500px]]<br>
| |
| − | In the '''Roles''' tab, assign the '''Admin''' role and set the division as '''Home'''.<br>
| |
| − | [[File:Hybrid_Client_Credentials_Role_Assignment.png|500px]]<br>
| |
| − | As necessary, for each on-premises service, like the "Agent Pacing Service" ('''ewt'''), create OAuth Client Credentials grants:
| |
| − | <ul>
| |
| − | <li>Using the UI, follow [https://help.mypurecloud.com/articles/create-an-oauth-client/ these steps],<br>
| |
| − | [[File:Hybrid_Client_Credential_OAuth_Grant.png|500px]]
| |
| − | </li>
| |
| − | <li>Or using the API, reference [https://developer.mypurecloud.com/api/rest/v2/oauth/ these endpoints].</li>
| |
| − | <li>Copy the client ID and Secret for later use.</li>
| |
| − | </ul>
| |
| − | For more information about Permissions for Altocloud, see the [https://help.mypurecloud.com/articles/altocloud-permissions-overview/ Altocloud permissions overview].
| |
| − | </li>
| |
| − | <li>Create a SAML2 Bearer OAuth Client for the client, such as PureEngage Workspace Desktop Edition, that needs to send a SAMLResponse to exchange for a PureCloud Access Token:
| |
| − | <ol type="i">
| |
| − | <li>In '''PureCloud Admin''', select '''Integrations'''>'''OAuth''', then click '''Add Client'''.</li>
| |
| − | <li>Name the Client and select '''SAML2 Bearer''' as the '''Grant Type'''.</li>
| |
| − | <li>Enter the Authorized redirect URI, for example: <nowiki>https://apps.mypurecloud.com</nowiki><br>
| |
| − | [[File:Hybrid_SAML2Bearer_Creation.png|500px]]
| |
| − | </li>
| |
| − | <li>Next, select '''Authorized Applications''' and include the scope(s) in the authorization.<br>
| |
| − | [[File:Hybrid_SAML2Bearer_Authorization.png|500px]]
| |
| − | </li>
| |
| − | <li>Copy the client ID and Secret for later use.</li>
| |
| − | </ol>
| |
| − | </li>
| |
| − | </ol>
| |
| − | </li>
| |
| − | <li>Create your SAML Certificate (public key) and private key. You can perform this task with open source tools or with the tools preferred by your IT department for security purposes. Whichever tools you use, you must produce both private and public keys in the form of a PEM file. For example:<br>
| |
| − | <source lang="text">
| |
| − | openssl req -new -x509 -days 3652 -nodes -out cert.pem -keyout key.pem
| |
| − | </source>
| |
| − | Save the cert.pem (public key) and key.pem (private key) for use in the creation of the Transaction object described in the next section.
| |
| − | </li>
| |
| − | <li>Create a PureEngage Identity Provider (IDP). You can use the Identity Provider API via the [https://developer.mypurecloud.com/developer-tools/#/api-explorer PureCloud Developer Tools], [https://developer.mypurecloud.com/api/rest/client-libraries/ SDKs], or [https://developer.mypurecloud.com/api/rest/v2/identityprovider/ Platform APIs].<br>
| |
| − | Sample Request:<br>
| |
| − | <source lang="text">
| |
| − | PUT https://api.{{environment}}/api/v2/identityproviders/pureengage
| |
| − |
| |
| − | {
| |
| − | "name": "PureEngage",
| |
| − | "autoProvisionUsers": true,
| |
| − | "certificate": "Content of the cert.pem file without the ---BEGIN CERTIFICATE— and ---END CERTIFICATE--- text blocks",
| |
| − | "issuerURI": "http://www.genesys.com/pureengage",
| |
| − | "ssoTargetURI": "http://example.com/target",
| |
| − | "disabled": false
| |
| − | }
| |
| − | </source>
| |
| − | <p>'''issuerURI''': the URI set when you created the SAML certificate in Step 2 (above).</p>
| |
| − | <p>'''ssoTargetURI''': the http redirect URL which should resolve to your PureCloud domain. Example: https://app.mypurecloud.com (domain varies according to your region).</p>
| |
| − | '''Troubleshooting''':
| |
| − | <ul>
| |
| − | <li>Ensure that the IDP is set with "autoProvisionUsers" = "true"</li>
| |
| − | <li>Ensure an exact match with the saml/issuer option of the Transaction object described in the PureEngage configuration.</li>
| |
| − | <li>Ensure that you don't have multiple issuers with the same URI.</li>
| |
| − | </ul>
| |
| − | </li>
| |
| − | <li>By default, Altocloud permissions are included in the '''Admin''' and '''AI Agent''' roles (which includes all necessary permissions for using Altocloud). As auto-provisioned users are created with the '''employee''' role, which does not include Altocloud permissions. You must grant the [https://help.mypurecloud.com/articles/altocloud-permissions-overview/ Altocloud permissions] to the employee role. You may grant Altocloud permissions to additional roles as needed. Copy these role names for the '''PureEngage On Premises: Transaction object for hybrid integrations''' steps below.</li>
| |
| − | <li>(Optional as needed) Create additional '''Admin''' accounts by [https://help.mypurecloud.com/articles/add-people-organization/ adding people to your organization] and [https://help.mypurecloud.com/articles/assign-roles-divisions-licenses-and-add-ons/ assigning them] to the '''Admin''' role.</li>
| |
| − | </ol>
| |
| − | |Status=No
| |
| − | }}{{Section
| |
| − | |sectionHeading=PureEngage On Premises: Transaction object for hybrid integrations
| |
| − | |Type=Unstructured
| |
| − | |anchor=TransactionObjHybrid
| |
| − | |freetext=A transaction object is needed for Genesys components to authenticate with Genesys Cloud.
| |
| − | <ol>
| |
| − | <li>Create a transaction object (and alias) of type '''list''' named '''hybrid_integration''' in the '''Transaction''' folder of the '''Environment''' tenant.
| |
| − | <ul>
| |
| − | <li>Tenant characteristics:
| |
| − | <ul>
| |
| − | <li>'''Single tenant deployment''': If your PureEngage deployment is ''not'' multi-tenant, the transaction object should be in the '''Transaction''' folder in the '''Environment''' or '''Resources''' structure.</li>
| |
| − | <li>'''Multi-tenant deployment''': If your PureEngage deployment is multi-tenant, there must be a separate transaction object under ''each'' of the tenant structures. The transaction objects represent the connectivity to the different PureCloud Orgs representing these different tenants. You ''cannot'' place a transaction object in the Environment structure and share it across tenants because you need a separate PureCloud Org for each tenant.<br>
| |
| − | '''WARNING''': If you are running Workspace Desktop Edition 8.5.133.02, you must ensure that the agents of a Tenant do ''not'' have READ access on the 'hybrid_integration' Transaction objects of the ''other'' tenants.
| |
| − | </li>
| |
| − | </ul>
| |
| − | </li>
| |
| − | </ul>
| |
| − | </li>
| |
| − | <li>Create the following Object options in the '''general''' section:
| |
| − | <ul>
| |
| − | <li>'''organization_sname''': The PureCloud organization short name for this tenant.</li>
| |
| − | <li>'''organization_id''': The PureCloud organization id for this tenant.</li>
| |
| − | <li>'''default_agent_role_name''': The default PureCloud agent role name for an '''AI Agent'''. This will always be '''employee'''. </li>
| |
| − | <li>'''default_admin_role_name''': The default PureCloud admin role name. This is '''admin'''.</li>
| |
| − | <li>'''base_auth_url''': The base auth URL that can be used for any PureCloud service; for example: '''base_auth_url''' should be <nowiki>https://[region_host]/oauth/token</nowiki> (for example: <nowiki>"https://login.mypurecloud.com/oauth/token"</nowiki>). <nowiki>[region_host]</nowiki> is the authentication-based FQDN for the region; the regions are listed on [https://developer.mypurecloud.com/api/rest/ this page].</li>
| |
| − | <li>'''base_service_url''': The base URL that can be used for any PureCloud service; for example: '''base_service_url''' should be <nowiki>https://[region_host]/api/</nowiki>. <nowiki>[region_host]</nowiki> should be the API-based FQDN for the region; the regions are listed on [https://developer.mypurecloud.com/api/rest/ this page]. The rest of the URL is PureCloud service and version specific; for example: '''...v2/conversations'''. The '''base_service_url''' and the service specific portion is combined in your component code.</li>
| |
| − | </ul>
| |
| − | </li>
| |
| − | <li>Use the two PEM files that you created in the PureCloud Provisioning section to perform the following steps. This example show you how to do it in an open source tool; check with your IT department to determine the best tool to use to meet your security requirements.
| |
| − | <ul>
| |
| − | <li>Encode cert.pem into a base64 string (cert.pem.b64) using this command:
| |
| − | <source lang="text">
| |
| − | openssl base64 -in cert.pem -out cert.pem.b64
| |
| − | </source>
| |
| − | </li>
| |
| − | <li>Encrypt the key.pem using a password that you specify
| |
| − | <source lang="text">
| |
| − | openssl rsa -in key.pem -out key.pem.enc -aes256
| |
| − | </source>
| |
| − | </li>
| |
| − | <li>Encode the resulting content into a base64 string (=>’key.pem.enc.b64’) using this command:
| |
| − | <source lang="text">
| |
| − | openssl base64 -in key.pem.enc -out key.pem.enc.b64
| |
| − | </source>
| |
| − | </li>
| |
| − | </ul>
| |
| − | </li>
| |
| − | <li>Create the following Object options in the '''saml''' section:
| |
| − | <ul>
| |
| − | <li>'''issuer''': The SAML IDP URI that you created in the PureCloud Provisioning steps above (for example: <nowiki>https://www.genesys.com/pureengage</nowiki>).</li>
| |
| − | <li>'''certificate''': The public key of the SAML related certificate encoded in base64; for example: cert.pem.b64 created in step 3.</li>
| |
| − | <li>'''pkey''': The encrypted private key of the SAML related certificate encoded in base64; for example: key.pem.enc.b64 created in step 3.</li>
| |
| − | <li>'''password''': The password to decrypt the private key that you specified in step 3.</li>
| |
| − | <li>'''expire_time''': The expiration time (in hours) for the access token. The default is 24 hours. This might be overridden on the server side.</li>
| |
| − | </ul>
| |
| − | </li>
| |
| − | <li>For each PureEngage service that uses a PureCloud common service (specified at step#1) you must create a dedicated section in the Transaction object:
| |
| − | <ul>
| |
| − | <li>Create the following Object options in the '''saml_auth''' section for the OAuth client for SAML Authentication from the client (such as Workspace Desktop Edition) that you created in step 1b of the PureCloud Provisioning section of type SAML2 Bearer:
| |
| − | <ul>
| |
| − | <li>'''client_id''': The SAML2 Bearer client ID created in step 1b of the PureCloud Provisioning section.</li>
| |
| − | <li>'''password''': The SAML2 Bearer client secret created in step 1b of the PureCloud Provisioning section.</li>
| |
| − | </ul>
| |
| − | </li>
| |
| − | <li>For the Agent Pacing Service, create the following Object options in the '''ewt''' section for the pacing engine to connect to PureCloud:
| |
| − | <ul>
| |
| − | <li>'''client_id''': The Client Credential Grant Client ID that you created in step 1c of the PureCloud Provisioning section.</li>
| |
| − | <li>'''password''': The Client Credential Grant Client secret that you created in step 1c of the PureCloud Provisioning section.</li>
| |
| − | </ul>
| |
| − | </li>
| |
| − | </ul>
| |
| − | </li>
| |
| − | </ol>
| |
| − | |Status=No
| |
| − | }}{{Section
| |
| − | |sectionHeading=Opening Your Network
| |
| − | |Type=Unstructured
| |
| − | |freetext=You must modify the permissions on our network to permit the PureEngage Components and UIs to access PureCloud Common APIs over your network and into the Internet. To do this, you must create a set of new firewall rules for the PureCloud Authentication and Common Services URLs.
| |
| − | |Status=No
| |
| − | }}
| |
| − | }} | |
