Multi-Tenant Authentication for Success Centers

PLEASE NOTE: It's very important to understand the authentication URL structure of your app. There is no specific way to handle tenants or authentication in a web app. We recommend collaborating with your internal technical resources to identify the key patterns and identifiers you'll need to use this feature. 

What is Multi-Tenant Authentication?

Multi-tenant authentication allows you to create Success Center authentication endpoints that use contact and account merge fields. If your app is tenanted, and you have more than one auth endpoint, you can use merge field values to set a portion of the URL to match your app's authentication patterns. This allows for more flexibility during Success Center authentication.

• Merge Field Resolution
• Usable Merge Fields
• Multi-Tenant Authentication Process

Merge Field Resolution: 

We break down auth URLs for merge field processing into three sections: 

• Domain: Domains are not case-sensitive, and can include any custom field. 
  • Characters that are not [a-z], [0-9], [.], or [-] are automatically removed in resolution.
  • Spaces: We will remove the space from values that include them. For example, the unresolved URL https://[[account.cfCompanyName}}.myapp.com, where account.cfCompanyName = "My Company", would become https://MyCompany.myapp.com. 
  • HTML: Any HTML inside of a custom field value will be removed. For example, the unresolved URL https://[[account.cf.htmlvalue}}.myapp.com, where the value of htmlvalue is <p>MyCompany<p>,  would become https://MyCompany.myapp.com. 
  • Protocols: https://, http://, and // are valid domain protocols. Whatever protocol is at the beginning of a URL will be kept at the beginning of the merged URL. 
• Path: No characters are removed. Paths can be case-sensitive, and we do not currently convert path casing. 
• Query: The only parts of a query string that ChurnZero will change are the merge field values. If you add a hardcoded value with characters that need to be encoded, we will not encode those characters: 
  

  //customer auth endpoint TCI (with hardcoded param values)
  https://auth.myapp.com/?company={{account.name}}&category=SomeThing
  
  //if account.name = 'My Company', the resolved URL is:
  https://auth.myapp.com/?company=My%20Company&category=SomeThing

If we cannot parse a URL before the merge fields are resolved, we will try to resolve and apply encoding or merge field mutations. For example, if you are trying to use one or more mergeFields to resolve a full domain: 

//their TCI value might look like this: 
{{account.cf.mydomain}} 

//if account.cf.mydomain = https://auth.myapp.com/sso, the resolved URL will be: 
https://auth.myapp.com/sso

If a URL contains {{}} after merge fields have been resolved, it will not be considered broken, and not valid. We will check the validity of the URL once the merge fields are resolved.

PLEASE NOTE: Success Centers with an invalid auth URL will not be displayed, but users can still see and click on the launch avatar. If the user clicks on the avatar, the success center will display a generic error message. Resolved URLs will be cached for thirty minutes. The cache is cleared when you update the auth URL in your Success Center configuration. 

Usable Merge Fields

Merge field query endpoints will pull in all possible merge field results. Therefore, we do filter out some merge fields to limit any superfluous results. This makes some fields unavailable. 

Available Fields: 

• ALL base account and contact fields such as name, address, etc
• ALL account and contact custom fields

Unavailable Fields: 

• Account role fields
• Survey response (contact)
• Nested fields (ex: contact.account..)

Authentication Process

Let's say you want to start using multi-tenant authentication for your success centers. In this example, your app is called "Beagle App" and uses the URL "bgl-app.com"

Working with your technical lead, you learn that ChurnZero is "tenanted" in your app, so each account uses a specific subdomain for contacts to sign in. For example, you look at two accounts, "Treats Plus" and "Bwldr."

• Treats Plus uses the URL "treats-plus.bgl-app.com"
• Bwldr uses the URL "bwldr.bgl-app.com"

In these cases, we'd call "treats-plus" and "bwldr" the "tenant identifier.". (ex: [tenant identifier].bgl-app.com.) It's up to you to determine how that identifier is stored in ChurnZero for each account or contact.

To get started with multi-tenant authentication: 

1. Add an account custom text field in ChurnZero called "Tenant Subdomain."
2. Technical lead performs a bulk update with an additional field for "Tenant Subdomain" in the CRM. This bulk update is then mapped and imported to the custom "Tenant Subdomain" field in each account.
3. In your success center, click the cog icon at the top right of your screen. In the Success Center Authentication window that appears, add https://{{account.cf.tenantsubdomain}}.bgl-app.com/sso as the auth URL endpoint.
   
4. When future accounts are added,  include the "Tenant Subdomain" field in the CRM. This ensures that the new accounts have a value for "Tenant Subdomain" when synced to ChurnZero.
5. You can then implement Success Centers across multiple tenants.