Professional

Configuring authentication for API scans

• Last updated: December 3, 2024

• Read time: 7 Minutes

This topic explains how to configure authentication for API-only scans in Burp Suite Professional.

Setting up authentication credentials enables Burp Scanner to access restricted API endpoints, which are often the most critical parts of your API's attack surface. Burp currently supports the following authentication types:

• Basic authentication

• Bearer tokens

• API keys

After you upload an API definition, you can view, add, and edit authentication methods in the API details > Authentication tab.

Detected authentication methods

When you upload an OpenAPI definition, Burp parses it to identify its endpoints and detect any specified authentication methods. If Burp detects authentication methods, it adds them to the API details > Authentication tab, and labels them:

• Detected: Supported by Burp. Can be used during the scan after adding credentials.

• Unsupported: Not supported by Burp. Can't be used during the scan.

Adding authentication methods

After you upload your API definition, you can manually add authentication methods for Burp to use when scanning your API.

Basic authentication

To add a basic authentication method:

1. Go to API details > Authentication.

2. Click New. The Add authentication window opens.

3. Type: Select Basic auth.

4. Label: Enter a unique identifier for this authentication method. Choose a name that makes it easy to recognize.

5. Add to: Specifies where Burp adds the credentials to requests it sends during the scan. This is always set to Authorization header for basic authentication.

6. Username: Enter a username for Burp to use during the scan.

7. Password: Enter a password for Burp to use during the scan.

8. Click Save. The new authentication method is now added to the list.

Bearer token

You can use fixed or dynamic tokens for bearer token authentication.

Fixed bearer token

Fixed tokens are tokens that do not expire. Select this option if your token has a long lifespan or doesn't expire. You provide the token manually, and Burp includes this exact token in relevant requests it sends during the scan.

To add a fixed bearer token:

1. Go to API details > Authentication.

2. Click New. The Add authentication window opens.

3. Type: Select Bearer token.

4. Label: Enter a unique identifier for this authentication method. Choose a name that makes it easy to recognize.

5. Add to: Specifies where Burp adds the token to requests it sends during the scan. This is always set to Authorization header for bearer tokens.

6. Token type: Select Fixed.

7. Token: Enter a token for Burp to use during the scan.

8. Click Save. The new authentication method is now added to the list.

Dynamic bearer token

Dynamic tokens are short-lived tokens that need to be renewed regularly. Select this option if your token has a limited lifespan. Burp automatically requests new tokens from the API at defined intervals during the scan, and includes the most recent token in relevant requests.

To add a dynamic bearer token:

1. Go to API details > Authentication.

2. Click New. The Add authentication window opens.

3. Type: Select Bearer token.

4. Label: Enter a unique identifier for this authentication method. Choose a name that makes it easy to recognize.

5. Add to: Specifies where Burp adds the token to requests it sends during the scan. This is always set to Authorization header for bearer tokens.

6. Token type: Select Dynamic.

7. Authentication service URL: Specify the URL of the endpoint used for retrieving or refreshing tokens from your API, for example: https://authservice.com/auth/token. Burp sends token retrieval requests to this URL.

8. Method: Select the method you want Burp to use for token retrieval requests.

9. Add header: If token retrieval requests require specific headers, click Add header, then enter its Name and Value. You can add multiple headers if needed.

10. Body: Enter the full request body required for token retrieval. Include all mandatory fields, and use the format specified by your authentication service.

11. Request new token every: Specify how often Burp requests a new token during the scan. Choose an interval based on how long your token remains valid. For example, if your token expires every hour, set this interval to 1 hour.

12. Token location: Specify where you want Burp to look when extracting the token from the authentication service's response:

    • If the token is in a JSON response, use dot-separated names to specify the exact field name. For example, token.access_token.

    • If the token is in an XML response, use an XPath expression to specify the token's location. For example, /response/token.

    • If you want to use the entire response as the token, leave this field blank.

13. Click Save. The new authentication method is now added to the list.

API key

To add an API key:

1. Go to API details > Authentication.

2. Click New. The Add authentication window opens.

3. Type: Select API key.

4. Label: Enter a unique identifier for this authentication method. Choose a name that makes it easy to recognize.

5. Add to: Specify where Burp adds the API key to requests it sends during the scan.

6. Name: Enter the name of the header, query parameter, or cookie you selected in the Add to drop-down.

7. Key: Enter an API key for Burp to use during the scan.

8. Click Save. The new authentication method is now added to the list.

Custom

The custom authentication method provides a flexible token-based authentication method. It enables you to choose where the token is placed in the request in a header, query parameter, or cookie when Burp sends it during the scan.

You can use fixed or dynamic tokens for custom authentication.

Fixed custom authentication method

Fixed tokens are tokens that do not expire. Select this option if your token has a long lifespan or doesn't expire. You provide the token manually, and Burp includes this exact token in relevant requests during the scan.

To add a fixed custom authentication method:

1. Go to API details > Authentication.

2. Click New. The Add authentication window opens.

3. Type: Select Custom.

4. Label: Enter a unique identifier for this authentication method. Choose a name that makes it easy to recognize.

5. Add to: Specify where Burp adds the token to requests it sends during the scan.

6. Name: Enter the name of the header, query parameter, or cookie you selected in the Add to drop-down.

7. Token type: Select Fixed.

8. Token: Enter a token for Burp to use during the scan.

9. Click Save. The new authentication method is now added to the list.

Dynamic custom authentication method

Dynamic tokens are short-lived tokens that need to be renewed regularly. Select this option if your token has a limited lifespan. Burp automatically requests new tokens from the API at defined intervals during the scan, and includes the most recent token in relevant requests during the scan.

To add a dynamic custom authentication method:

1. Go to API details > Authentication.

2. Click New. The Add authentication window opens.

3. Type: Select Custom.

4. Label: Enter a unique identifier for this authentication method. Choose a name that makes it easy to recognize.

5. Add to: Specify where Burp adds the token to requests it sends during the scan.

6. Name: Enter the name of the header, query parameter, or cookie you selected in the Add to drop-down.

7. Token type: Select Dynamic.

8. Authentication service URL: Specify the URL of the endpoint used for retrieving or refreshing tokens from your API, for example: https://authservice.com/auth/token. Burp sends token retrieval requests to this URL.

9. Method: Select the method you want Burp to use for token retrieval requests.

10. Add header: If token retrieval requests require specific headers, click Add header, then enter its Name and Value. You can add multiple headers if needed.

11. Body: Enter the full request body required for token retrieval. Include all mandatory fields, and use the format specified by your authentication service.

12. Request new token every: Specify how often Burp requests a new token during the scan. Choose an interval based on how long your token remains valid. For example, if your token expires every hour, set this interval to 1 hour.

13. Token location: Specify where you want Burp to look when extracting the token from the authentication service's response:

    • If the token is in a JSON response, use dot-separated names to specify the exact field name. For example, token.access_token.

    • If the token is in an XML response, use an XPath expression to specify the token's location. For example, /response/token.

    • If you want to use the entire response as the token, leave this field blank.

14. Click Save. The new authentication method is now added to the list.

Editing authentication credentials / methods

You can make changes to any supported authentication methods. These include methods labeled Detected, and methods that you added manually.

To edit an authentication method:

1. Select the method in the table and click Edit. This opens the Edit Authentication window.

2. Update the editable fields. The fields you can update depend on how the method was added:

   • If the method was detected by Burp, you can only edit its credentials.

   • If the method was added manually, you can edit any of your supplied configuration values.

3. Click Save to confirm your changes. The credentials are applied to the authentication method.

To learn how to configure the different types of authentication methods, including dynamic tokens, see: Adding authentication methods.

How Burp applies authentication credentials

When Burp scans your API, it adds authentication credentials to its requests. However, conflicts can arise if multiple methods target the same part of a request. For example:

• API keys may conflict if they share the same header or cookie name.

• Basic authentication and bearer tokens may clash because both send credentials in the Authorization header.

These conflicts can result in invalid credentials being sent, which causes the server to deny the request. To prevent this from happening, Burp applies the following logic:

Conflicts between manually added methods

Burp prevents you from saving new authentication methods that conflict with ones you've already added. This ensures that manually added methods don't interfere with each other.

Conflicts between detected methods and manually added methods

Burp allows you to manually add authentication methods, even if they conflict with Detected methods. This is because Detected methods are tied to specific endpoints, as defined in the OpenAPI specification. Manual methods, on the other hand, ensure that the scanner is authenticated for all other requests.

To avoid conflicts during the scan:

• Credentials for Detected methods are used in requests sent to their linked endpoints.

• Credentials for manual methods are used in requests sent to any other endpoints.