How to Use OAuth2 for the Authorization Code Grant Type

OAuth2 authentication can be implemented in various ways, depending on the collection structure and specific requirements. You can configure OAuth2 authentication at collection, folder, and request level.

OAuth2 Configuration

Select OAuth 2.0 as the authentication method and set the grant type to Authorization Code. Fill in the following fields:

  • Callback URL: The URL where you want to receive the authorization code
  • Authorization URL: The endpoint for authorization
  • Access Token URL: The endpoint to exchange the code for a token
  • Client ID: Your application’s client identifier
  • Client Secret: Your application’s client secret
  • Scope: The requested scope
  • State: An opaque value to maintain state between the request and callback
  • Add Credentials to: Choose how to send credentials (Request Body or Basic Auth Header)

Enable Use PKCE if your OAuth provider supports and requires PKCE (Proof Key for Code Exchange).

Understanding Callback URLs (Redirect URIs)

The Callback URL (also known as Redirect URI) is a critical component of the OAuth2 authorization code flow. Here’s what you need to know:

What is a Callback URL?

The callback URL is the address where the OAuth2 provider (like Azure, Google, Facebook, etc.) will redirect the browser after successful authentication. This redirect contains a sensitive authorization code that Bruno extracts to complete the authentication process.

How Bruno Handles Callback URLs

Bruno does not actually redirect to the callback URL. Instead, it intercepts the redirect attempt and extracts the authorization code from the URL that the OAuth2 provider tried to redirect to.

This means:

  • Bruno Support all formats: It can handle any callback URL format that your OAuth2 provider allows
  • No actual redirection: Bruno never actually navigates to the callback URL
  • Security maintained: The authorization code is extracted securely without exposing it
⚠️

If your application is already configured with OAuth2, use one of the existing callback URLs from your OAuth2 provider console. Do not add new URLs unless necessary.

Token Configuration and Usage

Before getting the access token, configure how you want to use it in your requests:

  1. Token Usage Configuration:

    • Add token to: Specify how the token should be included in requests:
      • Headers: Adds the token to request headers with a configurable prefix (default: "Bearer").
      • URL: Adds the token as a URL query parameter with a configurable parameter name (default: "access_token").
  2. Token Management Settings:

    • Auto-fetch: When enabled, Bruno will automatically fetch a new token when you try to access a resource and don’t have a valid token.
    • Auto-refresh: When enabled, Bruno will automatically refresh your token using the refresh URL when it expires.

    These settings streamline your workflow by reducing manual token management. Note that token refresh operations require a valid refresh token to be available.

You may optionally assign a Token ID to your token. If you do, you can reference this token in requests using the format {{$oauth2.<tokenId>.access_token}} (replace <tokenId> with your Token ID).

💡

If you use the same Token ID in multiple OAuth requests, Bruno will overwrite the existing token data. Make sure to use unique Token IDs for different OAuth configurations.

  1. Click Get Access Token to obtain and store the token.

You can click the ‘Clear Cache’ button to remove the stored token and request a new one.