Professional

Configuring authentication for API scans

• Last updated: October 29, 2024

• Read time: 4 Minutes

You can configure authentication for your API definitions, enabling Burp Scanner to access restricted endpoints, expanding the attack surface Burp can test. Burp Scanner currently supports the following authentication types:

• Basic authentication
• API key authentication
• Bearer authentication

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.

For OpenAPI definitions, Burp automatically detects authentication methods when parsing the definition. These are listed in the API details > Authentication tab, where you can add credentials to enable Burp to use them during the scan. You can also add new authentication methods.

Authentication methods that were detected in the OpenAPI 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.

Burp doesn't currently detect authentication methods in SOAP WSDLs. You'll need to add authentication methods and their credentials to enable Burp to use them during the scan.

Managing authentication details

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

• Add credentials for authentication methods that Burp detected in Open API definitions. For more information, see Adding credentials for detected authentication methods.
• Add new authentication methods. For more information, see Adding new authentication methods.
• Edit 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 OpenAPI definitions.

Adding credentials for detected authentication methods

For OpenAPI definitions, Burp automatically identifies the 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 OpenAPI definition.

Adding new authentication methods

To add new 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 OpenAPI definition. Burp doesn't currently detect authentication methods in SOAP WSDLs.
• 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.
• For OpenAPI definitions, 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.