Authentication in scanned applications¶

Configuration¶

Authentication verification mechanism¶

Performs periodic verification of session validity using the configuration in JSON format.

The configuration contains an array of criteria for verifying the validity of the session. The mandatory fields are request, responseConditions with the nested mandatory fields url and statusCode respectively.

Regardless of its type, the criterion is considered fulfilled if and only if all the specified conditions are met. The number of verification rounds affects the authentication decision as follows:

the criterion is considered PASSED ⇔ authentication is considered failed if the criterion is not fulfilled N times in a row;
the criterion is considered FAILED ⇔ authentication is considered failed if the criterion is fulfilled N times in a row.

Field	Description
`kind`	Shows what the fulfillment of the criterion corresponds to — authentication passed or not. Allowed values: `FAILED`, `PASSED`
`request.url`	Contains the absolute URL of the criterion subject request
`request.method`	Contains the method of the criterion subject request (Default `GET`)
`request.headers`	Contains the criterion subject request headers in the key-value format `("Content-Type": "application/json")`
`request.body`	Contains the body of the criterion subject request
`responseConditions.statusCode`	Contains the HTTP status of the criterion subject response. Not equal ⇒ criterion is not fulfilled
`responseConditions.body`	Contains the regular expression for criterion subject response body matching. Unmatched regexp ⇒ criterion not fulfilled
`responseConditions.headers`	Contains the `(name, regexp)` pairs for criterion subject response headers matching. Any unmatched ⇒ criterion is not fulfilled
`interval`	Contains the time interval between criterion checks. Uses seconds with fractional part, e.g. 0.5s, 1s, 10s. (Default 10s)
`rounds`	Contains the number of criterion checks, to ensure that authorization has failed (Default 5)

Config example:

[
  {
    "kind": "PASSED",
    "request": {
      "url": "http://api.e-shop.com/profile"
    },
    "responseConditions": {
      "statusCode": 200,
      "headers": {
        "Content-Type": "application/json"
      }
    },
    "interval": "7s",
    "rounds": 3
  },
  {
    "kind": "FAILED",
    "request": {
      "url": "http://api.e-shop.com/"
    },
    "responseConditions": {
      "statusCode": 200,
      "body": ".*Unauthorized.*"
    },
    "interval": "1s",
    "rounds": 7
  },
  {
    "kind": "FAILED",
    "request": {
      "url": "http://api.e-shop.com/"
    },
    "responseConditions": {
      "statusCode": 403
    },
    "interval": "1s",
    "rounds": 7
  },
  {
    "kind": "PASSED",
    "request": {
      "method": "POST",
      "url": "http://api.e-shop.com/endpoint/",
      "headers": {
        "Content-Type": "application/json"
      },
      "body": "{\"data\": \"here\"}"
    },
    "responseConditions": {
      "statusCode": 200
    }
  }
]

Updating authentication data¶

Periodic refreshing of sessions is performed using the JSON config. This only works in conjunction with the authentication verification mechanism.

This config describes how to perform a HTTP request to refresh a session in any of its manifestations, and the way to configure new authorization parameters with refreshed data.

