OAuth 2.0 Authentication

Karate Xplorer provides comprehensive OAuth 2.0 support for testing APIs requiring user authentication and authorization. The implementation follows industry standards and integrates with popular OAuth providers.

Overview

OAuth 2.0 is an authorization framework enabling applications to obtain limited access to user accounts on HTTP services. Xplorer automates the complex OAuth flow so developers can focus on API testing.

Key Features

• System Browser Integration: Uses your default browser for authentication — secure and familiar
• Existing Sessions Work: If already logged into the OAuth provider, authentication is instant
• Secure by Design: Credentials never pass through Xplorer; authentication occurs directly with the provider
• Automatic Token Management: Tokens are cached and automatically refreshed when expired
• PKCE Support: Built-in Proof Key for Code Exchange for enhanced security
• Multiple Grant Types: Client Credentials, Authorization Code, and Authorization Code with PKCE

Supported Grant Types

Client Credentials is best for server-to-server authentication without user interaction, including backend services, automated scripts, and service accounts.

Authorization Code is best for web applications where user authentication is required, such as apps needing user-specific data when the client secret can be kept confidential.

Authorization Code with PKCE is best for public clients like mobile apps, single-page applications, and desktop applications where client secrets cannot be securely stored.

Setting Up OAuth 2.0

Step 1: Register Your Application

Register an application with your OAuth provider by accessing their developer console, creating a new OAuth application, configuring the redirect/callback URL, and obtaining the Client ID and Client Secret.

Step 2: Configure Callback URL

Xplorer uses a local callback server listening on one of these ports (in order):

http://127.0.0.1:8080/callback
http://127.0.0.1:8888/callback
http://127.0.0.1:9090/callback
http://127.0.0.1:3000/callback

When registering, configure callback URLs based on provider capabilities: if you know a port is available, register just that one; if your provider supports multiple URLs (like Google or Auth0), add all four for maximum flexibility; if only one URL is allowed, use port 8080.

Provider Examples

GitHub: Settings → Developer settings → OAuth Apps → Create new OAuth App → Set Authorization callback URL to http://127.0.0.1:8080/callback

Google: Google Cloud Console → APIs & Services → Credentials → Create OAuth 2.0 Client ID → Add callback URLs to "Authorized redirect URIs"

Auth0: Applications → Create Application → Add callback URLs to "Allowed Callback URLs" (comma-separated or multiple entries)

Step 3: Configure OAuth in Xplorer

1. Open a request requiring OAuth authentication
2. Navigate to the Auth tab
3. Select OAuth 2.0 from the Auth Type dropdown
4. Choose a Grant Type
5. Fill in OAuth configuration fields

For Authorization Code or Authorization Code with PKCE:

Field	Description	Example
Authorization URL	Where users log in	https://github.com/login/oauth/authorize
Access Token URL	Where tokens are exchanged	https://github.com/login/oauth/access_token
Client ID	Application's client ID	your-client-id
Client Secret	Application's secret (optional for PKCE)	your-client-secret
Scope	Permissions requested	user repo

For Client Credentials:

Field	Description	Example
Access Token URL	Token endpoint	https://oauth.example.com/token
Client ID	Application's client ID	your-client-id
Client Secret	Application's secret	your-secret
Scope	Permissions requested (optional)	api:read api:write

Using OAuth 2.0

First Request — Authentication Flow

1. Click the Run button on your request
2. Browser dialog opens with the OAuth provider's login page
3. Log in with your credentials (or skip if already logged in)
4. Authorize the application — grant the requested permissions
5. Dialog closes automatically after successful authorization
6. Request executes with your access token
7. View the response in the Output pane

Subsequent Requests — Token Reuse

For subsequent requests using the same OAuth configuration:

1. Click Run on any request with the same OAuth config
2. No browser dialog — cached token is used automatically
3. Request executes immediately

Xplorer automatically handles token refresh when the token expires, requiring authentication only once per session.

Example: GitHub OAuth with Environment Variables

This complete example demonstrates OAuth 2.0 with GitHub, using environment variables for all credentials.

Sample files available:

