Get started with Postman to Access MSaaS API

CONTENTS

• Prerequisite
• Create Environment
• Import Collection
• Additional Preparations^optional
• Script Execution
• Script Execution Walk-through^optional

PREREQUISITE

• Install Postman.
• Obtain MSaaS API credentials (Tenant ID, App/Client ID, Support Area Path, Entitlement ID, etc) from Microsoft.
• Prepare a self-signed SSL certificate (in DEV and UAT). Keep private key (preferrably *.pem) and register public key with Microsoft. This may be created in various ways, depending on the system and resources at hand.
• Gain some familiarity with Postman debugging tools ^optional.

CREATE ENVIRONMENT

1. Open Postman, click drop-down triangle at top left corner.

2. Select Environment to create a new environment. Environment is functionally a placeholder for key-value pairs.

3. Name the new environment (say, Msaas Api Dev). Click Add button.

4. Click X symbol to dismiss the dialog (or simply press Esc key).

5. Select Msaas Api Dev (or whichever name you made) from Environment dropdown list.

IMPORT COLLECTION

1. Click Import button at top left corner to import the sample collection compiled by Microsoft.

2. Click Import From Link tab.

3. Supply Collection Link provided by Microsoft, and click Import button.

4. Alternatively, click Paste Raw Text tab, copy Collection script from github repository, paste entire JSON string in the text box, and click Import button.

5. Or, download the collection using the button below:
   

6. For other potential approaches, check this and this.

7. After import, we are ready to work with collection. If Postman sidebar has not already appeared, click Hide Sidebar symbol at bottom left corner to toggle sidebar.

8. Click Collections tab.

9. Click Msaas API folder to show the content.

10. Click GET 000 Environment Initialization Request.

11. Click Pre-request Script tab.

12. Please have a look at the brief README section regarding the uses and fine prints of the scripts under this request. In a nutshell, the script in Pre-request Script tab is run for preparation before sending GET request to JsRsaSign repository for JsRsaSign script, while the script in Tests tab is run afterwards for post-request processing and token request.

13. Further scroll down and find the following fields ThumbPrint, ClientId, TenantId, PrivateKey, and SupportAreaPath (SAP). The placeholders shown in red boxes below require user input.

    Attribute	Comment
    ThumbPrint	The public key certificate (*.cer) thumbprint the partner provided to Microsoft
    ClientId	Client ID (aka App/Application ID) shall be provided by Microsoft
    TenantId	Tenant refers to Azure Stack for our purpose, whose Tenant ID shall be provided by Microsoft
    PrivateKey	The private key string of the private key certificate (*.pem) which the user/partner securely keeps
    SupportAreaPath	The routing parameter used to direct request to Azure Stack team

ADDITIONAL PREPARATIONS ^optional

1. Go to Menu bar > View > Show Postman Console to open Postman Console.

2. Verify console is launched and ready.

3. If clicking the eye symbol at top right corner, we can examine the existing Global and Environment variables.

4. If Postman is newly installed, there is likely no variable on the list, as shown below. On the other hand, if there is any existing variable on the list, please note that they will be erased by this script execution.

SCRIPT EXECUTION

❗️❗️**Any existing variables will be erased if running the script as is.**❗️❗️

1. If there is any existing variable(s), which should not be erased, please comment out the following two lines of code in Pre-request Scripts tab.

   pm.globals.clear();
   pm.environment.clear();
   

2. Click Send button to run the scripts.

3. After execution, verify response Status is 200 OK.

4. Click the eye symbol at top right corner again to verify the Global and Environment variables are populated on the list.

5. Now, we are ready to run some scenarios against MSaaS API. The rest of article below is optional but informational.

SCRIPT EXECUTION WALK-THROUGH ^optional

1. Switch to Postman Console, and verify the existence of various transactions with successful response status codes (200 for GET, 201 for POST, 204 for PATCH, etc).

❗️❗️**eval() is vulnerable to malicious scripts and should be avoided if possible.**❗️❗️
2. First request acquired JsRsaSign script, which was immediately compiled. eval() is used here as last resort suggested by Postman team due to Postman Sandbox’s limitation on introducing dependencies.

3. Equipped with JsRsaSign dependency, JWT was synthesized in the form of header.claims.signature, where:

• Header is a base64Url-encoded string (For details, see RFC7519 JOSE Header):

  { 
      alg: "RS256", 
      typ: "JWT", 
      x5t: [thumbprint converted from hex to base64Url]
  }
  

• Claims (aka payload of JWS) are a base64Url-encoded string (For details, see RFC7519 Registered Claim Names):

  { 
      aud: https://login.microsoftonline.com/ [tenantid] /oauth2/token
      nbf: [current 10-digit POSIX timestamp]
      exp: [near-future (say, 10 min from now) 10-digit POSIX timestamp]
      jti: [Random GUID]
      iss: [clientId]
      sub: [clientId]
  }
  

• Signature is the digital signature computed by passing header.claims as input along with the private key through the RSA-SHA256 algorithm. This signing process was carried out by JsRsaSign static method KJUR.jws.JWS.sign(). For technical specification, see RFC7515 A.2.

4. Second request acquired the access token in the form of Bearer Token by submitting the JWT as Client Assertion along with other payload parameters to Authorization Server (login.microsoftonline.com/ [tenant id] /oauth2/token). Note that a. This is a POST request instead of GET, and b. The access token is also in the form of JWT (header.claims.signature), but this time the Authorization Server is the issuer and signer.

5. Acquired access token (valid for one hour) was immediately persisted as Environment variable for later uses. Always take great care of the Bearer Tokens since whoever with this token has the same access as the intended user/partner to the MSaaS API. For details, see this and this.

6. The third request, with the access token, created a new case and obtained its case number.

7. The fourth request, with the access token and new case number, retrieved the case JSON of the same.

8. With that, we can now proceed to Postman Scenarios section against MSaaS API.