Professional

Configuring authentication for API scans

• Last updated: August 30, 2024

• Read time: 4 Minutes

You can configure endpoint authentication for API scans. This enables Burp Scanner to access authenticated endpoints, increasing your scanning coverage. Burp Scanner currently supports the following authentication types:

• Basic authentication
• API key authentication
• Bearer authentication

When you upload an OpenAPI definition, Burp Scanner automatically detects authentication methods that are linked to specific endpoints. You can add credentials for these methods. You can also add authentication methods that aren't detected in the API definition.

Viewing authentication details

Authentication methods are listed in the following details in the API details > Authentication tab:

• Type - The authentication mechanism. For example, basic or API key.
• Label - The identifier for the authentication method.
• Credentials - Credentials that you've added for the authentication method. For example, the username and password for basic authentication, or the key for API key authentication.

Authentication methods that were detected in the definition are labeled as either Detected or Unsupported on the list:

• Detected - Authentication types that can be used by Burp Scanner. These are:
  • Basic authentication
  • API key authentication
  • Bearer authentication
• Unsupported - Authentication types that Burp Scanner can't use. For example, OAuth authentication.

Managing authentication details

You can perform the following actions on the authentication methods listed in the table:

• Add credentials for the detected authentication methods. For more information, see Adding credentials for detected authentication methods.
• Add new, non-detected authentication methods. For more information, see Adding new authentication methods.
• Edit the authentication method credentials. To do this, double-click a list item.
• Remove authentication methods. To do this, select a list item, then click Delete. You can't delete entries that were detected in the API definition.

Adding credentials for detected authentication methods

Burp automatically identifies the authentication type and label for detected authentication methods, but you'll need to add credentials to use them in the scan. To add credentials:

1. In the Credentials column, click Add credentials. The Edit authentication type dialog opens.
2. Enter the credentials, depending on the authentication type:
   • For API keys, enter the API key.
   • For basic authentication, enter the username and password.
   • For bearer authentication, enter the full bearer token.
3. Click Save.

The credentials are added to the Credentials column in the list. When you start the scan, they are added to API requests to the endpoints that they're linked to in the API definition.

Adding new authentication methods

To add new, non-detected authentication methods:

1. Click New. The Add authentication method dialog opens.
2. From the Select authentication method drop-down, choose the authentication type you want to add. If you select API key, use the Add to drop-down to select whether to add the key to the request header, cookie, or query parameter.
3. Add a unique Label for the authentication method.
4. Enter the credentials, depending on the authentication type:
   • For API keys, enter the name of the header, cookie, or query parameter, and provide the key value.
   • For basic authentication, enter the username and password.
   • For bearer authentication, enter the full bearer token.
5. Click Save.

The new authentication method is added to the list. When you start the scan, the authentication credentials are added to all API requests, except for requests with conflicting authentication credentials from a detected method. For more information, see Conflicting authentication methods.

How Burp Scanner applies authentication credentials

When you start a scan, Burp Scanner adds the authentication credentials to requests as follows:

• Credentials for detected authentication methods are added to requests to endpoints that they're linked to in the API definition.
• Credentials for added authentication methods are applied to all other requests. They're also added to requests that include credentials for detected methods, so long as the two sets of credentials aren't in conflict.

Conflicting authentication methods

In some situations, authentication methods may conflict. If conflicting credentials are sent in the same request, then the server may receive mixed or incorrect authentication information, potentially invalidating the request.

For example, this occurs when:

• Multiple basic or bearer methods are used, as they both use the Authorization header.
• Multiple API key methods use the same header or cookie name.

Burp Scanner manages these situations in the following ways:

• You can't save a new authentication method that conflicts with an earlier added method.
• You can add methods that conflict with detected methods. However, Burp Scanner only uses one method per request:
  • For requests to endpoints that are linked to the detected method, the detected method is used.
  • For all other requests, the added method is used.