> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# login

> Parameters for authenticating with protected resources.

* **Type**: `object`

This property defines how the Crawler acquires a session to access protected content.

## Basic auth

The Crawler extracts the `Set-Cookie` response header from the login page,
stores that cookie and sends it in a `Cookie` header when crawling all pages of the website defined in the configuration.

<Note>
  This cookie is only retrieved at the beginning of each complete crawl.
  It won't be renewed automatically if it expires.
</Note>

The Crawler can interact with your login page in these ways:

* With a direct request with the credentials to your login endpoint, like a standard `curl` command
  ([`fetchRequest`](#param-fetch-request)).
* By emulating a web browser, loading your login page, entering the credentials and validating the login form
  ([`browserRequest`](#param-browser-request)).

## OAuth 2.0

The crawler supports the [OAuth 2.0 Client Credentials Grant flow](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4).
It performs an *Access Token Request* using the provided credentials,
stores the retrieved token in an `Authorization` header,
and sends it when crawling all pages of the website defined in the configuration.

<Note>
  This token is only retrieved at the beginning of each complete crawl.
  It won't be renewed automatically if it expires.
</Note>

Client authentication is performed by passing the client credentials (`client_id` and `client_secret`)
in the request body as described in [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1).

The following providers are supported.

* [Azure AD v1.0](https://learn.microsoft.com/en-us/previous-versions/azure/active-directory/azuread-dev/v1-oauth2-client-creds-grant-flow)

## Parameters

<ParamField body="fetchRequest" type="object">
  Manually create the login request.

  **Example:**

  ```js JavaScript icon=code theme={"system"}
  {
    login: {
      fetchRequest: {
        url: "https://example.com/secure/login-with-post",
        requestOptions: {
          method: "POST",
          headers: { "Content-Type": "application/x-www-form-urlencoded" },
          body: "id=my-id&password=my-password",
          timeout: 5000 // in milliseconds
        }
      }
    }
  }
  ```

  <Expandable>
    <ParamField body="fetchRequest.url" type="string" required>
      The URL to target for logging in.
    </ParamField>

    <ParamField body="fetchRequest.requestOptions" type="object">
      Options for the login request.

      <Expandable>
        <ParamField body="requestOptions.method" type="string" default="GET">
          HTTP request method to use for the login.
        </ParamField>

        <ParamField body="requestOptions.headers" type="object" default="{}">
          HTTP headers for the login request.

          <Expandable>
            <ParamField body="headers.Content-Type" type="string">
              `Content-Type` header for the login request.
            </ParamField>

            <ParamField body="headers.Authorization" type="string">
              `Authorization` header for the login request.
            </ParamField>

            <ParamField body="headers.Cookie" type="string">
              `Cookie` header for the login request.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="requestOptions.body" type="string">
          Request body for the login request as string.
        </ParamField>

        <ParamField body="requestOptions.timeout" type="number">
          Time in milliseconds to wait before canceling the login request.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="browserRequest" type="object">
  Use a web browser to visit your login page and validate the login form similar to a human.

  **Example:**

  ```js JavaScript icon=code theme={"system"}
  {
    login: {
      browserRequest: {
        url: "https://example.com/secure/login-page",
        username: "my-id",
        password: "my-password",
      }
    }
  }
  ```

  <Expandable>
    <ParamField body="browserRequest.url" type="string" required>
      URL of your login page.
      The page must have `input[type=text]` or `input[type=email]` elements for the username,
      and `input[type=password]` for the password.
    </ParamField>

    <ParamField body="browserRequest.username" type="string" required>
      Your username for logging in.
    </ParamField>

    <ParamField body="browserRequest.password" type="string" required>
      Your password for logging in.
    </ParamField>

    <ParamField body="browserRequest.waitTime" type="object">
      Shortest and longest time to wait before considering the login complete.

      <Expandable>
        <ParamField body="waitTime.min" type="number" default={0}>
          If the login finishes faster than this time,
          the browser remains open at least this long before returning the cookies.
        </ParamField>

        <ParamField body="waitTime.max" type="number" default={2000}>
          Maximum time to wait before returning the cookies.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="oauthRequest" type="object">
  Use the [OAuth 2.0 Client Credentials Grant flow](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) to generate an `Authorization` header.

  **Example:**

  ```js JavaScript icon=code theme={"system"}
  {
    login: {
      oauthRequest: {
        accessTokenRequest: {
          url: "https://example.com/oauth2/token",
          grant_type: "client_credentials",
          client_id: "my-client-id",
          client_secret: "my-client-secret",
          extraParameters: {
            resource: "https://protected.example.com/"
          }
        }
      }
    }
  }
  ```

  <Expandable>
    <ParamField body="oauthrequest.accessTokenRequest" type="object" required>
      Required parameters to perform the *Access token request*.

      <Expandable>
        <ParamField body="accessTokenRequest.client_id" type="string" required>
          The [client identifier](https://datatracker.ietf.org/doc/html/rfc6749#section-2.2).
        </ParamField>

        <ParamField body="accessTokenRequest.client_secret" type="string" required>
          The client secret.
        </ParamField>

        <ParamField body="accessTokenRequest.grant_type" type="string" required>
          Must be `client_credentials`.
        </ParamField>

        <ParamField body="accessTokenRequest.url" type="string" required>
          URL of your access token endpoint.
        </ParamField>

        <ParamField body="accessTokenRequest.extraParameters" type="object">
          Implementation-specific parameters that aren't part of RFC 6749.

          <Expandable>
            <ParamField body="extraParameters.resource" type="string">
              Required for [Azure AD v1.0](https://docs.microsoft.com/en-us/azure/active-directory/azuread-dev/v1-oauth2-client-creds-grant-flow#first-case-access-token-request-with-a-shared-secret) implementations.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="accessTokenRequest.scope" type="string">
          [Scope of the access request](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3).
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>