---
title: "Authenticated Scanning"
description: "Set up HawkScan to test behind login screens and discover vulnerabilities in protected application areas. "
url: https://docs.stackhawk.com/getting-started/authenticated-scan/
---

# Authenticated Scanning

Scan the protected parts of your application where the most critical vulnerabilities hide

## Why Authenticated Scanning Matters

Most applications hide their valuable functionality behind login screens. Without authentication, security scanners can only test public routes, missing the critical parts of your application where the most dangerous vulnerabilities often lurk. StackHawk’s authenticated scanning capabilities allow HawkScan to:

- Access protected routes and functionality
- Test authorization boundaries between different user roles
- Discover vulnerabilities in authenticated API endpoints
- Provide comprehensive security coverage of your application

## Getting Started with Authentication

Setting up authenticated scanning requires configuring HawkScan to handle your application’s specific authentication mechanism. This guide will help you:

- Identify your authentication type - Determine how your application handles login
- Configure your stackhawk.yml file - Add the necessary authentication parameters
- Run your first authenticated scan - Verify complete access to protected routes

### Understanding Your Authentication Method

Before configuring HawkScan, you need to understand how your application handles authentication. Most applications fall into one of these categories:

| Authentication Type | Common Examples | Best For |
| - | - | - |
| **Form-based Authentication** | Traditional username/password login forms | Applications with simple login pages |
| **OAuth/3rd Party** | Auth0, Okta, Keycloak, Firebase | Modern applications using identity providers |
| **Token-based Authentication** | JWT, Bearer tokens | APIs and single-page applications |
| **Cookie-based Authentication** | Session cookies | Traditional web applications |

See [Authenticated Scanning](https://docs.stackhawk.com/hawkscan/authenticated-scanning/) for detailed configuration options.

## Configuration Steps

### 1. Gather Required Information

For all authentication types, you’ll need:

- **Login Test Path**: A protected page that requires authentication
- **Logged In Indicator**: Text or pattern that confirms successful login
- **Logged Out Indicator**: Text or pattern that indicates no authentication

### 2. Configure Your Authentication Type

Add the appropriate section to your `stackhawk.yml` file based on your authentication method:

#### Form-based Authentication

```yaml
app:
  authentication:
    loggedInIndicator: "Welcome, User" # Text that appears when logged in
    loggedOutIndicator: "Login" # Text that appears when logged out
    testPath: /dashboard # A path that requires authentication
    usernamePassword:
      type: FORM
      username: ${HAWK_USERNAME} # Set as environment variable
      password: ${HAWK_PASSWORD} # Set as environment variable
      loginPath: /login
      submitSelector: "button[type='submit']" # CSS selector for login button
      usernameSelector: "#username" # CSS selector for username field
      passwordSelector: "#password" # CSS selector for password field
```

#### OAuth/3rd Party Authentication

> **Warning:** Some OAuth Flows Require Manual Steps
>
> Authorization Code, PKCE, Implicit, and SAML flows require human intervention and can’t be fully automated. Use [Token Injection](https://docs.stackhawk.com/hawkscan/authenticated-scanning/inject-multiple-cookies-and-tokens/) for these flows.

For OAuth providers like Auth0, Okta, or Keycloak, use the native `oauth` configuration:

```yaml
app:
  authentication:
    loggedInIndicator: "HTTP/[0-9]+.[0-9]+\\s+([2-3][0-9][0-9])"
    loggedOutIndicator: "HTTP/[0-9]+.[0-9]+\\s+(4[0-9][0-9])"
    oauth:
      parameters:
        tokenEndpoint: https://${YOUR_DOMAIN}/oauth/token
        grantType: client_credentials
      credentials:
        clientId: ${YOUR_CLIENT_ID}
        clientSecret: ${YOUR_CLIENT_SECRET}
    tokenExtraction:
      type: TOKEN_PATH
      value: access_token
    tokenAuthorization:
      type: HEADER
      value: Authorization
      tokenType: Bearer
    testPath:
      path: /api/private
      success: '.*200.*'
```

See [3rd Party OAuth](https://docs.stackhawk.com/hawkscan/authenticated-scanning/3rd-party-oauth/) for provider-specific examples.

#### Token Injection

```yaml
app:
  authentication:
    loggedInIndicator: "User Profile" # Text indicating successful login
    loggedOutIndicator: "Unauthorized" # Text indicating no authentication
    testPath: /api/profile # Protected path to verify authentication
    external:
      headers:
        - name: "Authorization"
          value: "Bearer ${API_TOKEN}"
```

## Running Your Authenticated Scan

Once configured, run HawkScan with your authentication settings:

```bash
# For configurations with environment variables
hawk scan --env-file .env 

# For basic configurations without environment variables
hawk scan
```

## Verifying Authentication Success

After running your scan, check for these indicators of successful authentication:

- HawkScan logs should show successful login and authentication
- The scan results should include protected routes
- The “Coverage” tab in the StackHawk Platform should show authenticated pages

## Troubleshooting Authentication

If your authentication isn’t working:

- Check the HawkScan logs for specific authentication errors
- Verify your login indicators are unique and reliable
- Ensure your authentication credentials are correct
- Test your login flow manually to confirm it works as expected

## Next Steps

- **[Authenticated Scanning Reference](https://docs.stackhawk.com/hawkscan/authenticated-scanning/)** - Detailed configuration options for all authentication types
- **[3rd Party OAuth Guide](https://docs.stackhawk.com/hawkscan/authenticated-scanning/3rd-party-oauth/)** - Provider-specific examples for Auth0, Okta, Keycloak, and Firebase
- **[Example Configurations](https://github.com/kaakaww/hawkscan-examples)** - Sample scripts and YAML configs on GitHub