.. _envoy_v3_api_file_envoy/extensions/filters/http/credential_injector/v3/credential_injector.proto:

Credential Injector (proto)
===========================

.. _extension_envoy.filters.http.credential_injector:

This extension has the qualified name ``envoy.filters.http.credential_injector``


.. note::
  This extension is functional but has not had substantial production burn time,
  use only with this caveat.

  This extension has an unknown security posture and should only be
  used in deployments where both the downstream and upstream are
  trusted.

.. tip::
  This extension extends and can be used with the following extension category:


  - :ref:`envoy.filters.http <extension_category_envoy.filters.http>`



  This extension must be configured with one of the following type URLs:



  - :ref:`type.googleapis.com/envoy.extensions.filters.http.credential_injector.v3.CredentialInjector <envoy_v3_api_msg_extensions.filters.http.credential_injector.v3.CredentialInjector>`



.. warning::
   This API feature is currently work-in-progress. API features marked as work-in-progress are not considered stable, are not covered by the :ref:`threat model <arch_overview_threat_model>`, are not supported by the security team, and are subject to breaking changes. Do not use this feature without understanding each of the previous points.



Credential Injector :ref:`configuration overview <config_http_filters_credential_injector>`.




.. _envoy_v3_api_msg_extensions.filters.http.credential_injector.v3.CredentialInjector:

extensions.filters.http.credential_injector.v3.CredentialInjector
-----------------------------------------------------------------


:repo:`[extensions.filters.http.credential_injector.v3.CredentialInjector proto] <api/envoy/extensions/filters/http/credential_injector/v3/credential_injector.proto#L73>`

Credential Injector injects credentials into outgoing HTTP requests. The filter configuration is used to retrieve the credentials, or
they can be requested through the OAuth2 client credential grant. The credentials obtained are then injected into the Authorization header
of the proxied HTTP requests, utilizing either the Basic or Bearer scheme.

If the credential is not present or there was a failure injecting the credential, the request will fail with ``401 Unauthorized`` unless
``allow_request_without_credential`` is set to ``true``.

Notice: This filter is intended to be used for workload authentication, which means that the identity associated with the inserted credential
is considered as the identity of the workload behind the envoy proxy(in this case, envoy is typically deployed as a sidecar alongside that
workload). Please note that this filter does not handle end user authentication. Its purpose is solely to authenticate the workload itself.

Here is an example of CredentialInjector configuration with Generic credential, which injects an HTTP Basic Auth credential into the proxied requests.

.. code-block:: yaml

 overwrite: true
 credential:
   name: generic_credential
   typed_config:
     "@type": type.googleapis.com/envoy.extensions.http.injected_credentials.generic.v3.Generic
     credential:
       name: credential
       sds_config:
         path_config_source:
           path: credential.yaml
     header: Authorization

credential.yaml for Basic Auth:

.. code-block:: yaml

 resources:
 - "@type": "type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret"
   name: credential
   generic_secret:
     secret:
       inline_string: "Basic base64EncodedUsernamePassword"

It can also be configured to inject a Bearer token into the proxied requests.

credential.yaml for Bearer Token:

.. code-block:: yaml

 resources:
 - "@type": "type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret"
   name: credential
   generic_secret:
     secret:
       inline_string: "Bearer myToken"




.. code-block:: json
  :force:

  {
    "overwrite": ...,
    "allow_request_without_credential": ...,
    "credential": {...}
  }

.. _envoy_v3_api_field_extensions.filters.http.credential_injector.v3.CredentialInjector.overwrite:


overwrite
  (`bool <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) Whether to overwrite the value or not if the injected headers already exist.
  Value defaults to false.


.. _envoy_v3_api_field_extensions.filters.http.credential_injector.v3.CredentialInjector.allow_request_without_credential:


allow_request_without_credential
  (`bool <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) Whether to send the request to upstream if the credential is not present or if the credential injection
  to the request fails.

  By default, a request will fail with ``401 Unauthorized`` if the
  credential is not present or the injection of the credential to the request fails.
  If set to true, the request will be sent to upstream without the credential.


.. _envoy_v3_api_field_extensions.filters.http.credential_injector.v3.CredentialInjector.credential:


credential
  (:ref:`config.core.v3.TypedExtensionConfig <envoy_v3_api_msg_config.core.v3.TypedExtensionConfig>`, *REQUIRED*) The credential to inject into the proxied requests


  .. _extension_category_envoy.http.injected_credentials:

  .. tip::

    This extension category has the following known extensions:


    - :ref:`envoy.http.injected_credentials.generic <extension_envoy.http.injected_credentials.generic>`

    - :ref:`envoy.http.injected_credentials.oauth2 <extension_envoy.http.injected_credentials.oauth2>`