What makes a good SaaS API (from an IT Management perspective)?
Apr 13 | 7 mins read
SaaS applications are at the forefront of digitalization initiatives. They put business users in the driving seat, allowing them to directly test and buy products that meet their needs. Business users might be buying, but IT teams are ultimately responsible for governance and information security best practices. IT personnel bear the brunt of applying policies as best they can to an ever-increasing number of SaaS applications. At this scale, routine tasks like creating user accounts or analyzing licensing information are very time-consuming unless there’s an element of automation involved, preferably through an API. SaaS APIs often focus on functional areas of the product rather than management aspects. This article looks at what API end-points matter from an IT management perspective. IT buyers can use this as a guide to the API functionality to look for when procuring SaaS applications, and vendors can better understand how they can help IT managers by implementing solid management APIs.
It might not be the most modern or fancy API, but the good news is that SAML2 support is now widespread across the industry. Identity Providers (IdPs) like Okta and Azure AD list well over 1,000 SaaS applications that support SAML2. SAML makes life easier for users by cutting out individual application passwords, significantly reducing concerns for IT teams around password reuse between applications or weak passwords.
While SAML doesn’t directly support user management, two subtle ways an application implements SAML can make a big difference to IT teams:
- Applications can choose what to do if an IdP presents a new user that the application hasn’t seen before. By supporting “just-in-time” user provisioning (automatically creating a basic user account when the IdP presents a new user), the IT burden is reduced to modifying permissions.
- When SSO is enabled, an application should offer the ability to prevent conventional username/password logins (sometimes known as “big bang SAML enablement”). This means that IT teams can immediately respond by removing a user’s access in the IdP when a user leaves the organization. The user will be unable to circumvent the IdP by logging in with application-specific credentials. While it’s a best practice to deactivate the user account in each application, having a centralized way to quickly block access is an adequate backstop.
Account Management and SCIM2
The SCIM protocol is the industry-standard mechanism for provisioning and de-provisioning user accounts in SaaS products. Applications can choose how much of the SCIM specification to implement, but even a basic subset of SCIM provides a much more direct and comprehensive way to manage user accounts than relying on SAML. SCIM’s standard REST API endpoints let an IdP enumerate all user accounts, create or update user profiles, and assign them to security groups.
Compared to relying on a specific SSO implementation, SCIM offers a much more standardized way to provision and de-provision access. SCIM isn’t awfully demanding as far as protocols go, but IdP application catalogs indicate only around 20% of applications that support SAML also support SCIM. This figure is growing but still shows a big gap.
For vendors daunted by the full specification, it’s worth being pragmatic. In deciding what to implement, consider what SCIM functions the major IdPs utilize. These mostly consist of only basic filter functions — rarely do they touch on the more complex bulk update section of the SCIM specification.
Basic User Data Management
If SCIM isn’t supported, then APIs may offer their own mechanisms for user management. At the simplest level, many SaaS products have an endpoint to extract a list of current users. Some will also have endpoints to create or amend user accounts. Although these might not be supported by an IdP and may require custom scripts writing, it at least offers a way to automate some user management aspects.
Privileged User Accounts
An important element of regular User Access Reviews is focusing attention on privileged accounts. While membership of a group named “Admins” implies privileged access, this isn’t a very robust way to determine whether a group or role is privileged — especially if an application lets you create your own roles.
Some APIs will allow you to enumerate custom roles, and list their capabilities, which will give you a way to decide whether or not a role is privileged programmatically. DocuSign is a good example. At a simpler level, an API may return a field against a user account such as
From a cost optimization viewpoint, an API needs to return whether a user is actively accessing the application and the sort of license they have. This will give you a clear way to understand whether to deprovision or down-grade a user.
Only a subset of APIs that return a list of users will also return information like the last login date that indicates user activity. However, if users are authenticating through an IdP using SAML, this is less of an issue, as you can normally source this information from the IdP.
Either way, if you want to optimize usage efficiently, the application must provide an API that specifies each user’s license plan. For some applications, you need to understand usage patterns more deeply to know whether a user can be deprovisioned. The classic example here is Zoom, where a user may be logging infrequently and have a paid seat, but this might unnecessary if they’re not running any meetings over 40 minutes in length with more than two attendees (the rule for a paid seat). Specific application knowledge and potentially deeper analysis are needed to truly automate account optimization.
Sticking with financial themes, it may be useful for an IT team to retrieve invoicing and payment information. This lets you track actual amounts spent without having to request reports from the finance team. This could be helpful if IT teams are internally cross-charging access to applications to different departments, based on usage, also known as chargeback.
Audit logs are a mainstay of proper information security management, but it’s no longer sufficient to have a searchable web-page or a manual CSV export.
IT teams are increasingly feeding audit data to SIEM tools, which allow for automated breach detection and detailed incident analysis. Therefore, SIEM tools need some kind of API to pull data from an audit log. Ideally, the audit log will contain the basics of timestamp, actor, entity acted upon, and the actor’s IP address.
Be aware that SIEM tools may not support accessing the application API directly, so you may need to create a script to poll for audit log data and write it to a file, which can then be processed by
logstash, or some other SIEM log ingestion tool. For example, salesforce lets you easily retrieve a list of event log files and download them individually as CSV.
Standardizing audit event APIs, potentially as a SCIM extension, would be a positive move for the SaaS application industry.
API Authentication and Authorization
APIs typically offer either an API key or OAuth2 support for authentication and authorization. API keys are simple to understand and implement, but come with significant downsides: they’re often tied to admin accounts and can provide API clients with full administrative access.
Well-implemented OAuth2 support will let you limit precisely what access “scopes” will be granted to clients. Scopes are definitely preferable as they limit the data exposed. If you’re writing scripts to connect via OAuth2, if the application offers the Client Credentials flow, it will make your life easier as it’s simple to implement. Authorization Code flow, however, offers a more straightforward end-user experience in connecting to an API.
Either approach will mean that you get a short-lived access token, which can be refreshed or regenerated. This gives you the peace of mind that credentials aren’t being sent with every request (as they are with an API key), and the access token has a limited life if it leaks.
A leaked API key is more significant since it’s inherently long-lived until you rotate it. Manually rotating API keys can be awkward if multiple scripts use the same API key, so OAuth2 is definitely a more robust approach.
A Final Word on Costs
SaaS application vendors are increasingly aware of the value that IT teams place on good management APIs.
Unfortunately, vendors also see this as an easy way to pressure companies to pay for more expensive plans by restricting SAML or SCIM support to premium price points. Some vendors even restrict audit log access unless you’re on a costly enterprise-level plan. Check the plan feature matrix carefully when you’re selecting software.
When negotiating contracts, it’s worth pushing for something basic like SAML to be thrown-in at a lower price point, especially if you don’t need other features included in a premium plan. For vendors reading this, consider that easing access will more likely increase your products’ usage: offering SAML out of the box could be a smart commercial move.
The article was originally published by Nordic APIs, you can find it, along with many other great articles on APIs here.