Postman is a popular tool for API testing. Developers and testers use Postman during the development phase for different types of API tests. Furthermore, the Newman package allows the same test suites to be used for test automation.
Challenges
Many Machine-to-Machine Apis use the OAuth 2.0 Client Credentials flow with a fixed set of client credentials. Test automation pipelines can deal with this since credentials can be securely managed in a secret store. However, challenges arise when developers and testers interact with such APIs via the Postman user interface:
- Credentials may expire, introducing additional management effort.
- Unauthorized persons with access to the credentials can still use the API.
- The complexity increases since users need to retrieve credentials before testing.
- There’s a risk of storing credentials in de Postman collection.
Solution
The Postman user interface supports the OAuth 2.0 Authorization Code flow. In contrast to the Client Credentials flow, users enter their own credentials to obtain a JWT Access Token through a public OAuth client. This removes the need for client credentials and therefore resolves the above challenges.
In order to implement this approach, we use the following guidelines:
- The API relies on JWT Access Tokens from Azure Active Directory.
- Test automation pipelines are implemented as a GitHub Actions Workflow.
- Test automation pipelines retrieve Access Tokens through the Client Credentials flow.
- Developers and testers retrieve Access Tokens through the Authorization Code flow with a public client.
API Setup
First, the Api requires an Application Registration (AR) in AAD that has an App Role ApiConsumers. API consumers request Access Tokens with an audience that matches the App ID Uri of this AR. The API must validate the Access Token of each request and must also verify that the roles claim contains an entry for ApiConsumers.
Test Automation Pipeline
Next, the test automation pipeline is implemented as a GitHub Actions workflow. It relies on federated credentials to authenticate against the GitHub Test Client AR. This AR is assigned to the ApiConsumers App Role of the Api AR. The following figure shows the configuration:
The GitHub Actions workflow requests Access Tokens through the GitHub Test Client AR by using the Client Credentials flow. Here, it uses the scope {Application ID URI}/.default to retrieve a token for the API. Once the workflow has successfully obtained an Access Token, it executes the Newman package and passes the Access Token as an environment variable:
Here, the following pre-request script of the Postman collection places the Access Token in the authorization header for each request:
The resulting output of a GitHub Action workflow is shown below:
Developer and Tester Setup
Finally, developers and testers must use the Authorization Code flow to authorize requests to the API. This flow relies on the user context of developers and testers to securely obtain Access Tokens. This requires a new Application Registration in AAD. The resulting Postman Test Client AR has a ‘Mobile and desktop applications platform’ configured with the callback URI https://oauth.pstmn.io/v1/callback:
Furthermore, all authorized users are assigned to the Postman Test Client AR to be able to use it for retrieving tokens. Also, users are assigned to the ApiConsumers app role of the API. The following figure shows the configuration:
The Postman collection requires the following token configuration to retrieve Access Tokens:
Here, the Authorization URL and Access Token URL are unique for the AAD tenant. The Client ID matches the Client ID of the Postman Test Client, and the scope refers to the App ID Uri of the Api AR. No secret is required since Postman Test Client is considered to be public.
Users can now retrieve an Access Token for the API by logging in with their regular AAD account. This token overrides the value from the pre-request script of the collection, so all requests and tests should work as intended. Since the token configuration contains no client secret, it can be stored inside the Postman collection.
Conclusion
The above approach allows Postman collections to be used for both manual and automated testing of Machine-To-Machine Apis. It improves governance since non-authorized users cannot abuse leaked client credentials. Furthermore, Postman collections can safely be stored in a source control system because they do not contain any secrets. Conclusively, this aids the practice of Shift Left testing and accelerates the development cycle of APIs.
Check this GitHub Repo for an example implementation.