• github-oauth.postman_collection.json — the collection (no secrets, just variables)
• github-dev.postman_environment.json — sample dev environment
• github-prod.postman_environment.json — sample prod environment

How to Use

1. Register a GitHub OAuth App at GitHub → Settings → Developer settings → OAuth Apps
   • Set the callback URL to http://127.0.0.1:8080/callback
   • Copy the Client ID and generate a Client Secret
2. Edit the environment file — replace your-dev-client-id and your-dev-client-secret with your actual credentials
3. Open the collection in Xplorer (File → Open or drag and drop)
4. Load the environment file (File → Open or drag and drop)
5. Click Send on any request — the browser opens for GitHub login
6. Authorize the app — the token is cached for subsequent requests

Collection Auth Configuration

The collection uses variables for all OAuth fields. Auth is set at the collection level, so all requests inherit it automatically:

{
  "auth": {
    "type": "oauth2",
    "oauth2": [
      { "key": "grant_type", "value": "authorization_code", "type": "string" },
      { "key": "authorizationUrl", "value": "{{githubAuthUrl}}", "type": "string" },
      { "key": "url", "value": "{{githubTokenUrl}}", "type": "string" },
      { "key": "client_id", "value": "{{githubClientId}}", "type": "string" },
      { "key": "client_secret", "value": "{{githubClientSecret}}", "type": "string" },
      { "key": "scope", "value": "{{githubScope}}", "type": "string" }
    ]
  }
}

Environment File

Each environment file provides the actual values. Edit the Client ID and Secret for your OAuth app:

{
  "name": "GitHub - Dev",
  "values": [
    { "key": "githubApiUrl", "value": "https://api.github.com", "enabled": true },
    { "key": "githubAuthUrl", "value": "https://github.com/login/oauth/authorize", "enabled": true },
    { "key": "githubTokenUrl", "value": "https://github.com/login/oauth/access_token", "enabled": true },
    { "key": "githubClientId", "value": "your-dev-client-id", "enabled": true },
    { "key": "githubClientSecret", "value": "your-dev-client-secret", "enabled": true },
    { "key": "githubScope", "value": "user repo", "enabled": true }
  ]
}

Switching Environments

Simply open a different environment file — the collection stays the same. The prod environment might have a different Client ID, Client Secret, or more restricted scopes. The Bearer token is automatically added to requests by Xplorer after successful OAuth authentication.

Security Considerations

Why System Browser?

Xplorer uses your system's default browser for OAuth authentication because:

• Secure: Credentials go directly to the OAuth provider, never through Xplorer
• Familiar: You see the real OAuth provider's page with proper SSL certificates
• Session Reuse: If already logged in, authentication is instant
• Transparency: You can verify the URL and certificate in your browser

HTTPS Requirement

For security, OAuth providers typically require HTTPS for their authorization endpoints. Xplorer works best with HTTPS OAuth providers.

Recommended providers: GitHub, Google, Microsoft, Auth0, Okta, and other major OAuth providers that use HTTPS.

Troubleshooting

Browser Dialog Doesn't Open

Issue: Clicking Run doesn't show the browser dialog.

Solutions:

• Check that you've selected the correct Grant Type (should be "Authorization Code" or "Authorization Code with PKCE")
• Verify your Authorization URL is correct and uses HTTPS
• Make sure all required fields are filled in

"Invalid Redirect URI" Error

Issue: OAuth provider shows an error about the redirect URI.

Solution: Make sure you've added the callback URLs to your OAuth provider's configuration:

http://127.0.0.1:8080/callback
http://127.0.0.1:8888/callback
http://127.0.0.1:9090/callback
http://127.0.0.1:3000/callback

Token Expired Errors

Issue: Getting 401 Unauthorized errors on subsequent requests.

Solution: Xplorer automatically refreshes tokens, but if errors persist:

• Some OAuth providers don't support token refresh
• You may need to re-authenticate manually
• Check your OAuth provider's token lifetime settings

Port Already in Use

Issue: All callback ports are in use.

Solution: Xplorer tries ports 8080, 8888, 9090, and 3000 in sequence. If all are in use:

• Stop other applications using these ports
• Or restart Xplorer to try again

