Zapier docs: plain-english, useful content, and helpful visual cues

Welcome back to Zapier month here at All Things Auth!

This series includes all of the fun details that we gathered during our review of Zapier that we didn’t have nearly enough time to talk about during the Zapier screencast episode.

This is the final article in the Zapier series, so here is a quick recap in case you missed some of the earlier articles:

In this final article, I'm going to focus on some really awesome documentation that Zapier has available on their site. No, don't leave! Documentation might sound boring, but it's a really critical part of making sure that end-users like you and me have a pleasant user experience. Aren't you incredibly appreciative when the docs for a service answer your question quickly before you even have to reach out to the support team?!

That takes the skill and attention of the unsung heroes: technical writers.

Let’s get into it!

Everyone should present their privacy policy like this! Yes, everyone!!

The very first thing that I must highlight is the truly exceptional job that Zapier has done presenting their privacy policy.

Using a two column format, Zapier has gone out of their way to make sure that their Privacy Policy includes plain-english right next to the classic wall of legalese. That means that even us "normal" people can understand it! This gives me the warm fuzzies!

SUPER Excellent: Zapier presents their privacy policy in plain-english so that any of their users can read it and understand what information they are collecting and how they are using it. Literally everyone should present their privacy policies this way! Here are some extra stars just to convey my excitement: ⭐⭐⭐⭐⭐

Zapier uses the same approach for their Terms & Conditions too. Whoever over at Zapier decided to present these documents in plain-english deserves an award!

The Zapier privacy policy highlights that they do need to keep a copy of the credentials to any third party service that you integrate via a Zap. Behind the scenes, Zapier needs to log into your third party account so that it can execute whatever task you got bored with and decided to automate! Zapier does specifically say that they encrypt these credentials before storing them in the database, but that leaves many important questions unanswered about how that is actually implemented. The details here matter immensely. Luckily, Zapier already provides this information elsewhere on their site!

Improvement: Zapier should update the "Third-Party Service Integration" section of their privacy policy to link directly to the related technical details that are already defined on their Data Privacy page.

The Data Privacy page contains some other really important information. Let's take a quick look.

Data Privacy & Technical Details

I really like that Zapier breaks the Data Privacy page into a "High Level" section that most people can understand and a "Technical Details" section for tech folks like me.

The first bullet in the High Level summary makes the classic mistake of using the buzz-phrase "protected with bank-level encryption". Really, that doesn't mean anything. I understand that this section is intended for the non-technical audience, but best to just avoid that phrase entirely. Rewording from "Credentials that you use to connect your Accounts to Zapier are protected with bank-level encryption" to something like "Zapier follows industry wide best practices and encrypts the credentials to your third party accounts before they are stored in our database" should clearly convey the fact that they are doing the “right thing” here.

Improvement: Replace the buzz-phrase "protected with bank-level encryption" with something less offensive to tech folks.

Secure password storage

Zapier defines exactly how they securely store passwords, which follows the best practices outlined in NIST's guidance. However, they should consider increasing the iterations of their password hash, PBKDF2, from 10,000 to something higher since that is just the minimum recommended.

Good: Zapier is following NIST guidance on how to securely store account passwords in their database.

Secure storage of third party account credentials

Zapier addresses the fact that they encrypt credentials to third party accounts before storing them in their database. Though there are many more details here than in the Privacy Policy, there are still some unanswered questions. For example, Zapier says they are using AES encryption, but does not specify the mode (e.g. AES-GCM).

Encryption key management

Managing encryption keys is an important aspect of using encryption in any application. Zapier says that they are using a project called KeyCzar with default settings and that "a black box with hot keys that runs and houses our KeyCzar servers". That description isn't immediately useful to anyone not already familiar with that project, but a quick glance at the GitHub repo does raise some concerns. The KeyCzar project was last updated over 1 year ago on February 14th, 2017 and the README starts off with a grim message:

Important note: KeyCzar has some known security issues which may influence your decision to use it. See Known Security Issues.

Use of SHA 1 and 1024 bit DSA
Keyczar uses 1024 bit DSA keys with SHA1. Both of these are considered weak by current security standards. However, it is not trivial to upgrade without breaking backwards compatibility.

I have not used the KeyCzar personally and do not know enough about it nor Zapier's use of it to know whether it is a security issue, but it is definitely worth a review by their security team. It is also worth investigating AWS KMS, which is a fantastic solution for this specific use-case considering they are already running on AWS infrastructure.

Improvement: Zapier should more clearly explain their key management practices and investigate AWS KMS as a more standard solution.

TLS configuration

Zapier specifically states that they use TLS whenever they can, which is excellent, however not all TLS configurations are secure. Fortunately, Zapier is following all of the best practices!

Excellent: Zapier gets an A+ rating on SSL Labs, an industry go-to for rating TLS configurations.

Zapier should update this page to flaunt that fact that they have a secure TLS configuration!

Links to help docs right where you need them

There is nothing better than a well placed link to help documentation so that when I get stuck, I know right where to go for help.

Zapier places links to their help docs in a few key places that are worth highlighting.

The 2FA setup page includes a link to the 2FA help docs. This is great because most people do not know what 2FA is and even though they may have clicked through to start the setup process, having a link to documentation with more details will be very helpful for a large number of users who still have unanswered questions.

They also link to the docs from the confirmation email after enabling 2FA. Why is it useful here? Again, many users will be using 2FA for the first time. They might recall that they were sent an email after setting up 2FA initially and go back to that email for help in the future.

