Guides

Authentication

How to authenticate your site before scanning.

Unlighthouse is built to support scanning sites that require authentication.

Basic Authentication

To use basic authentication, provide the auth option in your configuration file:

// unlighthouse.config.ts
export default {
  auth: {
    username: 'username',
    password: 'password',
  },
}

Alternatively, you can provide the --auth flag to the CLI.

unlighthouse --site <your-site> --auth username:password

If you can authenticate your session using cookies, use the cookies option in your configuration file:

// unlighthouse.config.ts
export default {
  cookies: [
    {
      name: 'my-jwt-token',
      value: '<token>',
      // optional extras
      domain: 'your-site.com',
      path: '/',
      httpOnly: false,
      secure: false,
      sameSite: 'Lax',
    },
  ],
}

Alternatively, you can provide the --cookies flag to the CLI.

unlighthouse --site <your-site> --cookies "my-jwt-token=<token>"

You can provide multiple cookies by separating them with a ;.

unlighthouse --site <your-site> --cookies my-jwt-token=<token>;my-other-cookie=value

Custom Headers Authentication

If providing cookies or basic auth is not enough, you can provide custom headers to be sent with each request.

To use custom headers, provide the extraHeaders option in your configuration file:

// unlighthouse.config.ts
export default {
  extraHeaders: {
    'x-custom-auth': '<token>>',
  },
}

Alternatively, you can provide the --extra-headers flag to the CLI.

unlighthouse --site <your-site> --extra-headers x-custom-header:custom-value

You can provide multiple headers by separating them with a ,.

unlighthouse --site <your-site> --extra-headers x-custom-header:custom-value,x-other-header:other-value

Query Params

If you can configure your authentication using query params, then you can provide them using the defaultQueryParams option in your configuration file:

// unlighthouse.config.ts
export default {
  defaultQueryParams: {
    auth: '<token>'
  }
}

Alternatively, you can provide the --default-query-params flag to the CLI.

unlighthouse --site <your-site> --default-query-params auth=<token>,foo=bar

Local Storage

If you can configure your authentication using local storage, then you can provide them using the localStorage option in your configuration file:

// unlighthouse.config.ts
export default {
  localStorage: {
    auth: '<token>'
  }
}

Programmatic Usage

You can also use control Puppeteer programmatically before the page is scanned using a config file. This is more experimental, and you may run into issues.

You can see an example here:

// unlighthouse.config.ts
export default {
  hooks: {
    async authenticate(page) {
      // login to the page
      await page.goto('https://example.com/login')
      const emailInput = await page.$('input[type="email"]')
      await emailInput.type('admin@example.com')
      const passwordInput = await page.$('input[type="password"]')
      await passwordInput.type('password')
      await Promise.all([
        page.$eval('.login-form', form => form.submit()),
        page.waitForNavigation(),
      ])
    },
  },
}

Troubleshooting

If you're having trouble authenticating, you can use the debug: true and headless: false, flags to see what's happening.

// unlighthouse.config.ts
export default {
  debug: true,
  // show the browser window
  puppeteerOptions: {
    headless: false,
  },
  // only run a single scan at a time
  puppeteerClusterOptions: {
    maxConcurrency: 1,
  },
}