In addition to the ChurnZero JavaScript requirement for In-App functionality, the ChurnZero Success Centers feature requires token-based authentication to ensure you have explicit control over who can access a Success Center and view its content. This authentication means that when a Contact (i.e. one of your users) attempts to open a Success Center, ChurnZero will reach out to an endpoint controlled by you and request validation that the Success Center can be shown for that Contact. Access by that specific Contact is confirmed through a single-use token.
For more information on MULTI-TENANT AUTHENTICATION, see: Multi-Tenant Authentication for Success Centers.
Required Information
To complete Success Center Authentication, you’ll need to collect a few pieces of information from ChurnZero.
-
In the Admin space, go to Data > Application Keys. Copy the AppKey that you want to use for authentication.
-
Go to In-App Tools > Success Centers, then open the “Success Center Authentication” setting in the upper right. From the “Authentication Endpoints” section of this dialog, retrieve:
-
Success Center Contact Lookup URL
-
Success Center AuthCallBack URL
-
Configuration Overview
Once you have your AppKey, Success Center Contact Lookup URL, and Success Center AuthCallBack URL, there are two steps to configure token-based authentication.
-
First, configure your Authentication URL. This is the URL where Contacts will be re-directed to for authentication and where you will call the Success Center Contact Lookup URL to retrieve an auth-token for the contact.
-
Once your Authentication URL is configured, within ChurnZero go to In-App Tools > Success Centers and open the “Success Center Authentication” setting in the upper right. Within this dialog, fill out two pieces of information:
-
Endpoint URL
-
Hash Secret
-
Configuration Detail
Authentication URL
The Authentication URL is a URL within your system that handles authentication requests. Your Authentication URL will need to authenticate the Contact, retrieve a single-use auth-token from the Success Center Contact Lookup URL, and then redirect the contact back to the ChurnZero Success Center AuthCallback URL with the "next" querystring parameter that was passed in and the auth-token.
For example, a Contact attempts to view a Success Center:
/successcenter/{successcenter-public-key}
The Contact will be redirected to your authentication URL:
Response: HTTP 302
Location: https://your-domain/authentication-url?next={successcenter-public-key}
Your Authentication URL then validates the Contact, retrieves an auth-token via the ChurnZero Success Center Contact Lookup URL as described below, and then redirects the Contact to the ChurnZero Success Center AuthCallback URL:
Response: HTTP 302
Location: https://your-churnzero-vanity-url/SuccessCenterCallback?token={retrieved-auth-token}&next={successcenter-public-key}
NOTE: The Success Center and its content is added to your application’s page via an HTML iframe element. ChurnZero sets the src attribute of this iframe to a dynamic URL. The {successcenter-public-key} is a generated string of characters that is a piece of this dynamic URL. This dynamic URL is created and manipulated solely by ChurnZero.
The {successcenter-public-key} is not something that your developers need to create or provide during setup. This URL query parameter is created and managed exclusively by ChurnZero. No action is required from you or your development team.
Retrieving an Auth Token for a Contact
You will need:
- Your App Key
- Your Success Center Contact Lookup URL
- The AccountExternalId for the Contact
- The ContactExternalId for the Contact
You'll be making a POST request to the SuccessCenterContactLookup URL with the following HTTP information:
1) Request Body (application/json) with the following shape
{"appKey":"<your-app-key>","accountExternalId":"<account-external-id>","contactExternalId":"<contact-external-id>"}
2) X-Signature Header
This header's value will be an HMAC (SHA256 hash) with a message of the request body from above and a secret of your Hash Secret mentioned in section 2.2
For more information on generating HMACs see the "How do I generate HMACs?" article.
Example HTTP Request
POST https://your-churnzero-vanity-url/SuccessCenterContactLookup HTTP/1.1
X-Signature: <HMAC_FROM_ABOVE>
Content-Type: application/json
{"appKey":"<your-app-key>","accountExternalId":"<account-external-id>","contactExternalId":"<contact-external-id>"}
Redirecting to the SuccessCenterCallback URL
A successful response from the SuccessCenterContactLookup will contain JSON that has an authToken property:
{ "authToken": "<auth_token>" }
After receiving this response, you will 302 Redirect back to ChurnZero's SuccessCenterAuthCallback endpoint with a url encoded version of this auth token and the next query string parameter mentioned in the Authentication URL Section
Example Redirect URL
https://your-churnzero-vanity-url/SuccessCenterCallback?token={url_encoded_auth_token}&next={next_query_string_parameter}
Comments
4 comments
Updating SEO to make this easy to find form a search will be super helpful. Also not requiring to be logged in to view this page would help a ton.
Hello,
We already have implemented an authentication which authenticates the user using a cookie attached to the request. This works fine in Chrome and Firefox, we can see the success center and it’s content no problem.
However we have run into an issue with Safari. It seems Safari’s default privacy setting is to block third party cookies by default, so our cookie is not allowed to leave our domain and the authentication request fails. Therefore we can only use the success center in Safari if the user manually disables the setting ‘Prevent cross site tracking’ in the browser settings. Chrome and Firefox also have similar settings but they are disabled by default.
It seems this has been Safari’s policy since 2020: https://webkit.org/blog/10218/full-third-party-cookie-blocking-and-more/
And from what I have researched this seems to be the general direction in which the industry is moving. Chrome will also attempt to block third party tracking by the end of 2023: https://blog.google/products/chrome/updated-timeline-privacy-sandbox-milestones/
Is there any know workarounds for this? Or another form of authentication available?
Also, considering the policy changes in third party cookies, is there something in Churnzero’s roadmap to address this issue?
thanks
Hi,
Why I keep getting a error 401 Unauthorized when I access the SuccessCenterLookup. I'm sending the right app key, accountId and external Id. Also I'm using javascript integration and its working properly. But I dont have luck with this Success Center Page. Any help will be appreciated. Thank you
I've read the article and the authentication works, but I get the 401 too! I'm going to resort to witch craft next.
Please sign in to leave a comment.