Interceptor integration for Postman Native Apps

Postman <> Interceptor Integration

Update: This post was updated on June 22, 2019, following the release of this feature in Postman’s production build.

We’re finally ready to launch a beta for the Interceptor integration for the native Postman apps! The Interceptor is a very useful part of the Postman workflow - making API calls in the context of the browser’s session is a common use case. However, with Google announcing their intention to deprecate Chrome Apps, we realized that lack of this workflow was a big handicap for our native apps. Any use-case which requires you to login to the browser (effectively setting a cookie) and performing API calls from Postman was cumbersome at best. This is the first problem we’ve tried to address. The Interceptor integration in available in Postman starting today!

Requirements:

  1. Postman Interceptor (v0.2.26 and above): https://go.pstmn.io/interceptor-download
  2. Postman App (v7.2.1 and above): https://www.getpostman.com/downloads/
  3. Interceptor Bridge (available here):
    OSX
    Windows
    Linux

Quick Start

  • Run the install script from the OS-specific Interceptor Bridge package. Do not change the location of the com.postman.postmanapp.json file after executing the install script. Depending on your OS, you might need to double-click or execute the installer script via a shell. Users on MacOS/Windows might see a security warning. For example, to override the security on MacOS, you may need to right click > open.

  • Restart Chrome (only required for Windows)

  • Update the Postman Interceptor Extension to v0.2.26 or above (chrome://extensions/ > enable Developer Mode > Update).

  • Update Postman to v7.2.1 or above.

  • Open the capture cookie overlay from the icon on the top-right.

  • The ‘Interceptor Connected’ status indicates that Postman is able to communicate with the Interceptor extension installed in the browser.

  • Enable the Capture cookies setting, and add domains you want to sync cookies for.

Long Version:

Interceptor Bridge

We’re using Chrome’s nativeMessaging feature to facilitate communication between the Interceptor (a Chrome Extension) and Postman (a native application). This requires a standalone executable to be present on the user’s system for Chrome to interact with. A detailed explanation of this flow is coming soon!

This means there’s a small installation step required before the integration can be used. You’ll need to download an OS-specific version of the bridge. The installer script will add an entry (certain file directories for OSX/Linux, Registry for Windows) that tells Chrome where to find the bridge executable.

The next time Chrome opens (and the Interceptor extension is enabled), the Interceptor will have a permanent duplex messaging link with this executable. The executable starts an IPC server, to enable communication between Postman and the executable.

Postman App

To start using the cookie capture functionality, open the cookie capture overlay from the top-right of the Postman window. Here, you’ll be able to view and modify the list of domains you want to sync cookies for. You’ll also see the status of the Postman <> Interceptor connectivity. If you see an ‘Interceptor Disconnected’ status, try reinstalling the bridge, and restarting Chrome.

Once you see a successful connection, enable the Capture cookies setting. You now need to add domains whose cookies you want synced from the browser. Entering the root domain will sync cookies for all its subdomains as well. Adding facebook.com, for example, will sync cookies whose domain is facebook.com or www.facebook.com.

API reference (not required for Postman versions 7.2.1 and above):

  1. pm.interceptorBridge.cookieSync.enable(): Enable cookie syncing from the Interceptor to Postman
  2. pm.interceptorBridge.cookieSync.disable(): Disable cookie syncing from the Interceptor
  3. pm.interceptorBridge.cookieSync.addDomain(domain: String): Add a new domain for which cookies should be synced. eg. addDomain('facebook.com')
  4. pm.interceptorBridge.cookieSync.removeDomain(domain: String): Stop receiving cookie updates for a domain.
  5. pm.interceptorBridge.cookieSync.getDomainList(): Get the list of domains for which cookies are currently being synced
  6. pm.interceptorBridge.setKey(key: String): Set a key for encryption over IPC. The same key must be set on the Interceptor as well. Using this is optional.
  7. pm.interceptorBridge.getKey(): Reading the key that’s currently used for encryption over IPC.

Encryption

The interceptor and Postman communicate via two sets of IPC. One provided by Chrome (from the Interceptor to the Bridge), one from the bridge to Postman. You can choose to set a key for end-to-end encryption of your messages.

If you set a key for encryption, use the pm.interceptorBridge.setKey(key: String) command in the app. To set the key on the interceptor, open the Interceptor extension popup from the toolbar, right click > Inspect Element > Console. Enter the same command here - pm.interceptorBridge.setKey(key: String). This will encrypt anything sent between the two sides using AES.

Notes

  1. Postman’s cookie jar will respect all cookie properties - expiry, path, secure etc.

  2. For a domain that has cookie syncing enabled, new cookie creations, updates to cookie values/properties, and cookie deletions will all be synced to Postman.

  3. Enabling cookie sync for facebook.com will enable cookie sync for all subdomains as well. Internally, we check for the domain strictly matching facebook.com, or ending with .facebook.com

  4. Once you disable cookie syncing for a domain, syncing of future cookie updates will be stopped, but the existing cookies for that domain will NOT be removed from Postman. They can be deleted manually from the Cookies section.

  5. On restart of the Postman app, all cookies for the configured domains will be re-synced, so you’ll be able to retain browser context seamlessly.

7 Likes

On Requirements, are you sure you don’t mean Version 0.2.26 and above of the interceptor?

1 Like

Unable to add domains to the list. I get:
pm.interceptorBridge.cookieSync.addDomain(‘foobar.com’)
“adding foobar.com to the domain list…”
pm.interceptorBridge.cookieSync.getDomainList()
“fetching domain list …”
InterceptorBridge : No domains found

@baronmog Can you restart the Postman app and send a screenshot of the View -> Developer -> Current View?

Essentially, after the app restarts, you should see the INTERCEPTOR CONNECTIVITY: cookie sync enabled for the domains - Array(1) message.

@baronmog Can you re-attempt the quick-start steps? After installing the bridge, you should have the com.postman.postmanapp.json file in: /Users/nromer/Library/Google/Chrome/NativeMessagingHosts or $HOME/Library/Application Support/Google/Chrome/NativeMessagingHosts

If not, we’ll be happy to get on a call with you to sort this out.

Hmm. I’ve followed the instructions to install the Postman Canary app ( v 7.1.1), but I don’t see the any interceptor toggle inside the canary app to be able to enable the desktop application to see requests from the chrome extension.

Therefore, the problem I’m having is that requests are captured successfully in the browser extension, but nothing shows up in the canary app.

According to the existing interceptor documentation, I should expect to see an interceptor toggle in the header of the postman app, but inside of the canary version of the app, all I see is this:

@ldstn The docs are for the Chrome version only - we’re working on updating those. For now, you’ll need to use the command-line API (described above) to configure domains to sync cookies between Chrome and the Postman app.

Syncing history requests isn’t supported yet.

1 Like

Doesn’t work on MacOS for me. When switching “Capture cookies” on, it still displays INTERCEPTOR DISCONNECTED.

3 Likes

@brandon.kiefer Can you confirm you’ve completed the following:
Downloaded and installed the interceptor bridge as described above
Restarted Chrome

Toggling the capture cookies setting won’t affect the connection status. The status is only determined by whether Chrome is open with the Interceptor extension installed, and whether the bridge has been installed.

I should manually insert the domain name in the cookies manager as I did in the capture cookies interface or it should fetch it automatically.

At the moment I’m not able to get any cookies both ways.

@Malaachi
The cookies and domains will be populated automatically. Can you confirm the following:

  1. Chrome is open, and has the Interceptor extension installed (v0.2.26)
  2. You’ve completed the installation steps for the bridge
  3. The Interceptor Status isn’t updating to ‘Interceptor Connected’ even after restarting Chrome

If all three are true, could you contact us at help@getpostman.com? We’ll need to check system logs for why the connectivity isn’t being established.

does not work on MacOS for me either… I have restarted chrome and restarted my machine, and uninstalled and installed the interceptor.

MacOS update: it appears as tho you have to add the url you are trying to capture cookies for to the allowed_origins in the com.postman.postmanapp.json file

“allowed_origins”: [
“chrome-extension://aicmkgpgakddgnaphhhpliifpcfhicfo/”,
https://www.example.com/
]

then maybe restart your browser and restart postman. I also think you have to have chrome running before you start postman.

@nick That’s weird. The Chrome docs (https://developer.chrome.com/apps/nativeMessaging) state:

allowed_origins: List of extensions that should have access to the native messaging host. Wildcards such as chrome-extension://*/* are not allowed.

Did adding the example.com domain work for you? My guess is it could have been more to do with the restarts. Can you remove the example.com line, restart your browser, and check if the cookie syncing works?

Not work on MacOS for me

The Postman Interceptor have captured some reqeust.


and App show ‘INTERCEPTOR CONNECTED’.
image

But Cookies is not found.

@jomenxiao As mentioned in the blog post, you’ll need to enter the domain in the Postman app UI, in the “Enter a domain to capture cookies” input, and hit ‘Add domain’. Once this is done, the Interceptor will sync cookies for those domains.

The UI in the Interceptor extension in the browser is only for the Chrome app, and not relevant for this integration.

I have added the domain to “enter domain to capture cookies” section in multiple fashions as show below with replacing example.com with my real domain with to luck is there something I’m missing still? The intercepter is on in chrome and I recently restarted both the app and chrome.

Domains structure entered:
https://example.com
https://example.com/
https://example.com/*
https://example.com/path/to/my/endpoint

@dsudenfield you just need the ‘example.com’ structure, without the https:// part. Is the Interceptor Connected status showing up?

1 Like