|
|
| (66 intermediate revisions by 5 users not shown) |
| Line 1: |
Line 1: |
| − | {{Article
| + | #REDIRECT [[ATC/ProvisioningMulticloudCX]] |
| − | |Standalone=Yes
| |
| − | |DisplayName=Provisioning PureEngage Hybrid Integrations
| |
| − | |Platform=PureEngage
| |
| − | |TocName=Provisioning
| |
| − | |ComingSoon=No
| |
| − | |Context=This article describes the essential provisioning steps to enable a hybrid integration between PureEngage On-Prem deployments and Genesys PureCloud services.
| |
| − | |Section={{Section
| |
| − | |sectionHeading=Supported Services
| |
| − | |Type=Unstructured
| |
| − | |anchor=SupportedServices
| |
| − | |freetext=The following 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 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 Configuration Server under the environment and associated script folder with the following data. 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, you will receive a welcome email to activate your admin accounts with PureCloud. With those credentials 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'''.
| |
| − | # Enter your organization name and the organization ID provided to you. For example:<br>[[File:Hybrid_Organization_Name_And_ID.png|500px]]
| |
| − | | |
| − | |Status=No
| |
| − | }}{{Section
| |
| − | |sectionHeading=PureCloud Provisioning Steps
| |
| − | |Type=Unstructured
| |
| − | |freetext=Perform the following steps using the PureCloud Admin UI or the PureCloud API.
| |
| − | <ol>
| |
| − | <li>As necessary, for each on-premises service, create OAuth Client Credentials grants:
| |
| − | <ul>
| |
| − | <li>Using the UI, follow [https://help.mypurecloud.com/articles/create-an-oauth-client/ these steps],</li>
| |
| − | <li>Or using the API, reference [https://developer.mypurecloud.com/api/rest/v2/oauth/ these endpoints].</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 your SAML Cert and key. Certificate is base64 string created from PEM file by using this command:<br>
| |
| − | <source lang="text">
| |
| − | openssl base64 -in cert.pem -out result _file_name
| |
| − | </source>
| |
| − | Pkey is also based64 string but requires additional command to create encrypted private key:<br>
| |
| − | <source lang="text">
| |
| − | openssl pkcs8 -topk8 -inform PEM -outform PEM -in saml.pem -out <span>key.pem</span> -nocrypt
| |
| − | | |
| − | openssl rsa -in key.pem -out key_protected.pem -aes256openssl base64 -in key_protected.pem -out result _file_name
| |
| − | </source>
| |
| − | Once you have created the two PEM files perform the following steps:
| |
| − | <ul>
| |
| − | <li>Encode saml.pem into a base64 string (=>’saml.pem.b64’) using this command:
| |
| − | <source lang="text">
| |
| − | openssl base64 -in saml.pem -out saml.pem.b64
| |
| − | </source>
| |
| − | </li>
| |
| − | <li>Encrypt the saml.pkcs using a password (=>’saml.pkcs.enc.password’) and then encode the resulting content into a base64 string (=>’saml.pkcs.enc.b64’) using this command:
| |
| − | <source lang="text">
| |
| − | openssl rsa -in saml.pkcs8 -out saml.pkcs8.enc -aes256
| |
| − | </source>
| |
| − | (specify the value of saml.pkcs.enc.password when prompted)
| |
| − | <source lang="text">
| |
| − | openssl base64 -in saml.pkcs8.enc -out saml.pkcs8.enc.b64
| |
| − | </source>
| |
| − | </li>
| |
| − | </ul>
| |
| − | </li>
| |
| − | <li>Create a PureEngage Identity Provider (IDP). You can use the Identity Provider API via the PureCloud Developer Tools, SDKs, or Platform API.<br>
| |
| − | Sample Request:<br>
| |
| − | <source lang="text">
| |
| − | PUT https://api.{{environment}}/api/v2/identityproviders/pureengage
| |
| − |
| |
| − | {
| |
| − | "name": "PureEngage",
| |
| − | "autoProvisionUsers": true,
| |
| − | "certificate": "-----INSERT CERTIFICATE GENERATED IN STEP 2-----",
| |
| − | "issuerURI": "http://www.genesys.com/pureengage",
| |
| − | "ssoTargetURI": "http://example.com/target",
| |
| − | "disabled": false
| |
| − | }
| |
| − | </source>
| |
| − | <ul>
| |
| − | <li>[https://developer.mypurecloud.com/developer-tools/#/api-explorer Developer Tools]<br>
| |
| − | [[File:Hybrid_Identity_Provider_Tools_PureEngage.png|500px]]
| |
| − | </li>
| |
| − | <li>[https://developer.mypurecloud.com/api/rest/client-libraries/ SDKs]<br>
| |
| − | [[File:Hybrid_Identity_Provider_SDK_PureEngage.png|500px]]
| |
| − | <ul>
| |
| − | <li>[https://developer.mypurecloud.com/api/rest/client-libraries/java/IdentityProviderApi.html Java]</li>
| |
| − | <li>[https://developer.mypurecloud.com/api/rest/client-libraries/dotnet/IdentityProviderApi.html .NET]</li>
| |
| − | <li>[https://developer.mypurecloud.com/api/rest/client-libraries/python/IdentityProviderApi.html Python]</li>
| |
| − | </ul>
| |
| − | </li>
| |
| − | <li>[https://developer.mypurecloud.com/api/rest/v2/identityprovider/ Platform APIs]<br>
| |
| − | [[File:Hybrid_Identity_Provider_API_PureEngage.png|500px]]
| |
| − | </li>
| |
| − | </ul>
| |
| − | Troubleshooting:
| |
| − | <ul>
| |
| − | <li>Ensure that the IDP is set with "autoProvisionUsers" = "true"</li>
| |
| − | <li>Ensure that the issuer URI in your SAML assertion is the same as the issuer URI for the IDP.</li>
| |
| − | <li>Ensure that you don't have multiple issuers with the same URI.</li>
| |
| − | </ul>
| |
| − | </li>
| |
| − | <li>Create SAML Response Assertion to automatically provision users with the desired role in PureCloud. The following is sample code. Do not copy/paste this code. You must populate the code with the values particular to your organization:<br>
| |
| − | <source lang="xml">
| |
| − | <?xml version="1.0" encoding="UTF-8"?>
| |
| − | <saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:xs="http://www.w3.org/2001/XMLSchema" ID="xxxxxxxx" IssueInstant="2019-02-08T18:18:43.979Z" Version="2.0">
| |
| − | <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">http://www.genesys.com/pureengage</saml2: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="#b4d16943-17a8-45ed-adfc-c3db20cadd75">
| |
| − | <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#">
| |
| − | <ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" PrefixList="xs"/>
| |
| − | </ds:Transform>
| |
| − | </ds:Transforms>
| |
| − | <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
| |
| − | <ds:DigestValue>EiF51HI9wRntjC+aJ1M/2/0LfFo=</ds:DigestValue>
| |
| − | </ds:Reference>
| |
| − | </ds:SignedInfo>
| |
| − | <ds:SignatureValue>xxxxx</ds:SignatureValue>
| |
| − | <ds:KeyInfo>
| |
| − | <ds:X509Data>
| |
| − | <ds:X509Certificate>xxxxx</ds:X509Certificate>
| |
| − | </ds:X509Data>
| |
| − | </ds:KeyInfo>
| |
| − | </ds:Signature>
| |
| − | <saml2p:Status>
| |
| − | <saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
| |
| − | </saml2p:Status>
| |
| − | <saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" ID="d87bb408-523d-496f-a65e-775f986b6813" IssueInstant="2019-02-08T18:18:43.976Z" Version="2.0">
| |
| − | <saml2:Issuer>http://www.genesys.com/pureengage</saml2:Issuer>
| |
| − | <saml2:Subject>
| |
| − | <saml2:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">chuckcustomer@example.com</saml2:NameID>
| |
| − | <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
| |
| − | <saml2:SubjectConfirmationData NotOnOrAfter="2019-02-09T18:18:43.969Z"/>
| |
| − | </saml2:SubjectConfirmation>
| |
| − | </saml2:Subject>
| |
| − | <saml2:AuthnStatement AuthnInstant="2019-02-08T18:18:42.870Z">
| |
| − | <saml2:AuthnContext>
| |
| − | <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef>
| |
| − | </saml2:AuthnContext>
| |
| − | </saml2:AuthnStatement>
| |
| − | <saml2:AttributeStatement>
| |
| − | <saml2:Attribute Name="OrganizationName">
| |
| − | <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">chuckcustomer</saml2:AttributeValue>
| |
| − | </saml2:Attribute>
| |
| − | </saml2:AttributeStatement>
| |
| − | </saml2:Assertion>
| |
| − | </source>
| |
| − | </li>
| |
| − | <li>By default, Altocloud permissions are included in the Admin and AI Agent roles. You may grant [https://help.mypurecloud.com/articles/altocloud-permissions-overview/ Altocloud permissions] to additional roles as needed.
| |
| − | </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 '''Script''' folder of the '''Environment''' tenant.
| |
| − | <ul>
| |
| − | <!--<li>Usage characteristics: the transaction object should be acquired at start-up and used until the component gets an error from a given API call. If an error occurs, your component should retrieve the hybrid_integration object from config server and try again. If the component still has problems, your component should end the associated processing with an error.</li>-->
| |
| − | <li>Tenant characteristics:
| |
| − | <ul>
| |
| − | <li>'''Single tenant deployment''': If your PureEngage deployment is ''not'' multi-tenant, the transaction object should be put under the '''Environment''' 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.</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'''. If you want to provision agents with a different role, you must do so in the SAML assertion that provisions the user (see IDP...). </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>. <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>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 (a base64 saml.pem PEM encoded key).</li>
| |
| − | <li>'''pkey''': The encrypted SAML related certificate private key (a saml.pkcs8 private key encrypted in aes256 with a password (see password option below) and encoded in base64). You must encrypt the private key with a password that you create before you store the key in Config Server.</li>
| |
| − | <li>'''password''': The password to decrypt the private key. You must store the password in the '''password''' option. You can use OpenSSL to perform the encryption with your password</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>
| |
| − | The resulting material can be set in the saml section of the transaction object:
| |
| − | <ul>
| |
| − | <li>certificate=<saml.pem.b64></li>
| |
| − | <li>pkey=<saml.pkcs.enc.b64></li>
| |
| − | <li>password=<saml.pkcs.enc.password></li>
| |
| − | </ul>
| |
| − | To allow for better control and monitoring of the components using PureCloud Services, for each PureEngage Service that uses a common service you must create multiple sections, one for each OAuth client, in Configuration Server 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.<br />
| |
| − | Genesys recommends that you consult architecture before performing this step.
| |
| − | <br />
| |
| − | Create the following two options in each section:
| |
| − | <ul>
| |
| − | <li>'''client_id''': The Client Credential Grant Client ID.</li>
| |
| − | <li>'''password''': The Client Credential Grant Client secret.</li>
| |
| − | </ul>
| |
| − | For example:
| |
| − | <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):
| |
| − | <ul>
| |
| − | <li>'''client_id'''</li>
| |
| − | <li>'''password'''</li>
| |
| − | </ul>
| |
| − | </li>
| |
| − | <li>For each Service or component using a Genesys API, such as 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'''</li>
| |
| − | <li>'''password'''</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
| |
| − | }}
| |
| − | }}
| |
