Authentication for ChurnZero Success Centers

Authentication ensures you have explicit control over who can access a Success Center and view its content. 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. You can use cookies or tokens to authenticate your users. 

For more information on how to implement Success Centers if you have different domains for each account, see Multi-Tenant Authentication for Success Centers.

Required Information

To complete Success Center authentication, you will need to get some information from ChurnZero first.

1. Go to In-App Tools > Success Centers, then open the Success Center Authentication settings using the gear button in the upper right. Under the Authentication Endpoints, retrieve:

   1. Success Center Contact Lookup

   2. Success Center AuthCallBack

2. In the Admin, go to Data > Application Keys. Create an application key, or copy an existing one, that you intend to use for authentication.

Configuration Overview

Once you have your application key, Success Center Contact Lookup URL, and Success Center AuthCallBack URL, there are two steps to configure token-based authentication.

1. First, configure your Authentication URL. This is the URL where contacts will be redirected to for authentication and where you will call the Success Center Contact Lookup URL to retrieve an auth-token for the contact.

2. Once your Authentication URL is configured, within ChurnZero go to In-App Tools > Success Centers and click on gear button in the upper right to open Success Center Authentication. Under Configuration Information, fill out two pieces of information:

   1. Authentication URL

   2. 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}

Authenticating the User

Depending on the authentication method used in your application, you may choose from one of the two methods below.

Cookie Authentication

If you use a cookie to authenticate your users, no further action is required. When ChurnZero redirects to your Authentication URL, the cookie you include will be present.

Token Authentication

If you use bearer tokens, you will need to use the snippet below prior to calling ChurnZero.push(['setContact', ...]) to ensure that the token can be included with the redirect to your Authentication URL. ChurnZero will serialize the object returned from the provided function into query parameters on redirect. You can then accept the query parameters on your authentication URL to verify the user's token.

ChurnZero.push(['setAuth', () => ({
	"parameterName": "tokenValue"
})]);

// This will cause ChurnZero to redirect to the following during the authentication flow
// <https://your-authentication-url?parameterName=tokenValue>

Retrieving an Auth Token for a Contact

You will need:

• Your AppKey

• 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 found in the configuration modal. (See Configuration Overview above for where to find that.)

An example HTTP request would be:

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.

An example redirect URL would be: https://your-churnzero-vanity-url/SuccessCenterCallback?token={url_encoded_auth_token}&next={next_query_string_parameter}