OAuth2 Class — fastapi Architecture

Architecture documentation for the OAuth2 class in oauth2.py from the fastapi codebase.

Class python Security

Entity Profile

Security→ OAuth2 Class — fastapi Architecture

Dependency Diagram

graph TD
  5023758b_9456_fafe_dbb4_30deaf7720ac["OAuth2"]
  28c8873a_5ba4_867f_0824_7abcac157a85["SecurityBase"]
  5023758b_9456_fafe_dbb4_30deaf7720ac -->|extends| 28c8873a_5ba4_867f_0824_7abcac157a85
  efdd0530_d49f_83d3_f1d5_e8884b1b9602["oauth2.py"]
  5023758b_9456_fafe_dbb4_30deaf7720ac -->|defined in| efdd0530_d49f_83d3_f1d5_e8884b1b9602
  8bbd2977_d668_7711_0e32_049fb7ad434f["__init__()"]
  5023758b_9456_fafe_dbb4_30deaf7720ac -->|method| 8bbd2977_d668_7711_0e32_049fb7ad434f
  8eebc79f_2a8c_2a4d_ce43_d94dc5a2eaf2["make_not_authenticated_error()"]
  5023758b_9456_fafe_dbb4_30deaf7720ac -->|method| 8eebc79f_2a8c_2a4d_ce43_d94dc5a2eaf2
  b560ad81_87a3_a7da_6bf8_f1bf0b4190a4["__call__()"]
  5023758b_9456_fafe_dbb4_30deaf7720ac -->|method| b560ad81_87a3_a7da_6bf8_f1bf0b4190a4

Relationship Graph

Source Code

fastapi/security/oauth2.py lines 330–430

class OAuth2(SecurityBase):
    """
    This is the base class for OAuth2 authentication, an instance of it would be used
    as a dependency. All other OAuth2 classes inherit from it and customize it for
    each OAuth2 flow.

    You normally would not create a new class inheriting from it but use one of the
    existing subclasses, and maybe compose them if you want to support multiple flows.

    Read more about it in the
    [FastAPI docs for Security](https://fastapi.tiangolo.com/tutorial/security/).
    """

    def __init__(
        self,
        *,
        flows: Annotated[
            Union[OAuthFlowsModel, dict[str, dict[str, Any]]],
            Doc(
                """
                The dictionary of OAuth2 flows.
                """
            ),
        ] = OAuthFlowsModel(),
        scheme_name: Annotated[
            Optional[str],
            Doc(
                """
                Security scheme name.

                It will be included in the generated OpenAPI (e.g. visible at `/docs`).
                """
            ),
        ] = None,
        description: Annotated[
            Optional[str],
            Doc(
                """
                Security scheme description.

                It will be included in the generated OpenAPI (e.g. visible at `/docs`).
                """
            ),
        ] = None,
        auto_error: Annotated[
            bool,
            Doc(
                """
                By default, if no HTTP Authorization header is provided, required for
                OAuth2 authentication, it will automatically cancel the request and
                send the client an error.

                If `auto_error` is set to `False`, when the HTTP Authorization header
                is not available, instead of erroring out, the dependency result will
                be `None`.

                This is useful when you want to have optional authentication.

                It is also useful when you want to have authentication that can be
                provided in one of multiple optional ways (for example, with OAuth2
                or in a cookie).
                """
            ),
        ] = True,
    ):
        self.model = OAuth2Model(
            flows=cast(OAuthFlowsModel, flows), description=description
        )
        self.scheme_name = scheme_name or self.__class__.__name__
        self.auto_error = auto_error

    def make_not_authenticated_error(self) -> HTTPException:
        """
        The OAuth 2 specification doesn't define the challenge that should be used,
        because a `Bearer` token is not really the only option to authenticate.

        But declaring any other authentication challenge would be application-specific
        as it's not defined in the specification.

        For practical reasons, this method uses the `Bearer` challenge by default, as
        it's probably the most common one.