Using Environment Variables with OAuth

OAuth configuration fields fully support variable syntax. This keeps sensitive values like Client ID, Client Secret, and token URLs out of your collection and manages them per environment instead.

Step 1: Use Variables in the Auth Tab

In the Auth tab, use variable placeholders instead of hardcoded values:

Field	Value
Access Token URL	{{tokenUrl}}
Client ID	{{clientId}}
Client Secret	{{clientSecret}}
Scope	{{scope}}

The same approach works for Authorization Code flows — use variables for the Authorization URL as well.

Step 2: Create Environment Files

Create a separate environment JSON file for each environment. These follow the standard Postman environment format.

dev.postman_environment.json:

{
  "name": "Dev",
  "values": [
    { "key": "baseUrl", "value": "https://dev-api.example.com", "enabled": true },
    { "key": "tokenUrl", "value": "https://dev-auth.example.com/oauth2/token", "enabled": true },
    { "key": "clientId", "value": "dev-client-id", "enabled": true },
    { "key": "clientSecret", "value": "dev-client-secret", "enabled": true },
    { "key": "scope", "value": "read write", "enabled": true }
  ]
}

staging.postman_environment.json:

{
  "name": "Staging",
  "values": [
    { "key": "baseUrl", "value": "https://staging-api.example.com", "enabled": true },
    { "key": "tokenUrl", "value": "https://staging-auth.example.com/oauth2/token", "enabled": true },
    { "key": "clientId", "value": "staging-client-id", "enabled": true },
    { "key": "clientSecret", "value": "staging-client-secret", "enabled": true },
    { "key": "scope", "value": "read write", "enabled": true }
  ]
}

Create similar files for production or any other environment.

Step 3: Switch Environments

1. Open your collection in Xplorer
2. Load the desired environment file via File → Open or drag and drop
3. The environment name appears in the Environment Pane (right panel)
4. Run your requests — OAuth fields automatically resolve to the active environment's values
5. To switch, simply open a different environment file

This way your collection file stays unchanged — only the environment determines which OAuth provider, credentials, and API endpoints are used.

Tip: For Okta-style setups, the Access Token URL typically looks like: https://{{oktaDomain}}/oauth2/default/v1/token. You can make even the domain part a variable for maximum flexibility.

Example: Okta Client Credentials per Environment

A common enterprise pattern is Okta with Client Credentials grant type, where each environment has its own Okta tenant.

Collection Auth tab configuration:

Field	Value
Auth Type	OAuth 2.0
Grant Type	Client Credentials
Access Token URL	{{oktaTokenUrl}}
Client ID	{{oktaClientId}}
Client Secret	{{oktaClientSecret}}
Scope	{{oktaScope}}

qa.postman_environment.json:

{
  "name": "QA",
  "values": [
    { "key": "baseUrl", "value": "https://qa-api.yourcompany.com", "enabled": true },
    { "key": "oktaTokenUrl", "value": "https://yourcompany-qa.okta.com/oauth2/default/v1/token", "enabled": true },
    { "key": "oktaClientId", "value": "0oa1234567abcdefg", "enabled": true },
    { "key": "oktaClientSecret", "value": "your-qa-client-secret", "enabled": true },
    { "key": "oktaScope", "value": "api.read api.write", "enabled": true }
  ]
}

Create matching files for dev, staging, and production with their respective Okta tenant URLs and credentials.

Tips and Best Practices

1. Use PKCE for Desktop Apps: Authorization Code with PKCE is more secure for public clients like Xplorer
2. Set Appropriate Scopes: Only request the permissions you actually need
3. Test with GitHub First: GitHub OAuth is well-documented and works great for testing
4. Keep Client Secrets Secure: Don't commit OAuth credentials to version control — use environment files and keep them out of source control
5. Use Environment Variables: Store sensitive values like Client ID and Secret in environment files so you can switch between environments without editing the collection
6. One Authentication Per Session: Once authenticated, the token is cached for all requests in the collection

Additional Resources

• OAuth 2.0 RFC 6749
• PKCE RFC 7636
• GitHub OAuth Documentation
• Google OAuth 2.0 Documentation