--- title: "HTTP Authentication" description: "HTTP Authentication" url: https://docs.stackhawk.com/hawkscan/authenticated-scanning/http-authentication/ --- # HTTP Authentication ## Overview HTTP authentication is a form of authentication where a server will issue a challenge to a client request and the client will provides a user’s credentials in the header of the request. The `authentication` section of the `stackhawk.yml` will have 4 parts: 1. Logged in/out indicators - How HawkScan checks it is logged in throughout the scan. 2. Auth(N) - Your form type and login credentials. 3. Auth(Z) - How you maintain the session. Either a Cookie or Token. 4. Test Path - How HawkScan sees if it successfully logged in Make sure your file has all 4 of these parts filled out. ### YAML by HTTP Type #### NTLM Authentication: ```yaml title="stackhawk.yml" app: applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX env: Test host: ${APP_HOST:http://localhost:3000} antiCsrfParam: __RequestVerificationToken authentication: # Paths that HawkScan checks to see if it is still logged in during the scan loggedInIndicator: "HTTP.*2[0-9][0-9]\\s*O[kK](\\s*)|HTTP.*3[0-9][0-9].*" # Change me loggedOutIndicator: "HTTP.*4[0-9][0-9](\\s*)Unauthorized.*" # Change me # Auth(N) HTTP Authentication usernamePassword: type: HTTP loginPath: /login # Page behind NTLM Authentication usernameField: user # Field name for the account username/email passwordField: password # Field name for the password scanUsername: ${SCAN_USERNAME} # Inject variable at runtime or place your username here scanPassword: ${SCAN_PASSWORD} # Inject variable at runtime or place your password here realm: "My Realm" # The realm protection space for your ntlm authentication # (REQUIRED) Add your Auth(Z) here. Either Cookie or Token tokenAuthorization: type: HEADER value: Authorization tokenType: NTLM # A path that can only be seen when successfully logged in. HawkScan will check this path to see if log in was successful testPath: path: /mysettings # Change me success: ".*200.*" requestMethod: GET ``` #### Basic Authentication: Basic authentication is very similar to NTLM authentication with the token type for the Authorization is specified as Basic ```yaml title="stackhawk.yml" # (REQUIRED) Add your Auth(Z) here. Either Cookie or Token tokenAuthorization: type: HEADER value: Authorization tokenType: BASIC ``` ### YAML Sections in Detail #### Giving HawkScan HTTP Credentials HawkScan best practices is using [environment variable runtime overrides](https://docs.stackhawk.com/hawkscan/configuration/extended-configuration/#environment-variable-runtime-overrides). This is the most secure way to keep valid credentials to your application secret. These can be pulled in from your run command or a stored secret in your pipeline. ```yaml title="stackhawk.yml" app: applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX env: Test host: ${APP_HOST:http://localhost:3000} authentication: usernamePassword: scanUsername: ${SCAN_USERNAME} scanPassword: ${SCAN_PASSWORD} ``` ### Maintaining the Session For HTTP authentication, the authorization is stored in the Authorization Header. The `tokenType` will determine what type of auth it is, e.g. Basic or in this example NTLM. Tokens: ```yaml title="stackhawk.yml" app: applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX env: Test host: ${APP_HOST:http://localhost:3000} authentication: tokenAuthorization: type: HEADER value: Authorization tokenType: NTLM ``` Logged In/Out Indicators Throughout the scan, HawkScan will check to see if it is still logged in by the `.loggedInIndicator` and `.loggedOutIndicator`. These are regex strings to match against http responses from requests in the web application. A `.loggedInIndicator` could be a “Log Out” or ”Sign Out” button a user would see if logged in. An example of a `.loggedOutIndicator` would be a “Log In” button on the sign in page. These can also leverage http status codes from the response. ```yaml title="stackhawk.yml" app: applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX env: Test host: ${APP_HOST:http://localhost:3000} authentication: loggedInIndicator: "HTTP.*2[0-9][0-9]\\s*O[kK](\\s*)|HTTP.*3[0-9][0-9].*" loggedOutIndicator: "HTTP.*4[0-9][0-9](\\s*)Unauthorized.*" ``` ## Example NTLM Authentication NTLM authentication is a multi legged authentication. The flow in the browser would be as such: 1. A user will visit a page and be challenged with providing a username and password. 2. The browser will store a hashed version of the password. 3. The browser will request to be connected to the server. 4. The server will respond with a nonce. 5. The browser then sends back the nonce encrypted with the user’s password hash for NTLMv1. NTLMV2 uses username and timestamp as well. #### Detailed Configuration You would want a `stackhawk.yml` configuration like this. ```yaml title="stackhawk.yml" app: applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX env: Test host: ${APP_HOST:http://localhost:3000} authentication: loggedInIndicator: "HTTP.*2[0-9][0-9]\\s*O[kK](\\s*)|HTTP.*3[0-9][0-9].*" loggedOutIndicator: "HTTP.*4[0-9][0-9](\\s*)Unauthorized.*" usernamePassword: type: HTTP loginPath: / usernameField: email passwordField: password scanUsername: ${SCAN_USERNAME} scanPassword: ${SCAN_PASSWORD} tokenAuthorization: type: HEADER value: Authorization tokenType: NTLM testPath: path: /mysettings success: ".*200.*" ``` The authentication request/response would then look something like. #### Auth Request ```text GET / HTTP/1.1 Host: localhost:3000 Authorization: NTLM TlRMTVNTUAABAAAABoIIAAAAAAAAAAAAAAAAAAAAAAA= Accept: */* ``` #### Challenge Response ```text HTTP/1.1 401 Unauthorized Content-Type: text/html; charset=us-ascii Server: Microsoft-HTTPAPI/2.0 WWW-Authenticate: NTLM TlRMTVNTUAACAAAADgAOADgAAAAGgooCCkHJ30o9RUcAAAAAAAAAAJAAkABGAAAACgBdWAAAAA9XSU5ERVYyMzAyRVZBTAIAHABXAEkATgBEAEUAVgAyADMAMAAyAEUAVgBBAEwAAQAcAFcASQBOAEQARQBWADIAMwAwADIARQBWAEEATAAEABwAVwBpAG4ARABlAHYAMgAzADAAMgBFAHYAYQBsAAMAHABXAGkAbgBEAGUAdgAyADMAMAAyAEUAdgBhAGwABwAIAIHxrhL+ctkBAAAAAA== ``` ### Authorized Request to `/mysettings` ```text GET / HTTP/1.1 Host: localhost:3000 Authorization: NTLM TlRMTVNTUAADAAAAGAAYAEAAAADAAMAAWAAAAAAAAAAYAQAABAAEABgBAAALAAsAHAEAAAAAAAAAAAAABoKKAk7QHf/4L8gXYkLkwTHVZ0nCgylcRISB+pANx6y5cDJDdh//qgd4ltYBAQAAAAAAAADdZBL+ctkBwoMpXESEgfoAAAAAAgAcAFcASQBOAEQARQBWADIAMwAwADIARQBWAEEATAABABwAVwBJAE4ARABFAFYAMgAzADAAMgBFAFYAQQBMAAQAHABXAGkAbgBEAGUAdgAyADMAMAAyAEUAdgBhAGwAAwAcAFcAaQBuAEQAZQB2ADIAMwAwADIARQB2AGEAbAAHAAgAgfGuEv5y2QEAAAAAAAAAAHVzZXJXT1JLU1RBVElPTg== Accept: */* ``` ### Authorized Response ```text HTTP/1.1 200 OK Transfer-Encoding: chunked Content-Type: text/html; charset=utf-8 Server: Microsoft-IIS/10.0 Persistent-Auth: true ``` Requests to protected routes like `/mysettings` will have the Authorization header added to each request. With the `type` header describing the token being as a request header, the `value` being the name of the header `Authorization`, and `tokenType` : `NTLM` prepended to the token. ## Example Basic Authentication Basic authentication is much more simple and just includes a base64 hash of the `username:password` in each request. #### Detailed Configuration You would want a `stackhawk.yml` configuration like this. ```yaml title="stackhawk.yml" app: applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX env: Test host: ${APP_HOST:http://localhost:3000} authentication: loggedInIndicator: "HTTP.*2[0-9][0-9]\\s*O[kK](\\s*)|HTTP.*3[0-9][0-9].*" loggedOutIndicator: "HTTP.*4[0-9][0-9](\\s*)Unauthorized.*" usernamePassword: type: HTTP loginPath: / usernameField: email passwordField: password scanUsername: ${SCAN_USERNAME} scanPassword: ${SCAN_PASSWORD} tokenAuthorization: type: HEADER value: Authorization tokenType: Basic testPath: path: /mysettings success: ".*200.*" ``` The authentication request/response would then look something like: #### Auth Request ```text GET / HTTP/1.1 Host: localhost:3000 Authorization: BASIC dXNlcjpwYXNzd29yZA== Accept: */* ``` Requests to protected routes like `/mysettings` will have the Authorization header added to each request. With the `type` header describing the token being as a request header, the `value` being the name of the header `Authorization`, and `tokenType` : `Basic` prepended to the token.