Insomnia plugin for Microsoft Entra ID

Easily acquire Microsoft Entra ID tokens from within Insomnia REST Client!

This plugin supports:

• OAuth 2.0 code and client credential flows for Work or School accounts and Microsoft accounts (when applicable),
• Account saving to Insomnia store,
• Silent log in for saved accounts, even across Insomnia sessions.

Pre-requisites

This plugin requires Insomnia, the Open Source API client.

Installation

1. Start Insomnia,

2. Click "Application" -> "Preferences" and choose the "Plugins" tab,

3. Enter insomnia-plugin-azure-ad-authentication and click "Install Plugin",

   

4. Close the dialog.

Usage

1. Open a new request, switch to the "Headers" tab,

2. Insert a new header. In the header name field, enter Authorization,

3. In the value field type Bearer control + space entra. This will bring the template tag menu and reveal the Entra ID Authorization template:

   

4. Choose the desired Microsoft Entra instance. Most users will choose Entra ID global service. The tag will display its unconfigured form as follows:

   

5. Click on the tag to edit. Specify the Directory (tenant) ID, the Application (client) ID, desired scopes and the Redirect URI. For Microsoft Accounts, set Directory to consumers. For Work or School accounts, set Directory to organizations, a tenant name or tenant ID (i.e contoso.com or f0cb5560-5e2a-4b3b-88f9-8193bdd39f7a). To allow for both Microsoft Accounts and Work or School accounts, select common. Choose the desired Scopes, Redirect URI (see configure Microsoft Entra ID Application) and Token Grant Flow (see Choosing a token grant flow).

   

6. Close the "Edit Tag" dialog,

7. Send a request by pressing "Send". If an interactive login has been chosen, a browser window will appears and take you through the regular Microsoft Entra ID login flow possibly including consent. When the authentication completes, the tag will display its logged in form as follows:

   

Configuring the Microsoft Entra ID application

This plugin requires the Redirect URI specified during step 5 above to be configured under "Mobile and Desktop applications" or "Web" in Microsoft Entra ID. Other platforms (including "Single Page Application") are not currently supported.

By default, the Redirect URI is http://127.0.0.1:1234/redirect and most users should configure their Microsoft Entra ID application with this default return URI. If you are unable to configure Microsoft Entra ID with http, see Issue #2 - http not allowed anymore for instructions on how to change the application manifest. For web browser token grant flows, the only practical option is a Redirect URI targetting 127.0.0.1 instead of localhost since some web browsers block navigation to http://localhost.

An example of Microsoft Entra ID application Redirect URIs can be seen below:

The following Redirect URI styles are supported:

1. http://127.0.0.1:<port></path> where port is a valid, port number above 1000 and available for binding. Examples include: http://127.0.0.1:1234 or http://127.0.0.1:1234/openid,
2. http://<dns-name>:<port></path> where dns-name resolves to 127.0.0.1 via an entry in the local machine hosts file. Examples include: http://myapp:1234 or http://myapp:1234/openid.

The following Redirect URI styles are not supported:

1. Use of https. The plugin currently only supports http for Redirect URI,
2. Use of localhost. Most web browsers block navigation to localhost or force the use of https which the plugin does not currently support,
3. Postman style callback URLs (aka https://oauth.pstmn.io/v1/callback and variants). On most computers, oauth.pstmn.io is a valid DNS name that resolves to an IP address other than 127.0.0.1.

Configure for Shared Secret or Certificate authentication

Microsoft Entra ID applications can authenticate as themselves wihtou any user interaction. This capability can be enabled by adding a shared secret (client secret) or a certificate. More details can be found in the Microsoft Entra ID documentation Quickstart: Register an application with the Microsoft identity platform

Learn more about Microsoft Entra ID Redirect URIs with Redirect URI (reply URL) restrictions and limitations.

Choosing a token grant flow

This plugin supports the following OAuth 2.0 grant flows. For more information on OAuth 2.0 flows, see Scenarios and supported authentication flows

1. Authorization code with PKCE - Authorization code flow,
2. Client Credentials - Shared secret,
3. Client Credentials - Certificate.

Authorization code with PKCE

This is the most common flow. A web browser is opened and users authenticate with Microsoft Entra ID interactively. With this flow, it is possible to choose the type of token returned and the scopes. An access token can be used to authenticate and authorize calls to Web APIs. An id token can be used to verify a user is who they claim to be.

When using this flow, the Scopes accepts a space separated list of Microsoft Entra ID permission like openid offline_access.

Client Credentials - Shared secret

This flow permits a web service (confidential client) to use its own credentials, instead of impersonating a user, to authenticate when calling another web service. The client presents a pre-established shared secret. This flow is not recommended in production. Create a shared secret in Microsoft Entra ID and paste the secret in the 'Shared Secret' field.

When using this flow, the Scopes field must be set to <app URI>/.default, for instance api://f0cb5560-5e2a-4b3b-88f9-8193bdd39f7a/.default.

Client Credentials - Certificate

This flow permits a web service (confidential client) to use its own credentials, instead of impersonating a user, to authenticate when calling another web service. The client uses a certificate to sign an assertion. Upload the public key of a certificate to Microsoft Entra ID. Configure the plugin with the certificate thumbprint and the certificate private key file in PEM format.

When using this flow, the Scopes field must be set to <app URI>/.default, where <app URI> is the Microsoft Entra ID application URI, for example api://f0cb5560-5e2a-4b3b-88f9-8193bdd39f7a/.default.

Actions

The plugin allows users to log out or clear the cache to forget all saved accounts. These capabilities are accessible via the "Edit Tag" dialog:

Future Improvements

Enhancements include:

• Encrypt tokens saved to the Insomnia cache,
• Implement 'on behalf' flow,
• Enable B2C.