Field	Description
`request`	Contains the description of the HTTP request
`request.url`	Contains the absolute URL of the session-refresh endpoint. This field is mandatory
`request.method`	Contains the HTTP method of the session-refresh endpoint. (Default `GET`)
`request.headers`	Contains key-value pairs which specify additional headers for a session-refresh request, if needed
`request.body`	Contains a string representation of the HTTP body needed for a session-refresh request
`request.timeout`	Contains timeout configuration for session-refresh request. Uses seconds with fractional part, e.g. 0.5s, 1s, 10s. (Default 10s)
`responseExtractors`	Describes how to process the response of the session-refresh endpoint. It’s an array, in which each element describes a single strategy of extraction
`responseExtractors[].extractor`	Contains a regular expression in RE2 format, corresponding to the extracted data for the current element of the `responseExtractors` array. This field is mandatory for each element of the `responseExtractors` array. The regular expression searches for matches in the response body and headers in the format `Header-Key: Header-Value`
`responseExtractors[].proxyParams`	Contains a description of the hook which will be added after successful data extraction. Field is an object, which allows the `cookie`, `header`, `httpAuth` and `jsonReplacer` keys. The `cookie` and `header` objects allow the `name` key. `httpAuth` allows the `username` field. `jsonReplacer` allows the `path` key. All of the above objects also allow the `path`, `schema`, `hostname` and `port` keys, which contain additional information about proxy constraints. Values will be taken from the base URL of the scan if not specified. This field is mutually exclusive with `responseExtractors[].placeholderVariableName`
`responseExtractors[].proxyParams.[cookie\\|header].name`	Describes the name of the header or the cookie where the extracted data will be substituted. It is only used in objects generated by the `cookie` and `header` keys. This field is mutually exclusive with `responseExtractors[].proxyParams.httpAuth.username` and `responseExtractors[].proxyParams.jsonReplacer.path`
`responseExtractors[].proxyParams.httpAuth.username`	Describes the username for HTTP Basic where the extracted data will be substituted for a password. Only used in objects generated by the `httpAuth` key. This field is mutually exclusive with `responseExtractors[].proxyParams.[cookie\\|header].name` and `responseExtractors[].proxyParams.jsonReplacer.path`
`responseExtractors[].proxyParams.jsonReplacer.path`	Describes the path to the JSON keys to change the values using the extracted data. This field is mutually exclusive with `responseExtractors[].proxyParams.[cookie\\|header].name` and `responseExtractors[].proxyParams.httpAuth.username`
`responseExtractors[].placeholderVariableName`	Contains the name of the key where the extracted data will be stored. This data will be used in the next session-refresh request in the relevant templated parts of the HTTP request. Use case: changing the refresh token after each session refresh. This field is mutually exclusive with `responseExtractors[].proxyParams`
`responseExtractors[].valueTransformationTemplate`	Describes the context corresponding to the placeholder {{ .Matched }} the templated part of which is substituted for the extracted data. This context is displayed in the HTTP request to update the session in the placeholder corresponding to the placeholderVariableName value. Usage example: The extracted data should be used in the `Authorization` header, but the value is returned without the `Bearer` prefix. The context will look like `Bearer {{ .Matched }}`
`placeholdersInitValues`	Contains key-value pairs which will be used in the template rendering of the `request` field of the HTTP request. All key-value pairs must be filled in with initial values which will be used during the first session-refresh request. For the other session-refresh requests, values will be rewritten using the extracted data with the corresponding `responseExtractors[].placeholderVariableName` key
`dropHooksBeforeRefreshRequest`	Optional field. Indicates whether to drop the authentication data (proxy hooks) accumulated by the refresher before executing next HTTP request for a refresh. By default, authentication data is not dropped.

Config examples:

{
  "request": {
    "url": "http://example.com/login",
    "method": "POST",
    "body": "login=admin&password=secretpass"
  },
  "responseExtractors": [
    {
      "extractor": "Set-Cookie:.*session_token=(.*);",
      "proxyParams": {
        "cookie": {
          "name": "session_token"
        }
      }
    }
  ]
}

{
  "request": {
    "url": "http://api.example.com/refresh-with-token",
    "method": "POST",
    "body": "{\"authData\": {\"refreshToken\": \"{{ .RefreshToken }}\"}}"
  },
  "responseExtractors": [
    {
      "extractor": "{\"token\": \"(.*)\",}",
      "proxyParams": {
        "header": {
          "name": "X-Auth",
          "hostname": "api.example.com"
        }
      }
    },
    {
      "extractor": "\"authData\": {\"refreshToken\": \"(.*)\"}",
      "placeholderVariableName": "RefreshToken"
    }
  ],
  "placeholdersInitValues": {
    "RefreshToken": "c2712990-ec19-414b-8be0-8a66e9271253"
  }
}

{
  "request": {
    "url": "http://example.com/refresh-with-token",
    "method": "POST",
    "body": "{\"authData\": {\"refreshToken\": \"{{ .RefreshToken }}\"}}"
  },
  "responseExtractors": [
    {
      "extractor": "{\"token\": \"(.*)\"}",
      "proxyParams": {
        "header": {
          "name": "Authorization"
        }
      },
      "valueTransformationTemplate": "Bearer {{ .Matched }}"
    },
    {
      "extractor": "\"authData\": {\"refreshToken\": \"(.*)\"}",
      "placeholderVariableName": "RefreshToken"
    }
  ],
  "placeholdersInitValues": {
    "RefreshToken": "c2712990-ec19-414b-8be0-8a66e9271253"
  }
}