Although it’s hard to do justice to the topic of API security in the space of a blog post, the topic is important because it affects every API architect creating a new web service. Advice that has come from experience may be of particular value—and that’s what follows here.
At DocuSign, we take great steps to protect the API because the type and volume of data we deal in demands it. We process thousands of electronic signatures every hour and to-date have served nearly 6,000,000 customers. No matter the scale of your solution, developers and systems integrators should take the following five considerations into account when designing a web service architecture.
1. Consider the sensitivity of your data.
Are you giving a view into publicly available data, or would a breach jeopardize personal information?
DocuSign handles people’s most sensitive information so we only allow someone to access data with a secure protocol. Some transactions, like transferring financial documents out of our system and into a different vault, require API clients to:
- Use an X.509 cert XML signature on the SOAP call
- Provide an Integrator’s Key
- Provide account credentials
- Go through the SSL channel without exception
As you can imagine, many developers find these security requirements challenging. Some web services don’t require XML Signature which makes implementation easier.
Since our customers range from an individual real estate agent to a multi-national bank, our system design is flexible to meet the needs of any size business and security requirements. Be sure to understand your customers’ needs and requirements up front so you build the right solution from the start.
2. Keep intentional and unintentional attacks in mind.
Your system should protect itself from both intentional and unintentional attacks. DocuSign maintains separate platforms for developers (https://demo.docusign.net) and production customers (https://www.docusign.net) to prevent unintended consequences of development from spilling over to our production customers. Only after undergoing a review process we call “certification” do apps get access to our production datacenter.
Basic things like ensuring access controls, revoking passwords after X number of attempts and checking handles have stopped many breaches. Most “attacks” were actually not malicious. One frequent error is when someone uses a wrong password in their web service calls.
Be mindful of these situations. Does someone need to call your phone support after X number of retries? Should the account lockout expire after some time? Are people getting enough information in an exception or error code to fix their unintentional problems? Hopefully the answer to the last question is “Yes”.
A helpful error:
“Due to unsuccessful login attempts your account has been locked out for X minutes”
A less helpful error:
“Your account is locked out”
The first one enables your customer to figure out how to remedy the situation and not get locked out again. The second error may generate a support call.
3. Set resource limits.
Introduction of Cloud or SaaS applications didn’t change the fact that you still need memory, disk, network bandwidth and CPU time for computing. In reality, most Cloud services do not expose CPU, Disk Utilization or anything else to their customers. Frankly, most don’t want to worry about it since they can’t do much about it anyway.
One bad tenant in a multi tenant solution can abuse your system and potentially spoil the experience for everyone else. Give people some way to measure their performance and consume a reasonable amount of resources. The system needs to protect itself from runaway threads, endless loops and request floods. Most commercial web services introduce a rate limit for API calls. Some examples include:
Twitter Rate Limits: http://dev.twitter.com/pages/rate-limiting
Amazon API Limits: https://affiliate-program.amazon.com/gp/advertising/api/detail/main.html
The limits must be simple, reasonable and meterable by the consumer of the web service. At DocuSign, we introduced a limit of 1,000 web service calls per account per hour. It was simple to communicate, and our studies show that only a few customers have exceeded it. For those rare exceptions, DocuSign worked with these developers to ensure more effective and efficient API calls.
4. Remember: whatever your rate limits, someone will exceed them.
That’s a good thing for a subscription service, since it means that someone is sending you a lot of business. At DocuSign, we have set a default rate limit and allow several large enterprise accounts to have a higher limit.
Why introduce a rate limit if you grant exceptions? Because with a self-service system for 98% of your customer base, this reserves some flexibility for special cases, and you can benefit from a scalable mechanism.
5. Use accepted protocols that potential customers are comfortable with.
If your security protocols or resource allocation is overly complicated, it won’t be broadly adopted.
When selecting an authentication protocol, look at the leading languages and technology stacks and see if the developers have the libraries and code samples to work with your web service. Make sure your services are easily consumable in .NET, PHP, Java, Ruby and Python. If your market tends to use a special language, check that out, too.
At DocuSign, we maintain an SDK with 5 different development languages: C#, Java, PHP, Ruby and ApexCode. We make sure that we can implement web service calls in those languages before we ask our customers to do so, to ensure we will be able to serve our customers’ needs.
When you leverage these five tips to develop your API, you put your solution in a position to succeed. Addressing and planning for security issues well before your API becomes popular is smart—and much easier than the alternative. No one likes to go back and re-implement a working solution to comply with a new security guideline. It’s worth the effort to do it right the first time.