syntax = "proto3";

package envoy.extensions.filters.http.basic_auth.v3;

import "envoy/config/core/v3/base.proto";

import "udpa/annotations/sensitive.proto";
import "udpa/annotations/status.proto";
import "validate/validate.proto";

option java_package = "io.envoyproxy.envoy.extensions.filters.http.basic_auth.v3";
option java_outer_classname = "BasicAuthProto";
option java_multiple_files = true;
option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/basic_auth/v3;basic_authv3";
option (udpa.annotations.file_status).package_version_status = ACTIVE;

// [#protodoc-title: Basic Auth]
// Basic Auth :ref:`configuration overview <config_http_filters_basic_auth>`.
// [#extension: envoy.filters.http.basic_auth]

// Basic HTTP authentication.
//
// Example:
//
// .. code-block:: yaml
//
//   users:
//     inline_string: |-
//       user1:{SHA}hashed_user1_password
//       user2:{SHA}hashed_user2_password
//
// [#next-free-field: 6]
message BasicAuth {
  // Username-password pairs used to verify user credentials in the "Authorization" header.
  // The value needs to be the htpasswd format.
  // Reference to https://httpd.apache.org/docs/2.4/programs/htpasswd.html
  config.core.v3.DataSource users = 1 [(udpa.annotations.sensitive) = true];

  // This field specifies the header name to forward a successfully authenticated user to
  // the backend. The header will be added to the request with the username as the value.
  //
  // If it is not specified, the username will not be forwarded.
  string forward_username_header = 2
      [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME strict: false}];

  // This field specifies the request header to load the basic credential from.
  //
  // If it is not specified, the filter loads the credential from  the "Authorization" header.
  string authentication_header = 3
      [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME strict: false}];

  // If set to true, requests without Basic credentials (missing ``Authorization`` header, or
  // ``Authorization`` header with a non-``Basic`` scheme such as ``Bearer``) are allowed to pass through
  // without authentication. Requests that present ``Basic`` credentials are still fully validated.
  //
  // This is useful when combining BasicAuth with other authentication methods (e.g. JWT) to
  // achieve OR semantics: a request is accepted if any one configured auth method succeeds.
  // When ``allow_missing`` is ``true`` on all auth filters, pair it with an RBAC filter that checks
  // the dynamic metadata emitted by this filter (see ``emit_dynamic_metadata``) to ensure at
  // least one method authenticated the request. Requires ``emit_dynamic_metadata`` to be set to
  // ``true``.
  bool allow_missing = 4;

  // If set to ``true``, the filter emits dynamic metadata on successful authentication with key
  // ``username`` set to the authenticated username. The metadata is emitted under the namespace
  // corresponding to the name of this basic_auth filter as configured in the ``http_filters``
  // chain (e.g. if the filter is configured with name ``envoy.filters.http.basic_auth``, that is
  // the namespace that will be used).
  //
  // This is typically enabled together with ``allow_missing`` when combining BasicAuth with
  // other authentication methods (e.g. JWT) and using a downstream RBAC filter to enforce
  // OR semantics.
  bool emit_dynamic_metadata = 5;
}

// Extra settings that may be added to per-route configuration for
// a virtual host or a cluster.
message BasicAuthPerRoute {
  // Username-password pairs for this route.
  config.core.v3.DataSource users = 1
      [(validate.rules).message = {required: true}, (udpa.annotations.sensitive) = true];
}
