How to securely deploy Postman at scale, part 1: user management

The Postman Team

June 8, 2022

Congratulations! You’ve got your team set up on a shiny new Postman API Platform account and now you’re ready to get ramped up. Or maybe you’ve been a long-time Postman user and are always on the lookout for best practices. Either way, it’s a good idea to carve out some time to figure out how you will keep your account and Postman data secure. Postman has always kept security as a top priority for our product and customers, and over the past few years, we’ve released several features to enhance the security experience.

In this two-part series of blog posts focused on securely deploying Postman at scale, we’ll share key recommendations from the Postman security and solutions engineering teams and provide a plan you can use to get your team up to speed with our security best practices.

Whether you’re a Postman team of five or 500, this series will help you be more confident in your ability to manage who has access to what on your Postman team.

The series will cover the following:

Part 1

• Managing teams both at the workspace and administrative levels
• Specialized roles for information management
• Account-level security features

Part 2

• Better practices for security-conscious developer workflows
• Tools for keeping tabs on information within your instance
• A checklist for your team to implement

Working together to protect information

Defining and enforcing access controls

While it’s critical that everyone working in Postman—from Developer to Administrator roles—follow the Postman shared responsibility principles, Postman also has safeguards in place and ways to formalize these responsibilities. These prevent the leakage of sensitive information.

User roles are available at the element (collections, APIs, etc.), workspace, and team level. Though it’s good practice that everyone at an organization understands how these roles work,  implementation of these features usually falls on project owners and team leaders. Let’s start with the most granular of these and work our way up:

Element and workspace-level roles

Each element in the Postman, whether a collection, API, mock server, monitor, or environment, has controls limiting who is allowed to interact with it. This helps teams have structure and control around who can make edits. On Professional and Enterprise plans, these element-level roles include Editor and Viewer:  Viewers cannot save their changes to a collection (encouraging forking of their own copy), and Editors are allowed to directly edit a collection. Similar, cumulative roles are present at the workspace level: Viewers can only send requests inside of a workspace, Editors can add and remove elements, and Admins can manage workspace members, roles, and details.

By assigning roles at the workspace level, Admins can set a default role for an individual or group that is inherited by all elements in the workspace, skipping the tedious task of assigning a user to every collection they might need. This functionality is made even more powerful by user groups, which allow you to assign permissions to a whole group of users at once.

When assigning out these roles, you may be tempted to assign everyone who will need access to a collection an Editor role to bypass the inevitable onslaught of “I need access to this collection!” requests. However, we recommend assigning the Viewer role by default, then Editor and Admin roles to others on a truly as-needed basis. This will prevent unintentional or unapproved changes to the collection that could include sensitive information, which is especially important if this is a shared or published collection.

Since this will limit access to shared elements, we recommend taking advantage of Postman’s built-in version control workflows. For those looking to contribute changes, a fork-edit-pull request workflow will serve as an additional review process to ensure shared collections stay up-to-standard. For developers who mainly use the shared collections for their own testing or debugging, creating a fork that is linked to the original collection will allow them to pull in any changes to the original collection while keeping any local changes out of the shared copy.

Team-level roles

At the broadest level of access management, users can be assigned team-level roles to help manage their Postman instance. Each user must have at least one role, but may have multiple roles at once. For most developers in your organization, the most logical role will probably be, well, the Developer role: this grants access to all of the team resources and workspaces. It should be sufficient for most development work.

When it comes to inviting and managing people in teams, an Admin role will be required. Those who deal with the team’s billing cycle can be assigned the Billing role, but the last few roles, Super Admin, Community Manager, and API Network Manager, are a little more interesting.

While managers and team leads may hold Admin roles, the Super Admin role should be given out more judiciously. This role can do every possible action on the Postman platform, so we recommend granting very few users this access—only those who know the platform well. Next up is the Community Manager: this role is responsible for approving and monitoring which information from the team gets exposed to the public. Especially for teams that deal with lots of sensitive information, having this extra safeguard in the form of a Community Manager who is familiar with the company standards to make sure workspaces, documentation, and other resources are fit for public use can be a great tool. The API Network Manager is a similar concept to the Community Manager, but focused on maintaining quality as users start adding APIs to an organization’s Private API Network.

Admin controls for managing teams safely and efficiently

While ensuring your users are handling data correctly is important for good security, ensuring the right people have the right access to your account is perhaps even more important. Unlike the previous section that focused on assigning the right access to roles at a project level, as organizations get larger, these issues of access become broader and require solutions that scale: the 10,000-feet-view of user management, if you will. Postman’s features available for administrators not only provide another layer of protection, but they can also save time in the account provisioning process as well. Let’s walk through each and how they’ll enhance your team management.

Management of team invites

When inviting new teammates to join your Postman team, those with Admin roles can invite people one-by-one using an email address, or they can generate a link that can be shared to invite multiple people at once. While the link is convenient, it’s important to ensure it’s only shared within the company and to those who have been authorized to join the platform. Though the links do expire after 15 days, administrators also have the option to view any links that are active and disable any that they feel have either been exposed or are just no longer needed.

Single sign-on (SSO)

Enabling SSO for Postman can result in an easier management of Postman accounts for both team members and administrators alike. Similar to how you may sign in to other non-Google products with your work Google account, Postman supports most major identity providers that support SAML 2.0. This allows you to add the Postman app to your organization’s list of SaaS products used. Adding SSO to your team’s Postman sign-in page not only makes for a more seamless sign-in experience (and one less password for everyone to manage), but it can enforce the use of multi-factor authentication to ensure user accounts stay secure.

Provisioning users with SCIM

Once you have SSO set up, you can take your team automation one step further by enabling SCIM. Many organizations may already have an Identity Access Manager set up, simplifying the process of giving the right privileges to the right employees on the right app. Postman can plug right into that provisioning workflow, using the Postman SCIM API, Okta, or Azure AD. Creating, activating, and deactivating a user can be done by team admins, making the process quick and less prone to human error.

Domain Capture

If you’re an organization with lots of developers, you may have seen or heard about developers setting up a Postman account without a team to do some API tinkering. While we’re always happy that people are finding the product useful, we know that the platform is best experienced when you can collaborate with your coworkers directly and avoid the exporting/importing collections dance. Having lots of people working with company information on independent accounts is also a security risk because it ignores a lot of the recommendations we’ve covered in earlier points. To help bring these developers together and help organizations manage their data better, earlier this year we introduced Domain Capture. This feature, once toggled on and paired with SSO, allows organizations to consolidate all of the existing Postman users into one company-managed account, and automatically directs any new users onto the account as well.

Note that this feature is a little more involved than just a toggle or filling in some fields: since “captured” users will be essentially locked out of their original accounts, it is vital to have a well-communicated plan in place to help everyone prepare and migrate any needed data. Our Support and Customer Success teams are always available to advise and help make the process go as smoothly as possible. While it takes a little more work than some of the other interventions, it’s also potentially the one with the biggest payoff. It’s a win-win for teams who now get the full power of the platform, and security administrators who can now breathe a little easier.

Stay tuned for Part 2

In the next blog post, we’ll be covering best practices for keeping your information secure within the platform. If you’re looking for some further reading on our security practices, we recommend checking out our Trust Center, or our white paper on Postman security features.

This post is by Postman Technical Enablement Architect Carson Hunter, Postman Senior Engineering Manager Suhas Gaikwad, and Postman Security Engineer II Ronak Odhaviya.