Recently, we’ve spent some time digging into frameworks and best practices for your API auth needs. Absorbing that much detail and theory can be overwhelming. I met up with Daniel White, a Senior Software Engineer at Stoplight, to get some on-the-ground perspective.
White is fairly new to Stoplight, but he has had many years of experience as a backend developer. He worked most recently at a MAANG company, where he got a valuable perspective on scalability and maintainability. In our conversation, he repeatedly emphasized how important it is to take a design-first approach to API auth practices. A design-first approach means looking at auth as a core feature of your API product, considering how decisions around auth will integrate with other product features and shape developer experience.
There is no one right answer to your team’s questions about auth practices, but asking the right questions at the start can help you design better solutions. Prioritizing your auth needs now will make for a more scalable, reliable system down the road.
Start Planning for API Security on Day One
In White’s experience, the most costly mistake API developers make around authentication and authorization is waiting too long to think about it. API teams have a lot of choices to make—OIDC? SAML? OAuth?—but White doesn’t think the exact technologies you choose are nearly as important as ensuring you build in some kind of auth practice from the start, putting authentication “at the forefront of your design.”
A proactive approach doesn’t mean deciding every detail in advance, but including some basic infrastructure now can help prevent serious delays later. White described a project where the previous team he was on waited until six months into development to begin building an auth solution, at a significant cost: “We had all these services that slammed to a halt. If the standard is not there, then no one’s going to write to it, and what we found was that adding auth was a breaking change at that point.”
Your planning should take into account your long-term goals for your product. Design-first approaches are meant to create sustainable architectures that can grow in scale without growing too much complexity. That’s especially important for anything related to security, where “complex” can sometimes be a synonym for “vulnerable.”
Rather than starting with a boilerplate approach and making exceptions and adjustments as you build, White suggests that API designers should be “designing with the right access levels in mind” from the beginning. That means separating public and private resources and considering edge cases like machine authentication early in your design process.
Draw on Existing Resources
Most API product teams have expertise in a range of areas, but security may not be one of them. Acknowledging that the knowledge gap is not a weakness—it’s an opportunity to leverage the strengths of others.
If your API teams need more security expertise, you might consider creating partner relationships with security engineers, either in a working group or a consulting relationship. White described a collaborative approach where a security engineer plays a consultative role for an API team, reviewing designs, asking questions, and explaining tradeoffs. In his experience, the positive peer-to-peer communication in that model “pays dividends for security, because you have access to this special understanding of how attackers think and work.” A working group that includes security staff can help you take a more expansive view of your design needs so that you can anticipate edge cases earlier in the process and understand the cross-functional implications of auth decisions.
Your API teams should also take advantage of the wealth of expertise outside your organization by adopting industry best practices. White encourages API teams to “do your due diligence” and choose tools and standards that are proven and trusted. There are never any guarantees, but building on existing infrastructure is a more reliable approach than trying “to be bespoke” or “reinventing a law,” according to White. When you use a widely-adopted open-source standard, you benefit from a huge community of users and contributors who are continually evaluating the standard and integrating hard-won knowledge.
Web security is a public good, and the pooled resources behind standards like SAML and OAuth are the work of some of the most talented, motivated, and ethical developers in the technology industry. Taking advantage of their work will help you keep your own auth practices current and proactive. You’ll also have an easier time onboarding new developers and users, who will be familiar with these standards, and you’ll be ready to integrate with other applications that have made the same choices. Of course, industry standards are not perfect, but tools developed by highly trusted companies are likely to be easier to implement and maintain over time, even as technology evolves.
Make Choices You Can Live With
The best auth practice is one you’ll stick with. Inevitably, you’re going to have to make some trade-offs and compromises—those need to be choices your organization is comfortable supporting, especially because it will need to invest resources in ongoing maintenance.
No auth system is going to be entirely self-sustaining, but different choices will require different resources over the long term. White repeatedly emphasized maintainability during our conversation – with every choice, you are creating a solution but also a maintenance commitment. He made a distinction between the clear-cut work of supporting documented processes, and the hard-to-quantify burden of constant vigilance – maintaining the first is usually a better choice.
As an example, White talked about duplicate API endpoints. One line of thinking says that supporting both a public and private version of the same endpoint is duplicative and creates unnecessary work. But to White, this is a false economy: “I can see the view that it’s just another endpoint to maintain. But I think the cost of maintaining the mental awareness of what should be where is much more challenging.” White’s view is that it’s far easier to automate and streamline processes for endpoint management than it is to ensure that all API stakeholders remain vigilant – to the right risks – indefinitely.
Another choice that has a maintainability impact is whether you use roles-based or another more resource-intensive approach. Roles-based auth is well-suited to monolithic applications, but isn’t flexible enough for microservices or more complex API products – solutions include claims-based, policy-based, and resource-based auth, all of which require much more backend logic and more frequent requests to an auth server. White’s experience at a very large company helped him see the cost commitment involved in these types of policies. If your API authorization policies rely on “very picky resource-level validation,” he says, this will generate a lot of traffic to your auth servers that will scale rapidly as your number of API consumers grows. By separating resources for public and internal API consumers, you can enable roles-based auth, reducing the complexity and volume of calls to your auth servers.
Ideally, the design of your API auth services will outlast the engineers who implement it. Sound design and maintenance practices will include planning for that transition with good documentation, governance tools, and consistent implementations. White also emphasized the role of culture and mindset, and how valuable collaboration and open communication are for better API security.
If you’re going to define a solution that works for your organization, you will need to understand how it affects different aspects of your API program. Design-first approaches take a comprehensive view of your API as a product, including auth needs. Careful listening and collaboration will help you build a solution with endurance.
Stoplight Is Becoming What We’re Trying To Serve
White had a lot of praise for Stoplight’s internal commitment to collaboration and continual improvement and spoke about how it helped facilitate better security solutions. As we said above, the best auth practice is one you will stick with, and you’re much more likely to achieve that if you are getting buy-in from the start. Being new to the company, he has had the opportunity to ask a lot of questions and offer a new perspective, and he has been happy to find doors open:
“One thing I love about Stoplight is the cross-team collaboration. Anything you can do to lower silos is going to help breed confidence that everyone’s views are being heard. Not everyone is going to have the same concerns, and when you have collaboration, you can standardize on something that people agree on.”
That’s not to say Stoplight has arrived at perfection. White recognizes that the company is currently very “human-focused”, and his prior experience has taught him that anticipating a move toward more automation may be in the cards for the future. Ultimately, he sees that Stoplight is in the same boat as many of our customers: “Stoplight is becoming what we’re trying to serve. We’re running into those same kinds of questions like, ‘How do we do this better? How do we do that at scale?’”
White’s answer—one that the Stoplight team can get behind—is that there isn’t a single right answer. The key to creating the most effective auth practices for your API product is collaborative planning. Design-first thinking is an approach that can pay dividends throughout your API lifecycle.
For more on auth strategy, check out our first two blogs in the series:
