Question:

How can I configure HawkScan to send my authorization token to the application being scanned according to that application's requirements?

Answer:

To get the right token to your application in the right format:

Determine the token management requirements of your application
1. how is a token obtained?
2. how is the token relayed to the application to prove authorization?
3. how is a session maintained (e.g., are refresh tokens involved)?
Configure the scanner to obtain an authorization token using one of the various authenticated scanning mechanisms
1. in complex scenarios, a custom authentication script may be needed for authentication
Use HawkScan's tokenExtraction configuration to extract the token from the authentication response
Use HawkScan's tokenAuthorization configuration to send the token to your application in one of various formats, such as:
- A bearer token sent in an Authorization header
- A token sent via a custom header that you name yourself
- A bearer token sent alongside other auth-related headers:
  - session cookies
  - X-ApiKey headers

Examples:

Example 1: Bearer token in an Authorization Header

Configuration:

    tokenAuthorization:
      type: HEADER
      value: Authorization
      tokenType: Bearer

Resulting Header:

Authorization: Bearer <tokenvalue>

Example 2: Token value in Authorization Header

Configuration:

    tokenAuthorization:
      type: HEADER
      value: Authorization

Resulting Header:

Authorization: <tokenvalue>

Example 3: Custom header with token value only

Configuration:

    tokenAuthorization:
      type: HEADER
      value: my-custom-token-header

Resulting Header:

my-custom-token-header: <tokenvalue>

Example 4: Bearer token alongside separate X-APIKey header

Token Configuration:

    tokenAuthorization:
      type: HEADER
      value: Authorization
      tokenType: Bearer

Replacer Configuration (from How to configure HawkScan to authenticate to applications using an API Key):

hawkAddOn:
  replacer:
    rules:
      - matchString: "X-APIKey"
        replacement: "abc123"
        replaceOnly: false

Resulting Headers:

Authorization: Bearer <tokenvalue>

X-APIKey: abc123

Example 5: Bearer token alongside cookies

Token Configuration:

    tokenAuthorization:
      type: HEADER
      value: Authorization
      tokenType: Bearer

Cookie Configuration:

app:
  sessionTokens:
    - cookie1
    - cookie2

Resulting Headers:

Authorization: Bearer <tokenvalue>

Cookie: cookie1=<cookie1value>; cookie2=<cookie2value>

Notes:

Indentation

When configuring tokens, indentation matters (since this is yml / yaml).

For app.authentication.tokenAuthorization:

app has no indentation
app.authentication is indented under app
app.authentication.tokenAuthorization is indented under app.authentication (hence the whitespace in the examples above)

For hawkAddOn.replacer:

hawkAddOn has no indentation
hawkAddOn.replacer is indented from hawkAddOn
replacer is an array, multiple entries are allowed in the fashion of:

    rules:
      - matchString: "apikey"
        replacement: "abc123"
        replaceOnly: false
      - matchString: "apikey2"
        replacement: "abc1234"
        replaceOnly: false

Cookies

For adding cookies alongside tokens:

when configuring cookies for cookie-only auth, they are configured in app.authentication.cookieAuthorization.cookieNames
when cookies are used in addition to a token, use tokenAuthorization for tokens and app.sessionTokens for cookies

Complex Scenarios

In some complex scenarios (e.g., token value changes on every request or is accompanied by custom logic), tokenAuthorization and tokenExtraction can be replaced by a custom script, such as:

a sessionScript with complex logic
an httpsender script which manipulates scanner messages on every request to the application

Authenticating HawkScan to applications using Basic Auth

Authenticating HawkScan to applications using an API Key

Authenticating HawkScan to applications using custom JSON payloads

Getting Started Guide: Authenticated Scanning

Authenticating HawkScan to applications using token injection