In the blog post announcing 2FA support, there are two direct links to the help docs. This is a great approach because the steps to enable 2FA may change over time, so pointing to the authoritative source means the blog post won't get outdated as quickly.

I've referenced the 2FA support documentation a few times, so let's take a closer look at that page specifically.

2FA help documentation page

The introduction on the 2FA help page does a really nice job explaining what 2FA is and why it provides additional security to the user's account.

It is important to remember that the intended audience is likely non-technical and may very well be interacting with 2FA for the first time. With that in mind, I like that they point out the abbreviations for two factor authentication right in the title. Sure, it's a simple thing, but the devil is in the details.

I particularly like this phrase: "even if someone stole your password, they would be unable to access your account without your mobile device." Though not technically an accurate statement, it does appropriately convey the intent of 2FA in this context given the intended audience. TOTP 2FA, the method supported by Zapier, does have its own vulnerabilities that I will explore in a separate article. Stay tuned!

I also like that Zapier makes it clear they highly recommend that users enable 2FA. As we saw in the 2FA Deep Dive article, Zapier walks the walk by doing a good job prompting users to enable 2FA. I will also point out (for the final time in this series, promise!) that they could likely improve adoption rates even further using contextual messaging.

Good: Zapier does a nice job explaining the benefit of 2FA for non-technical audiences.

The rest of the help doc answers specific questions about 2FA, including how to set it up, what to do if you lose your phone, dealing with recovery codes, etc. Each answer consists of a set of concise and to the point instructions. There is good use of direct links to where you need to go to get things done instead of explaining which menus to click, etc. A huge pet peeve of mine that is addressed nicely.

One of the things that initially caught my attention when reading the 2FA help docs for the first time was the use of visual cues for particularly important information.

Zapier uses a block quote with a red line along the left side. With the use of bold and italic fonts and a slightly different background color, these important notices jump off the page and can't be missed. Screen fatigue is a large problem, especially when I'm presented with a wall of text that contains key security related information somewhere within. Presentation details like this make a huge difference to quickly extract the key take aways!

Excellent: The use of stylized block quotes makes important information visually difficult to miss.

Throughout the 2FA help documentation, Zapier does a great job reiterating the importance of downloading recovery codes and keeping them somewhere safe. As I lamented in the 2FA Deep Dive article, I wish that Zapier would give more specific guidance for where users should store the recovery codes. These help docs would be a perfect place to include that guidance. Even though where to store them is an activity left to the reader, reiterating the importance of recovery codes many times throughout the help docs is a Good Thing. Repetition drives the point home.

It is oddly difficult to find the 2FA help docs without a direct link

On the Zapier Help page, there is a search box to assist users in finding useful support articles.

Oddly, a search for "two factor" does not include the Two-Factor Authentication (2FA, TFA) article at all in the first page of search results. It also does not appear in the results for "2FA", "two-factor", and "two factor authentication". A search for "TFA", the abbreviation in the title of the article, does not return any results at all...

Improvement: Zapier should verify that the main 2FA help article is included in the search index. If it already is included, figure out why it is not appearing in any of the search results.

I encountered another frustration on the help page that covers The Basics. In the left-hand column, I could not find a link to the main 2FA help article or other authentication related issues. I eventually discovered that I need to click the "Settings" link to bring up a help article that contains information corresponding to the live Settings page in my Zapier, such as password and other security settings. This is not very intuitive for users who are not intimately familiar with Zapier's organization.

Improvement: A top level link to help articles on important account security settings, including passwords and 2FA, would be a nice improvement.

Teams

Finally, I want to highlight the help page for Zapier Team Accounts.

It is fantastic that Zapier acknowledges that users are going to end up sharing a single account, even though that reduces their account security because they cannot enable 2FA. They also come right out and give direct answers to the questions before promoting Zapier for Teams.

Though Zapier for Teams does solve the problem of sharing a single account, it comes with a hefty price tag. As of this writing, plans start at $250/month.

There are tons of small teams that will not be able to afford the massive price jump from $0 to $250, but do have Zaps and other information worth keeping secure.

Improvement: Zapier should offer a realistic option to help smaller teams that cannot afford the high price tag of Zapier for Teams avoid sharing a single account.

As I mentioned in the Zapier screencast episode, I wish that there was a mid-level bare bones team account so that each user could have their own individual account login. The advanced team features that larger teams really need, such as Zaps with multiple steps and unlimited numbers of Zaps, could still be kept behind a paywall.

Wrap up

Overall, I am incredibly impressed with the Zapier documentation! While there are several improvements I'd make, it really feels like someone(s) put some serious thought into the content and presentation rather than throwing something together quickly.

The font is pleasant to read. They have great use of italics and bold to emphasize important points throughout the docs and utilize red colored block quotes to highlight particularly important information that users absolutely should not miss.

The documentation is also written in plain-english that is easy to understand and does not make the reader feel foolish for not already knowing the answer before looking it up.

Give Zapier some Twitter love for creating such awesome docs: Send them a tweet!

And thus comes the conclusion of our Zapier series! I hope you've enjoyed taking a look at how Zapier has tackled authentication and authorization challenges and learned something along the way that you can apply to your own service. If you are an end-user, hopefully you've learned how to better secure your Zapier account and common topics to explore on the other services you use too!

Share your feedback on this series so that we can improve future articles as we continue to feature more third party services in the future. Join the email list below so you don't miss future articles!


Lawery disclaimer: All Things Auth is not associated with Zapier in any way. We decided on our own to write this article because we like Zapier. All views expressed here are those of the author based on use of the public Zapier service only.

Thanks to Jordan Fischer for reading drafts of this.