Security Tools

When you need to declare dependencies with OAuth2 scopes you use Security().

But you still need to define what is the dependable, the callable that you pass as a parameter to Depends() or Security().

There are multiple tools that you can use to create those dependables, and they get integrated into OpenAPI so they are shown in the automatic docs UI, they can be used by automatically generated clients and SDKs, etc.

You can import them from fastapi.security:

  1. from fastapi.security import (
  2.     APIKeyCookie,
  3.     APIKeyHeader,
  4.     APIKeyQuery,
  5.     HTTPAuthorizationCredentials,
  6.     HTTPBasic,
  7.     HTTPBasicCredentials,
  8.     HTTPBearer,
  9.     HTTPDigest,
  10.     OAuth2,
  11.     OAuth2AuthorizationCodeBearer,
  12.     OAuth2PasswordBearer,
  13.     OAuth2PasswordRequestForm,
  14.     OAuth2PasswordRequestFormStrict,
  15.     OpenIdConnect,
  16.     SecurityScopes,
  17. )

API Key Security Schemes

fastapi.security.APIKeyCookie

  1. APIKeyCookie(
  2.     *,
  3.     name,
  4.     scheme_name=None,
  5.     description=None,
  6.     auto_error=True
  7. )

Bases: APIKeyBase

API key authentication using a cookie.

This defines the name of the cookie that should be provided in the request with the API key and integrates that into the OpenAPI documentation. It extracts the key value sent in the cookie automatically and provides it as the dependency result. But it doesn’t define how to set that cookie.

Usage

Create an instance object and use that object as the dependency in Depends().

The dependency result will be a string containing the key value.

Example

  1. from fastapi import Depends, FastAPI
  2. from fastapi.security import APIKeyCookie
  4. app = FastAPI()
  6. cookie_scheme = APIKeyCookie(name="session")
  8. @app.get("/items/")
  9. async def read_items(session: str = Depends(cookie_scheme)):
  10.     return {"session": session}
PARAMETERDESCRIPTION
name

Cookie name.

TYPE: str

scheme_name

Security scheme name.

It will be included in the generated OpenAPI (e.g. visible at /docs).

TYPE: Optional[str] DEFAULT: None

description

Security scheme description.

It will be included in the generated OpenAPI (e.g. visible at /docs).

TYPE: Optional[str] DEFAULT: None

auto_error

By default, if the cookie is not provided, APIKeyCookie will automatically cancel the request and send the client an error.

If auto_error is set to False, when the cookie 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, in a cookie or in an HTTP Bearer token).

TYPE: bool DEFAULT: True

Source code in fastapi/security/api_key.py

  1. 241
  2. 242
  3. 243
  4. 244
  5. 245
  6. 246
  7. 247
  8. 248
  9. 249
  10. 250
  11. 251
  12. 252
  13. 253
  14. 254
  15. 255
  16. 256
  17. 257
  18. 258
  19. 259
  20. 260
  21. 261
  22. 262
  23. 263
  24. 264
  25. 265
  26. 266
  27. 267
  28. 268
  29. 269
  30. 270
  31. 271
  32. 272
  33. 273
  34. 274
  35. 275
  36. 276
  37. 277
  38. 278
  39. 279
  40. 280
  41. 281
  42. 282
  43. 283
  44. 284
  45. 285
  46. 286
  47. 287
  48. 288
  49. 289
  50. 290
  1. def init(
  2.     self,
  3.     ,
  4.     name: Annotated[str, Doc(“Cookie name.”)],
  5.     scheme_name: Annotated[
  6.         Optional[str],
  7.         Doc(
  8.             “””
  9.             Security scheme name.
  11.             It will be included in the generated OpenAPI (e.g. visible at /docs).
  12.             “””
  13.         ),
  14.     ] = None,
  15.     description: Annotated[
  16.         Optional[str],
  17.         Doc(
  18.             “””
  19.             Security scheme description.
  21.             It will be included in the generated OpenAPI (e.g. visible at /docs).
  22.             “””
  23.         ),
  24.     ] = None,
  25.     auto_error: Annotated[
  26.         bool,
  27.         Doc(
  28.             “””
  29.             By default, if the cookie is not provided, APIKeyCookie will
  30.             automatically cancel the request and send the client an error.
  32.             If auto_error is set to False, when the cookie is not available,
  33.             instead of erroring out, the dependency result will be None.
  35.             This is useful when you want to have optional authentication.
  37.             It is also useful when you want to have authentication that can be
  38.             provided in one of multiple optional ways (for example, in a cookie or
  39.             in an HTTP Bearer token).
  40.             “””
  41.         ),
  42.     ] = True,
  43. ):
  44.     self.model: APIKey = APIKey(
  45.         *{“in”: APIKeyIn.cookie},  # type: ignore[arg-type]
  46.         name=name,
  47.         description=description,
  48.     )
  49.     self.schemename = schemename or self.class.__name
  50.     self.auto_error = auto_error

model instance-attribute

  1. model = APIKey(
  2.     **{"in": cookie}, name=name, description=description
  3. )

scheme_name instance-attribute

  1. scheme_name = scheme_name or __name__

auto_error instance-attribute

  1. auto_error = auto_error

fastapi.security.APIKeyHeader

  1. APIKeyHeader(
  2.     *,
  3.     name,
  4.     scheme_name=None,
  5.     description=None,
  6.     auto_error=True
  7. )

Bases: APIKeyBase

API key authentication using a header.

This defines the name of the header that should be provided in the request with the API key and integrates that into the OpenAPI documentation. It extracts the key value sent in the header automatically and provides it as the dependency result. But it doesn’t define how to send that key to the client.

Usage

Create an instance object and use that object as the dependency in Depends().

The dependency result will be a string containing the key value.

Example

  1. from fastapi import Depends, FastAPI
  2. from fastapi.security import APIKeyHeader
  4. app = FastAPI()
  6. header_scheme = APIKeyHeader(name="x-key")
  8. @app.get("/items/")
  9. async def read_items(key: str = Depends(header_scheme)):
  10.     return {"key": key}
PARAMETERDESCRIPTION
name

Header name.

TYPE: str

scheme_name

Security scheme name.

It will be included in the generated OpenAPI (e.g. visible at /docs).

TYPE: Optional[str] DEFAULT: None

description

Security scheme description.

It will be included in the generated OpenAPI (e.g. visible at /docs).

TYPE: Optional[str] DEFAULT: None

auto_error

By default, if the header is not provided, APIKeyHeader will automatically cancel the request and send the client an error.

If auto_error is set to False, when the 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, in a header or in an HTTP Bearer token).

TYPE: bool DEFAULT: True

Source code in fastapi/security/api_key.py

  1. 146
  2. 147
  3. 148
  4. 149
  5. 150
  6. 151
  7. 152
  8. 153
  9. 154
  10. 155
  11. 156
  12. 157
  13. 158
  14. 159
  15. 160
  16. 161
  17. 162
  18. 163
  19. 164
  20. 165
  21. 166
  22. 167
  23. 168
  24. 169
  25. 170
  26. 171
  27. 172
  28. 173
  29. 174
  30. 175
  31. 176
  32. 177
  33. 178
  34. 179
  35. 180
  36. 181
  37. 182
  38. 183
  39. 184
  40. 185
  41. 186
  42. 187
  43. 188
  44. 189
  45. 190
  46. 191
  47. 192
  48. 193
  49. 194
  50. 195
  1. def init(
  2.     self,
  3.     ,
  4.     name: Annotated[str, Doc(“Header name.”)],
  5.     scheme_name: Annotated[
  6.         Optional[str],
  7.         Doc(
  8.             “””
  9.             Security scheme name.
  11.             It will be included in the generated OpenAPI (e.g. visible at /docs).
  12.             “””
  13.         ),
  14.     ] = None,
  15.     description: Annotated[
  16.         Optional[str],
  17.         Doc(
  18.             “””
  19.             Security scheme description.
  21.             It will be included in the generated OpenAPI (e.g. visible at /docs).
  22.             “””
  23.         ),
  24.     ] = None,
  25.     auto_error: Annotated[
  26.         bool,
  27.         Doc(
  28.             “””
  29.             By default, if the header is not provided, APIKeyHeader will
  30.             automatically cancel the request and send the client an error.
  32.             If auto_error is set to False, when the header is not available,
  33.             instead of erroring out, the dependency result will be None.
  35.             This is useful when you want to have optional authentication.
  37.             It is also useful when you want to have authentication that can be
  38.             provided in one of multiple optional ways (for example, in a header or
  39.             in an HTTP Bearer token).
  40.             “””
  41.         ),
  42.     ] = True,
  43. ):
  44.     self.model: APIKey = APIKey(
  45.         *{“in”: APIKeyIn.header},  # type: ignore[arg-type]
  46.         name=name,
  47.         description=description,
  48.     )
  49.     self.schemename = schemename or self.class.__name
  50.     self.auto_error = auto_error

model instance-attribute

  1. model = APIKey(
  2.     **{"in": header}, name=name, description=description
  3. )

scheme_name instance-attribute

  1. scheme_name = scheme_name or __name__

auto_error instance-attribute

  1. auto_error = auto_error

fastapi.security.APIKeyQuery

  1. APIKeyQuery(
  2.     *,
  3.     name,
  4.     scheme_name=None,
  5.     description=None,
  6.     auto_error=True
  7. )

Bases: APIKeyBase

API key authentication using a query parameter.

This defines the name of the query parameter that should be provided in the request with the API key and integrates that into the OpenAPI documentation. It extracts the key value sent in the query parameter automatically and provides it as the dependency result. But it doesn’t define how to send that API key to the client.

Usage

Create an instance object and use that object as the dependency in Depends().

The dependency result will be a string containing the key value.

Example

  1. from fastapi import Depends, FastAPI
  2. from fastapi.security import APIKeyQuery
  4. app = FastAPI()
  6. query_scheme = APIKeyQuery(name="api_key")
  8. @app.get("/items/")
  9. async def read_items(api_key: str = Depends(query_scheme)):
  10.     return {"api_key": api_key}
PARAMETERDESCRIPTION
name

Query parameter name.

TYPE: str

scheme_name

Security scheme name.

It will be included in the generated OpenAPI (e.g. visible at /docs).

TYPE: Optional[str] DEFAULT: None

description

Security scheme description.

It will be included in the generated OpenAPI (e.g. visible at /docs).

TYPE: Optional[str] DEFAULT: None

auto_error

By default, if the query parameter is not provided, APIKeyQuery will automatically cancel the request and sebd the client an error.

If auto_error is set to False, when the query parameter 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, in a query parameter or in an HTTP Bearer token).

TYPE: bool DEFAULT: True

Source code in fastapi/security/api_key.py

  1.  47
  2.  48
  3.  49
  4.  50
  5.  51
  6.  52
  7.  53
  8.  54
  9.  55
  10.  56
  11.  57
  12.  58
  13.  59
  14.  60
  15.  61
  16.  62
  17.  63
  18.  64
  19.  65
  20.  66
  21.  67
  22.  68
  23.  69
  24.  70
  25.  71
  26.  72
  27.  73
  28.  74
  29.  75
  30.  76
  31.  77
  32.  78
  33.  79
  34.  80
  35.  81
  36.  82
  37.  83
  38.  84
  39.  85
  40.  86
  41.  87
  42.  88
  43.  89
  44.  90
  45.  91
  46.  92
  47.  93
  48.  94
  49.  95
  50.  96
  51.  97
  52.  98
  53.  99
  54. 100
  1. def init(
  2.     self,
  3.     ,
  4.     name: Annotated[
  5.         str,
  6.         Doc(“Query parameter name.”),
  7.     ],
  8.     scheme_name: Annotated[
  9.         Optional[str],
  10.         Doc(
  11.             “””
  12.             Security scheme name.
  14.             It will be included in the generated OpenAPI (e.g. visible at /docs).
  15.             “””
  16.         ),
  17.     ] = None,
  18.     description: Annotated[
  19.         Optional[str],
  20.         Doc(
  21.             “””
  22.             Security scheme description.
  24.             It will be included in the generated OpenAPI (e.g. visible at /docs).
  25.             “””
  26.         ),
  27.     ] = None,
  28.     auto_error: Annotated[
  29.         bool,
  30.         Doc(
  31.             “””
  32.             By default, if the query parameter is not provided, APIKeyQuery will
  33.             automatically cancel the request and sebd the client an error.
  35.             If auto_error is set to False, when the query parameter is not
  36.             available, instead of erroring out, the dependency result will be
  37.             None.
  39.             This is useful when you want to have optional authentication.
  41.             It is also useful when you want to have authentication that can be
  42.             provided in one of multiple optional ways (for example, in a query
  43.             parameter or in an HTTP Bearer token).
  44.             “””
  45.         ),
  46.     ] = True,
  47. ):
  48.     self.model: APIKey = APIKey(
  49.         *{“in”: APIKeyIn.query},  # type: ignore[arg-type]
  50.         name=name,
  51.         description=description,
  52.     )
  53.     self.schemename = schemename or self.class.__name
  54.     self.auto_error = auto_error

model instance-attribute

  1. model = APIKey(
  2.     **{"in": query}, name=name, description=description
  3. )

scheme_name instance-attribute

  1. scheme_name = scheme_name or __name__

auto_error instance-attribute

  1. auto_error = auto_error

HTTP Authentication Schemes

fastapi.security.HTTPBasic

  1. HTTPBasic(
  2.     *,
  3.     scheme_name=None,
  4.     realm=None,
  5.     description=None,
  6.     auto_error=True
  7. )

Bases: HTTPBase

HTTP Basic authentication.

Usage

Create an instance object and use that object as the dependency in Depends().

The dependency result will be an HTTPBasicCredentials object containing the username and the password.

Read more about it in the FastAPI docs for HTTP Basic Auth.

Example

  1. from typing import Annotated
  3. from fastapi import Depends, FastAPI
  4. from fastapi.security import HTTPBasic, HTTPBasicCredentials
  6. app = FastAPI()
  8. security = HTTPBasic()
  10. @app.get("/users/me")
  11. def read_current_user(credentials: Annotated[HTTPBasicCredentials, Depends(security)]):
  12.     return {"username": credentials.username, "password": credentials.password}
PARAMETERDESCRIPTION
scheme_name

Security scheme name.

It will be included in the generated OpenAPI (e.g. visible at /docs).

TYPE: Optional[str] DEFAULT: None

realm

HTTP Basic authentication realm.

TYPE: Optional[str] DEFAULT: None

description

Security scheme description.

It will be included in the generated OpenAPI (e.g. visible at /docs).

TYPE: Optional[str] DEFAULT: None

auto_error

By default, if the HTTP Basic authentication is not provided (a header), HTTPBasic will automatically cancel the request and send the client an error.

If auto_error is set to False, when the HTTP Basic authentication 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, in HTTP Basic authentication or in an HTTP Bearer token).

TYPE: bool DEFAULT: True

Source code in fastapi/security/http.py

  1. 130
  2. 131
  3. 132
  4. 133
  5. 134
  6. 135
  7. 136
  8. 137
  9. 138
  10. 139
  11. 140
  12. 141
  13. 142
  14. 143
  15. 144
  16. 145
  17. 146
  18. 147
  19. 148
  20. 149
  21. 150
  22. 151
  23. 152
  24. 153
  25. 154
  26. 155
  27. 156
  28. 157
  29. 158
  30. 159
  31. 160
  32. 161
  33. 162
  34. 163
  35. 164
  36. 165
  37. 166
  38. 167
  39. 168
  40. 169
  41. 170
  42. 171
  43. 172
  44. 173
  45. 174
  46. 175
  47. 176
  48. 177
  49. 178
  50. 179
  51. 180
  52. 181
  53. 182
  54. 183
  55. 184
  56. 185
  1. def init(
  2.     self,
  3.     *,
  4.     schemename: Annotated[
  5.         Optional[str],
  6.         Doc(
  7.             “””
  8.             Security scheme name.
  10.             It will be included in the generated OpenAPI (e.g. visible at /docs).
  11.             “””
  12.         ),
  13.     ] = None,
  14.     realm: Annotated[
  15.         Optional[str],
  16.         Doc(
  17.             “””
  18.             HTTP Basic authentication realm.
  19.             “””
  20.         ),
  21.     ] = None,
  22.     description: Annotated[
  23.         Optional[str],
  24.         Doc(
  25.             “””
  26.             Security scheme description.
  28.             It will be included in the generated OpenAPI (e.g. visible at /docs).
  29.             “””
  30.         ),
  31.     ] = None,
  32.     autoerror: Annotated[
  33.         bool,
  34.         Doc(
  35.             “””
  36.             By default, if the HTTP Basic authentication is not provided (a
  37.             header), HTTPBasic will automatically cancel the request and send the
  38.             client an error.
  40.             If auto_error is set to False, when the HTTP Basic authentication
  41.             is not available, instead of erroring out, the dependency result will
  42.             be None.
  44.             This is useful when you want to have optional authentication.
  46.             It is also useful when you want to have authentication that can be
  47.             provided in one of multiple optional ways (for example, in HTTP Basic
  48.             authentication or in an HTTP Bearer token).
  49.             “””
  50.         ),
  51.     ] = True,
  52. ):
  53.     self.model = HTTPBaseModel(scheme=“basic”, description=description)
  54.     self.schemename = schemename or self.__class.__name
  55.     self.realm = realm
  56.     self.auto_error = auto_error

model instance-attribute

  1. model = HTTPBase(scheme='basic', description=description)

scheme_name instance-attribute

  1. scheme_name = scheme_name or __name__

realm instance-attribute

  1. realm = realm

auto_error instance-attribute

  1. auto_error = auto_error

fastapi.security.HTTPBearer

  1. HTTPBearer(
  2.     *,
  3.     bearerFormat=None,
  4.     scheme_name=None,
  5.     description=None,
  6.     auto_error=True
  7. )

Bases: HTTPBase

HTTP Bearer token authentication.

Usage

Create an instance object and use that object as the dependency in Depends().

The dependency result will be an HTTPAuthorizationCredentials object containing the scheme and the credentials.

Example

  1. from typing import Annotated
  3. from fastapi import Depends, FastAPI
  4. from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
  6. app = FastAPI()
  8. security = HTTPBearer()
  10. @app.get("/users/me")
  11. def read_current_user(
  12.     credentials: Annotated[HTTPAuthorizationCredentials, Depends(security)]
  13. ):
  14.     return {"scheme": credentials.scheme, "credentials": credentials.credentials}
PARAMETERDESCRIPTION
bearerFormat

Bearer token format.

TYPE: Optional[str] DEFAULT: None

scheme_name

Security scheme name.

It will be included in the generated OpenAPI (e.g. visible at /docs).

TYPE: Optional[str] DEFAULT: None

description

Security scheme description.

It will be included in the generated OpenAPI (e.g. visible at /docs).

TYPE: Optional[str] DEFAULT: None

auto_error

By default, if the HTTP Bearer token not provided (in an Authorization header), HTTPBearer will automatically cancel the request and send the client an error.

If auto_error is set to False, when the HTTP Bearer token 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, in an HTTP Bearer token or in a cookie).

TYPE: bool DEFAULT: True

Source code in fastapi/security/http.py

  1. 252
  2. 253
  3. 254
  4. 255
  5. 256
  6. 257
  7. 258
  8. 259
  9. 260
  10. 261
  11. 262
  12. 263
  13. 264
  14. 265
  15. 266
  16. 267
  17. 268
  18. 269
  19. 270
  20. 271
  21. 272
  22. 273
  23. 274
  24. 275
  25. 276
  26. 277
  27. 278
  28. 279
  29. 280
  30. 281
  31. 282
  32. 283
  33. 284
  34. 285
  35. 286
  36. 287
  37. 288
  38. 289
  39. 290
  40. 291
  41. 292
  42. 293
  43. 294
  44. 295
  45. 296
  46. 297
  47. 298
  48. 299
  1. def init(
  2.     self,
  3.     *,
  4.     bearerFormat: Annotated[Optional[str], Doc(“Bearer token format.”)] = None,
  5.     schemename: Annotated[
  6.         Optional[str],
  7.         Doc(
  8.             “””
  9.             Security scheme name.
  11.             It will be included in the generated OpenAPI (e.g. visible at /docs).
  12.             “””
  13.         ),
  14.     ] = None,
  15.     description: Annotated[
  16.         Optional[str],
  17.         Doc(
  18.             “””
  19.             Security scheme description.
  21.             It will be included in the generated OpenAPI (e.g. visible at /docs).
  22.             “””
  23.         ),
  24.     ] = None,
  25.     autoerror: Annotated[
  26.         bool,
  27.         Doc(
  28.             “””
  29.             By default, if the HTTP Bearer token not provided (in an
  30.             Authorization header), HTTPBearer will automatically cancel the
  31.             request and send the client an error.
  33.             If auto_error is set to False, when the HTTP Bearer token
  34.             is not available, instead of erroring out, the dependency result will
  35.             be None.
  37.             This is useful when you want to have optional authentication.
  39.             It is also useful when you want to have authentication that can be
  40.             provided in one of multiple optional ways (for example, in an HTTP
  41.             Bearer token or in a cookie).
  42.             “””
  43.         ),
  44.     ] = True,
  45. ):
  46.     self.model = HTTPBearerModel(bearerFormat=bearerFormat, description=description)
  47.     self.schemename = schemename or self.__class.__name
  48.     self.auto_error = auto_error

model instance-attribute

  1. model = HTTPBearer(
  2.     bearerFormat=bearerFormat, description=description
  3. )

scheme_name instance-attribute

  1. scheme_name = scheme_name or __name__

auto_error instance-attribute

  1. auto_error = auto_error

fastapi.security.HTTPDigest

  1. HTTPDigest(
  2.     *, scheme_name=None, description=None, auto_error=True
  3. )

Bases: HTTPBase

HTTP Digest authentication.

Usage

Create an instance object and use that object as the dependency in Depends().

The dependency result will be an HTTPAuthorizationCredentials object containing the scheme and the credentials.

Example

  1. from typing import Annotated
  3. from fastapi import Depends, FastAPI
  4. from fastapi.security import HTTPAuthorizationCredentials, HTTPDigest
  6. app = FastAPI()
  8. security = HTTPDigest()
  10. @app.get("/users/me")
  11. def read_current_user(
  12.     credentials: Annotated[HTTPAuthorizationCredentials, Depends(security)]
  13. ):
  14.     return {"scheme": credentials.scheme, "credentials": credentials.credentials}
PARAMETERDESCRIPTION
scheme_name

Security scheme name.

It will be included in the generated OpenAPI (e.g. visible at /docs).

TYPE: Optional[str] DEFAULT: None

description

Security scheme description.

It will be included in the generated OpenAPI (e.g. visible at /docs).

TYPE: Optional[str] DEFAULT: None

auto_error

By default, if the HTTP Digest not provided, HTTPDigest will automatically cancel the request and send the client an error.

If auto_error is set to False, when the HTTP Digest 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, in HTTP Digest or in a cookie).

TYPE: bool DEFAULT: True

Source code in fastapi/security/http.py

  1. 356
  2. 357
  3. 358
  4. 359
  5. 360
  6. 361
  7. 362
  8. 363
  9. 364
  10. 365
  11. 366
  12. 367
  13. 368
  14. 369
  15. 370
  16. 371
  17. 372
  18. 373
  19. 374
  20. 375
  21. 376
  22. 377
  23. 378
  24. 379
  25. 380
  26. 381
  27. 382
  28. 383
  29. 384
  30. 385
  31. 386
  32. 387
  33. 388
  34. 389
  35. 390
  36. 391
  37. 392
  38. 393
  39. 394
  40. 395
  41. 396
  42. 397
  43. 398
  44. 399
  45. 400
  46. 401
  1. def init(
  2.     self,
  3.     *,
  4.     schemename: Annotated[
  5.         Optional[str],
  6.         Doc(
  7.             “””
  8.             Security scheme name.
  10.             It will be included in the generated OpenAPI (e.g. visible at /docs).
  11.             “””
  12.         ),
  13.     ] = None,
  14.     description: Annotated[
  15.         Optional[str],
  16.         Doc(
  17.             “””
  18.             Security scheme description.
  20.             It will be included in the generated OpenAPI (e.g. visible at /docs).
  21.             “””
  22.         ),
  23.     ] = None,
  24.     autoerror: Annotated[
  25.         bool,
  26.         Doc(
  27.             “””
  28.             By default, if the HTTP Digest not provided, HTTPDigest will
  29.             automatically cancel the request and send the client an error.
  31.             If auto_error is set to False, when the HTTP Digest is not
  32.             available, instead of erroring out, the dependency result will
  33.             be None.
  35.             This is useful when you want to have optional authentication.
  37.             It is also useful when you want to have authentication that can be
  38.             provided in one of multiple optional ways (for example, in HTTP
  39.             Digest or in a cookie).
  40.             “””
  41.         ),
  42.     ] = True,
  43. ):
  44.     self.model = HTTPBaseModel(scheme=“digest”, description=description)
  45.     self.schemename = schemename or self.__class.__name
  46.     self.auto_error = auto_error

model instance-attribute

  1. model = HTTPBase(scheme='digest', description=description)

scheme_name instance-attribute

  1. scheme_name = scheme_name or __name__

auto_error instance-attribute

  1. auto_error = auto_error

HTTP Credentials

fastapi.security.HTTPAuthorizationCredentials

Bases: BaseModel

The HTTP authorization credentials in the result of using HTTPBearer or HTTPDigest in a dependency.

The HTTP authorization header value is split by the first space.

The first part is the scheme, the second part is the credentials.

For example, in an HTTP Bearer token scheme, the client will send a header like:

  1. Authorization: Bearer deadbeef12346

In this case:

  • scheme will have the value "Bearer"
  • credentials will have the value "deadbeef12346"

scheme instance-attribute

  1. scheme

The HTTP authorization scheme extracted from the header value.

credentials instance-attribute

  1. credentials

The HTTP authorization credentials extracted from the header value.

fastapi.security.HTTPBasicCredentials

Bases: BaseModel

The HTTP Basic credendials given as the result of using HTTPBasic in a dependency.

Read more about it in the FastAPI docs for HTTP Basic Auth.

username instance-attribute

  1. username

The HTTP Basic username.

password instance-attribute

  1. password

The HTTP Basic password.

OAuth2 Authentication

fastapi.security.OAuth2

  1. OAuth2(
  2.     *,
  3.     flows=OAuthFlowsModel(),
  4.     scheme_name=None,
  5.     description=None,
  6.     auto_error=True
  7. )

Bases: 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.

PARAMETERDESCRIPTION
flows

The dictionary of OAuth2 flows.

TYPE: Union[OAuthFlows, Dict[str, Dict[str, Any]]] DEFAULT: OAuthFlows()

scheme_name

Security scheme name.

It will be included in the generated OpenAPI (e.g. visible at /docs).

TYPE: Optional[str] DEFAULT: None

description

Security scheme description.

It will be included in the generated OpenAPI (e.g. visible at /docs).

TYPE: Optional[str] DEFAULT: None

auto_error

By default, if no HTTP Auhtorization 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).

TYPE: bool DEFAULT: True

Source code in fastapi/security/oauth2.py

  1. 321
  2. 322
  3. 323
  4. 324
  5. 325
  6. 326
  7. 327
  8. 328
  9. 329
  10. 330
  11. 331
  12. 332
  13. 333
  14. 334
  15. 335
  16. 336
  17. 337
  18. 338
  19. 339
  20. 340
  21. 341
  22. 342
  23. 343
  24. 344
  25. 345
  26. 346
  27. 347
  28. 348
  29. 349
  30. 350
  31. 351
  32. 352
  33. 353
  34. 354
  35. 355
  36. 356
  37. 357
  38. 358
  39. 359
  40. 360
  41. 361
  42. 362
  43. 363
  44. 364
  45. 365
  46. 366
  47. 367
  48. 368
  49. 369
  50. 370
  51. 371
  52. 372
  53. 373
  54. 374
  55. 375
  56. 376
  57. 377
  1. def init(
  2.     self,
  3.     *,
  4.     flows: Annotated[
  5.         Union[OAuthFlowsModel, Dict[str, Dict[str, Any]]],
  6.         Doc(
  7.             “””
  8.             The dictionary of OAuth2 flows.
  9.             “””
  10.         ),
  11.     ] = OAuthFlowsModel(),
  12.     schemename: Annotated[
  13.         Optional[str],
  14.         Doc(
  15.             “””
  16.             Security scheme name.
  18.             It will be included in the generated OpenAPI (e.g. visible at /docs).
  19.             “””
  20.         ),
  21.     ] = None,
  22.     description: Annotated[
  23.         Optional[str],
  24.         Doc(
  25.             “””
  26.             Security scheme description.
  28.             It will be included in the generated OpenAPI (e.g. visible at /docs).
  29.             “””
  30.         ),
  31.     ] = None,
  32.     autoerror: Annotated[
  33.         bool,
  34.         Doc(
  35.             “””
  36.             By default, if no HTTP Auhtorization header is provided, required for
  37.             OAuth2 authentication, it will automatically cancel the request and
  38.             send the client an error.
  40.             If auto_error is set to False, when the HTTP Authorization header
  41.             is not available, instead of erroring out, the dependency result will
  42.             be None.
  44.             This is useful when you want to have optional authentication.
  46.             It is also useful when you want to have authentication that can be
  47.             provided in one of multiple optional ways (for example, with OAuth2
  48.             or in a cookie).
  49.             “””
  50.         ),
  51.     ] = True,
  52. ):
  53.     self.model = OAuth2Model(
  54.         flows=cast(OAuthFlowsModel, flows), description=description
  55.     )
  56.     self.schemename = schemename or self.__class.__name
  57.     self.auto_error = auto_error

model instance-attribute

  1. model = OAuth2(
  2.     flows=cast(OAuthFlows, flows), description=description
  3. )

scheme_name instance-attribute

  1. scheme_name = scheme_name or __name__

auto_error instance-attribute

  1. auto_error = auto_error

fastapi.security.OAuth2AuthorizationCodeBearer

  1. OAuth2AuthorizationCodeBearer(
  2.     authorizationUrl,
  3.     tokenUrl,
  4.     refreshUrl=None,
  5.     scheme_name=None,
  6.     scopes=None,
  7.     description=None,
  8.     auto_error=True,
  9. )

Bases: [OAuth2](#fastapi.security.OAuth2 "fastapi.security.oauth2.OAuth2")

OAuth2 flow for authentication using a bearer token obtained with an OAuth2 code flow. An instance of it would be used as a dependency.

PARAMETERDESCRIPTION
authorizationUrl

TYPE: str

tokenUrl

The URL to obtain the OAuth2 token.

TYPE: str

refreshUrl

The URL to refresh the token and obtain a new one.

TYPE: Optional[str] DEFAULT: None

scheme_name

Security scheme name.

It will be included in the generated OpenAPI (e.g. visible at /docs).

TYPE: Optional[str] DEFAULT: None

scopes

The OAuth2 scopes that would be required by the path operations that use this dependency.

TYPE: Optional[Dict[str, str]] DEFAULT: None

description

Security scheme description.

It will be included in the generated OpenAPI (e.g. visible at /docs).

TYPE: Optional[str] DEFAULT: None

auto_error

By default, if no HTTP Auhtorization 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).

TYPE: bool DEFAULT: True

Source code in fastapi/security/oauth2.py

  1. 494
  2. 495
  3. 496
  4. 497
  5. 498
  6. 499
  7. 500
  8. 501
  9. 502
  10. 503
  11. 504
  12. 505
  13. 506
  14. 507
  15. 508
  16. 509
  17. 510
  18. 511
  19. 512
  20. 513
  21. 514
  22. 515
  23. 516
  24. 517
  25. 518
  26. 519
  27. 520
  28. 521
  29. 522
  30. 523
  31. 524
  32. 525
  33. 526
  34. 527
  35. 528
  36. 529
  37. 530
  38. 531
  39. 532
  40. 533
  41. 534
  42. 535
  43. 536
  44. 537
  45. 538
  46. 539
  47. 540
  48. 541
  49. 542
  50. 543
  51. 544
  52. 545
  53. 546
  54. 547
  55. 548
  56. 549
  57. 550
  58. 551
  59. 552
  60. 553
  61. 554
  62. 555
  63. 556
  64. 557
  65. 558
  66. 559
  67. 560
  68. 561
  69. 562
  70. 563
  71. 564
  72. 565
  73. 566
  74. 567
  75. 568
  76. 569
  77. 570
  78. 571
  79. 572
  80. 573
  81. 574
  82. 575
  83. 576
  84. 577
  85. 578
  86. 579
  87. 580
  88. 581
  1. def init(
  2.     self,
  3.     authorizationUrl: str,
  4.     tokenUrl: Annotated[
  5.         str,
  6.         Doc(
  7.             “””
  8.             The URL to obtain the OAuth2 token.
  9.             “””
  10.         ),
  11.     ],
  12.     refreshUrl: Annotated[
  13.         Optional[str],
  14.         Doc(
  15.             “””
  16.             The URL to refresh the token and obtain a new one.
  17.             “””
  18.         ),
  19.     ] = None,
  20.     schemename: Annotated[
  21.         Optional[str],
  22.         Doc(
  23.             “””
  24.             Security scheme name.
  26.             It will be included in the generated OpenAPI (e.g. visible at /docs).
  27.             “””
  28.         ),
  29.     ] = None,
  30.     scopes: Annotated[
  31.         Optional[Dict[str, str]],
  32.         Doc(
  33.             “””
  34.             The OAuth2 scopes that would be required by the path operations that
  35.             use this dependency.
  36.             “””
  37.         ),
  38.     ] = None,
  39.     description: Annotated[
  40.         Optional[str],
  41.         Doc(
  42.             “””
  43.             Security scheme description.
  45.             It will be included in the generated OpenAPI (e.g. visible at /docs).
  46.             “””
  47.         ),
  48.     ] = None,
  49.     autoerror: Annotated[
  50.         bool,
  51.         Doc(
  52.             “””
  53.             By default, if no HTTP Auhtorization header is provided, required for
  54.             OAuth2 authentication, it will automatically cancel the request and
  55.             send the client an error.
  57.             If auto_error is set to False, when the HTTP Authorization header
  58.             is not available, instead of erroring out, the dependency result will
  59.             be None.
  61.             This is useful when you want to have optional authentication.
  63.             It is also useful when you want to have authentication that can be
  64.             provided in one of multiple optional ways (for example, with OAuth2
  65.             or in a cookie).
  66.             “””
  67.         ),
  68.     ] = True,
  69. ):
  70.     if not scopes:
  71.         scopes = {}
  72.     flows = OAuthFlowsModel(
  73.         authorizationCode=cast(
  74.             Any,
  75.             {
  76.                 “authorizationUrl”: authorizationUrl,
  77.                 “tokenUrl”: tokenUrl,
  78.                 “refreshUrl”: refreshUrl,
  79.                 “scopes”: scopes,
  80.             },
  81.         )
  82.     )
  83.     super().__init(
  84.         flows=flows,
  85.         scheme_name=scheme_name,
  86.         description=description,
  87.         auto_error=auto_error,
  88.     )

model instance-attribute

  1. model = OAuth2(
  2.     flows=cast(OAuthFlows, flows), description=description
  3. )

scheme_name instance-attribute

  1. scheme_name = scheme_name or __name__

auto_error instance-attribute

  1. auto_error = auto_error

fastapi.security.OAuth2PasswordBearer

  1. OAuth2PasswordBearer(
  2.     tokenUrl,
  3.     scheme_name=None,
  4.     scopes=None,
  5.     description=None,
  6.     auto_error=True,
  7. )

Bases: [OAuth2](#fastapi.security.OAuth2 "fastapi.security.oauth2.OAuth2")

OAuth2 flow for authentication using a bearer token obtained with a password. An instance of it would be used as a dependency.

Read more about it in the FastAPI docs for Simple OAuth2 with Password and Bearer.

PARAMETERDESCRIPTION
tokenUrl

The URL to obtain the OAuth2 token. This would be the path operation that has OAuth2PasswordRequestForm as a dependency.

TYPE: str

scheme_name

Security scheme name.

It will be included in the generated OpenAPI (e.g. visible at /docs).

TYPE: Optional[str] DEFAULT: None

scopes

The OAuth2 scopes that would be required by the path operations that use this dependency.

TYPE: Optional[Dict[str, str]] DEFAULT: None

description

Security scheme description.

It will be included in the generated OpenAPI (e.g. visible at /docs).

TYPE: Optional[str] DEFAULT: None

auto_error

By default, if no HTTP Auhtorization 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).

TYPE: bool DEFAULT: True

Source code in fastapi/security/oauth2.py

  1. 400
  2. 401
  3. 402
  4. 403
  5. 404
  6. 405
  7. 406
  8. 407
  9. 408
  10. 409
  11. 410
  12. 411
  13. 412
  14. 413
  15. 414
  16. 415
  17. 416
  18. 417
  19. 418
  20. 419
  21. 420
  22. 421
  23. 422
  24. 423
  25. 424
  26. 425
  27. 426
  28. 427
  29. 428
  30. 429
  31. 430
  32. 431
  33. 432
  34. 433
  35. 434
  36. 435
  37. 436
  38. 437
  39. 438
  40. 439
  41. 440
  42. 441
  43. 442
  44. 443
  45. 444
  46. 445
  47. 446
  48. 447
  49. 448
  50. 449
  51. 450
  52. 451
  53. 452
  54. 453
  55. 454
  56. 455
  57. 456
  58. 457
  59. 458
  60. 459
  61. 460
  62. 461
  63. 462
  64. 463
  65. 464
  66. 465
  67. 466
  68. 467
  69. 468
  70. 469
  71. 470
  72. 471
  1. def init(
  2.     self,
  3.     tokenUrl: Annotated[
  4.         str,
  5.         Doc(
  6.             “””
  7.             The URL to obtain the OAuth2 token. This would be the path operation
  8.             that has OAuth2PasswordRequestForm as a dependency.
  9.             “””
  10.         ),
  11.     ],
  12.     schemename: Annotated[
  13.         Optional[str],
  14.         Doc(
  15.             “””
  16.             Security scheme name.
  18.             It will be included in the generated OpenAPI (e.g. visible at /docs).
  19.             “””
  20.         ),
  21.     ] = None,
  22.     scopes: Annotated[
  23.         Optional[Dict[str, str]],
  24.         Doc(
  25.             “””
  26.             The OAuth2 scopes that would be required by the path operations that
  27.             use this dependency.
  28.             “””
  29.         ),
  30.     ] = None,
  31.     description: Annotated[
  32.         Optional[str],
  33.         Doc(
  34.             “””
  35.             Security scheme description.
  37.             It will be included in the generated OpenAPI (e.g. visible at /docs).
  38.             “””
  39.         ),
  40.     ] = None,
  41.     autoerror: Annotated[
  42.         bool,
  43.         Doc(
  44.             “””
  45.             By default, if no HTTP Auhtorization header is provided, required for
  46.             OAuth2 authentication, it will automatically cancel the request and
  47.             send the client an error.
  49.             If auto_error is set to False, when the HTTP Authorization header
  50.             is not available, instead of erroring out, the dependency result will
  51.             be None.
  53.             This is useful when you want to have optional authentication.
  55.             It is also useful when you want to have authentication that can be
  56.             provided in one of multiple optional ways (for example, with OAuth2
  57.             or in a cookie).
  58.             “””
  59.         ),
  60.     ] = True,
  61. ):
  62.     if not scopes:
  63.         scopes = {}
  64.     flows = OAuthFlowsModel(
  65.         password=cast(Any, {“tokenUrl”: tokenUrl, “scopes”: scopes})
  66.     )
  67.     super().__init(
  68.         flows=flows,
  69.         scheme_name=scheme_name,
  70.         description=description,
  71.         auto_error=auto_error,
  72.     )

model instance-attribute

  1. model = OAuth2(
  2.     flows=cast(OAuthFlows, flows), description=description
  3. )

scheme_name instance-attribute

  1. scheme_name = scheme_name or __name__

auto_error instance-attribute

  1. auto_error = auto_error

OAuth2 Password Form

fastapi.security.OAuth2PasswordRequestForm

  1. OAuth2PasswordRequestForm(
  2.     *,
  3.     grant_type=None,
  4.     username,
  5.     password,
  6.     scope="",
  7.     client_id=None,
  8.     client_secret=None
  9. )

This is a dependency class to collect the username and password as form data for an OAuth2 password flow.

The OAuth2 specification dictates that for a password flow the data should be collected using form data (instead of JSON) and that it should have the specific fields username and password.

All the initialization parameters are extracted from the request.

Read more about it in the FastAPI docs for Simple OAuth2 with Password and Bearer.

Example

  1. from typing import Annotated
  3. from fastapi import Depends, FastAPI
  4. from fastapi.security import OAuth2PasswordRequestForm
  6. app = FastAPI()
  8. @app.post("/login")
  9. def login(form_data: Annotated[OAuth2PasswordRequestForm, Depends()]):
  10.     data = {}
  11.     data["scopes"] = []
  12.     for scope in form_data.scopes:
  13.         data["scopes"].append(scope)
  14.     if form_data.client_id:
  15.         data["client_id"] = form_data.client_id
  16.     if form_data.client_secret:
  17.         data["client_secret"] = form_data.client_secret
  18.     return data

Note that for OAuth2 the scope items:read is a single scope in an opaque string. You could have custom internal logic to separate it by colon caracters (:) or similar, and get the two parts items and read. Many applications do that to group and organize permisions, you could do it as well in your application, just know that that it is application specific, it’s not part of the specification.

PARAMETERDESCRIPTION
grant_type

The OAuth2 spec says it is required and MUST be the fixed string “password”. Nevertheless, this dependency class is permissive and allows not passing it. If you want to enforce it, use instead the OAuth2PasswordRequestFormStrict dependency.

TYPE: Union[str, None] DEFAULT: None

username

username string. The OAuth2 spec requires the exact field name username.

TYPE: str

password

password string. The OAuth2 spec requires the exact field name `password”.

TYPE: str

scope

A single string with actually several scopes separated by spaces. Each scope is also a string.

For example, a single string with:

```python “items:read items:write users:read profile openid” ````

would represent the scopes:

  • items:read
  • items:write
  • users:read
  • profile
  • openid

TYPE: str DEFAULT: ‘’

client_id

If there’s a client_id, it can be sent as part of the form fields. But the OAuth2 specification recommends sending the client_id and client_secret (if any) using HTTP Basic auth.

TYPE: Union[str, None] DEFAULT: None

client_secret

If there’s a client_password (and a client_id), they can be sent as part of the form fields. But the OAuth2 specification recommends sending the client_id and client_secret (if any) using HTTP Basic auth.

TYPE: Union[str, None] DEFAULT: None

Source code in fastapi/security/oauth2.py

  1.  61
  2.  62
  3.  63
  4.  64
  5.  65
  6.  66
  7.  67
  8.  68
  9.  69
  10.  70
  11.  71
  12.  72
  13.  73
  14.  74
  15.  75
  16.  76
  17.  77
  18.  78
  19.  79
  20.  80
  21.  81
  22.  82
  23.  83
  24.  84
  25.  85
  26.  86
  27.  87
  28.  88
  29.  89
  30.  90
  31.  91
  32.  92
  33.  93
  34.  94
  35.  95
  36.  96
  37.  97
  38.  98
  39.  99
  40. 100
  41. 101
  42. 102
  43. 103
  44. 104
  45. 105
  46. 106
  47. 107
  48. 108
  49. 109
  50. 110
  51. 111
  52. 112
  53. 113
  54. 114
  55. 115
  56. 116
  57. 117
  58. 118
  59. 119
  60. 120
  61. 121
  62. 122
  63. 123
  64. 124
  65. 125
  66. 126
  67. 127
  68. 128
  69. 129
  70. 130
  71. 131
  72. 132
  73. 133
  74. 134
  75. 135
  76. 136
  77. 137
  78. 138
  79. 139
  80. 140
  81. 141
  82. 142
  83. 143
  84. 144
  85. 145
  86. 146
  87. 147
  88. 148
  89. 149
  1. def init(
  2.     self,
  3.     ,
  4.     grant_type: Annotated[
  5.         Union[str, None],
  6.         Form(pattern=“password”),
  7.         Doc(
  8.             “””
  9.             The OAuth2 spec says it is required and MUST be the fixed string
  10.             “password”. Nevertheless, this dependency class is permissive and
  11.             allows not passing it. If you want to enforce it, use instead the
  12.             OAuth2PasswordRequestFormStrict dependency.
  13.             “””
  14.         ),
  15.     ] = None,
  16.     username: Annotated[
  17.         str,
  18.         Form(),
  19.         Doc(
  20.             “””
  21.             username string. The OAuth2 spec requires the exact field name
  22.             username.
  23.             “””
  24.         ),
  25.     ],
  26.     password: Annotated[
  27.         str,
  28.         Form(),
  29.         Doc(
  30.             “””
  31.             password string. The OAuth2 spec requires the exact field name
  32.             `password”.
  33.             “””
  34.         ),
  35.     ],
  36.     scope: Annotated[
  37.         str,
  38.         Form(),
  39.         Doc(
  40.             “””
  41.             A single string with actually several scopes separated by spaces. Each
  42.             scope is also a string.
  44.             For example, a single string with:
  46.             ```python
  47.             “items:read items:write users:read profile openid”
  48.             ````
  50.             would represent the scopes:
  52.              items:read
  53.              items:write
  54.              users:read
  55.              profile
  56.              openid
  57.             “””
  58.         ),
  59.     ] = “”,
  60.     client_id: Annotated[
  61.         Union[str, None],
  62.         Form(),
  63.         Doc(
  64.             “””
  65.             If there’s a client_id, it can be sent as part of the form fields.
  66.             But the OAuth2 specification recommends sending the client_id and
  67.             client_secret (if any) using HTTP Basic auth.
  68.             “””
  69.         ),
  70.     ] = None,
  71.     client_secret: Annotated[
  72.         Union[str, None],
  73.         Form(),
  74.         Doc(
  75.             “””
  76.             If there’s a client_password (and a client_id), they can be sent
  77.             as part of the form fields. But the OAuth2 specification recommends
  78.             sending the client_id and client_secret (if any) using HTTP Basic
  79.             auth.
  80.             “””
  81.         ),
  82.     ] = None,
  83. ):
  84.     self.grant_type = grant_type
  85.     self.username = username
  86.     self.password = password
  87.     self.scopes = scope.split()
  88.     self.client_id = client_id
  89.     self.client_secret = client_secret

grant_type instance-attribute

  1. grant_type = grant_type

username instance-attribute

  1. username = username

password instance-attribute

  1. password = password

scopes instance-attribute

  1. scopes = split()

client_id instance-attribute

  1. client_id = client_id

client_secret instance-attribute

  1. client_secret = client_secret

fastapi.security.OAuth2PasswordRequestFormStrict

  1. OAuth2PasswordRequestFormStrict(
  2.     grant_type,
  3.     username,
  4.     password,
  5.     scope="",
  6.     client_id=None,
  7.     client_secret=None,
  8. )

Bases: [OAuth2PasswordRequestForm](#fastapi.security.OAuth2PasswordRequestForm "fastapi.security.oauth2.OAuth2PasswordRequestForm")

This is a dependency class to collect the username and password as form data for an OAuth2 password flow.

The OAuth2 specification dictates that for a password flow the data should be collected using form data (instead of JSON) and that it should have the specific fields username and password.

All the initialization parameters are extracted from the request.

The only difference between OAuth2PasswordRequestFormStrict and OAuth2PasswordRequestForm is that OAuth2PasswordRequestFormStrict requires the client to send the form field grant_type with the value "password", which is required in the OAuth2 specification (it seems that for no particular reason), while for OAuth2PasswordRequestForm grant_type is optional.

Read more about it in the FastAPI docs for Simple OAuth2 with Password and Bearer.

Example

  1. from typing import Annotated
  3. from fastapi import Depends, FastAPI
  4. from fastapi.security import OAuth2PasswordRequestForm
  6. app = FastAPI()
  9. @app.post("/login")
  10. def login(form_data: Annotated[OAuth2PasswordRequestFormStrict, Depends()]):
  11.     data = {}
  12.     data["scopes"] = []
  13.     for scope in form_data.scopes:
  14.         data["scopes"].append(scope)
  15.     if form_data.client_id:
  16.         data["client_id"] = form_data.client_id
  17.     if form_data.client_secret:
  18.         data["client_secret"] = form_data.client_secret
  19.     return data

Note that for OAuth2 the scope items:read is a single scope in an opaque string. You could have custom internal logic to separate it by colon caracters (:) or similar, and get the two parts items and read. Many applications do that to group and organize permisions, you could do it as well in your application, just know that that it is application specific, it’s not part of the specification.

the OAuth2 spec says it is required and MUST be the fixed string “password”.

This dependency is strict about it. If you want to be permissive, use instead the OAuth2PasswordRequestForm dependency class.

username: username string. The OAuth2 spec requires the exact field name “username”. password: password string. The OAuth2 spec requires the exact field name “password”. scope: Optional string. Several scopes (each one a string) separated by spaces. E.g. “items:read items:write users:read profile openid” client_id: optional string. OAuth2 recommends sending the client_id and client_secret (if any) using HTTP Basic auth, as: client_id:client_secret client_secret: optional string. OAuth2 recommends sending the client_id and client_secret (if any) using HTTP Basic auth, as: client_id:client_secret

PARAMETERDESCRIPTION
grant_type

The OAuth2 spec says it is required and MUST be the fixed string “password”. This dependency is strict about it. If you want to be permissive, use instead the OAuth2PasswordRequestForm dependency class.

TYPE: str

username

username string. The OAuth2 spec requires the exact field name username.

TYPE: str

password

password string. The OAuth2 spec requires the exact field name `password”.

TYPE: str

scope

A single string with actually several scopes separated by spaces. Each scope is also a string.

For example, a single string with:

```python “items:read items:write users:read profile openid” ````

would represent the scopes:

  • items:read
  • items:write
  • users:read
  • profile
  • openid

TYPE: str DEFAULT: ‘’

client_id

If there’s a client_id, it can be sent as part of the form fields. But the OAuth2 specification recommends sending the client_id and client_secret (if any) using HTTP Basic auth.

TYPE: Union[str, None] DEFAULT: None

client_secret

If there’s a client_password (and a client_id), they can be sent as part of the form fields. But the OAuth2 specification recommends sending the client_id and client_secret (if any) using HTTP Basic auth.

TYPE: Union[str, None] DEFAULT: None

Source code in fastapi/security/oauth2.py

  1. 216
  2. 217
  3. 218
  4. 219
  5. 220
  6. 221
  7. 222
  8. 223
  9. 224
  10. 225
  11. 226
  12. 227
  13. 228
  14. 229
  15. 230
  16. 231
  17. 232
  18. 233
  19. 234
  20. 235
  21. 236
  22. 237
  23. 238
  24. 239
  25. 240
  26. 241
  27. 242
  28. 243
  29. 244
  30. 245
  31. 246
  32. 247
  33. 248
  34. 249
  35. 250
  36. 251
  37. 252
  38. 253
  39. 254
  40. 255
  41. 256
  42. 257
  43. 258
  44. 259
  45. 260
  46. 261
  47. 262
  48. 263
  49. 264
  50. 265
  51. 266
  52. 267
  53. 268
  54. 269
  55. 270
  56. 271
  57. 272
  58. 273
  59. 274
  60. 275
  61. 276
  62. 277
  63. 278
  64. 279
  65. 280
  66. 281
  67. 282
  68. 283
  69. 284
  70. 285
  71. 286
  72. 287
  73. 288
  74. 289
  75. 290
  76. 291
  77. 292
  78. 293
  79. 294
  80. 295
  81. 296
  82. 297
  83. 298
  84. 299
  85. 300
  86. 301
  87. 302
  88. 303
  89. 304
  90. 305
  1. def init(
  2.     self,
  3.     granttype: Annotated[
  4.         str,
  5.         Form(pattern=“password”),
  6.         Doc(
  7.             “””
  8.             The OAuth2 spec says it is required and MUST be the fixed string
  9.             “password”. This dependency is strict about it. If you want to be
  10.             permissive, use instead the OAuth2PasswordRequestForm dependency
  11.             class.
  12.             “””
  13.         ),
  14.     ],
  15.     username: Annotated[
  16.         str,
  17.         Form(),
  18.         Doc(
  19.             “””
  20.             username string. The OAuth2 spec requires the exact field name
  21.             username.
  22.             “””
  23.         ),
  24.     ],
  25.     password: Annotated[
  26.         str,
  27.         Form(),
  28.         Doc(
  29.             “””
  30.             password string. The OAuth2 spec requires the exact field name
  31.             password".</span>
  32. <span>            """</span>
  33.         <span>),</span>
  34.     <span>],</span>
  35.     <span>scope</span><span>:</span> <span>Annotated</span><span>[</span>
  36.         <span>str</span><span>,</span>
  37.         <span>Form</span><span>(),</span>
  38.         <span>Doc</span><span>(</span>
  39. <span>            </span><span>"""</span>
  40. <span>            A single string with actually several scopes separated by spaces. Each</span>
  41. <span>            scope is also a string.</span>
  43. <span>            For example, a single string with:</span>
  45. <span>            ```python</span>
  46. <span>            "items:read items:write users:read profile openid"</span>
  47. <span>            ````</span>
  49. <span>            would represent the scopes:</span>
  51. <span>            *items:read</span>
  52. <span>            *items:write</span>
  53. <span>            *users:read</span>
  54. <span>            *profile</span>
  55. <span>            *openid</span>
  56. <span>            """</span>
  57.         <span>),</span>
  58.     <span>]</span> <span>=</span> <span>""</span><span>,</span>
  59.     <span>client_id</span><span>:</span> <span>Annotated</span><span>[</span>
  60.         <span>Union</span><span>[</span><span>str</span><span>,</span> <span>None</span><span>],</span>
  61.         <span>Form</span><span>(),</span>
  62.         <span>Doc</span><span>(</span>
  63. <span>            </span><span>"""</span>
  64. <span>            If there's aclientid, it can be sent as part of the form fields.</span>
  65. <span>            But the OAuth2 specification recommends sending theclient_idand</span>
  66. <span>client_secret(if any) using HTTP Basic auth.</span>
  67. <span>            """</span>
  68.         <span>),</span>
  69.     <span>]</span> <span>=</span> <span>None</span><span>,</span>
  70.     <span>client_secret</span><span>:</span> <span>Annotated</span><span>[</span>
  71.         <span>Union</span><span>[</span><span>str</span><span>,</span> <span>None</span><span>],</span>
  72.         <span>Form</span><span>(),</span>
  73.         <span>Doc</span><span>(</span>
  74. <span>            </span><span>"""</span>
  75. <span>            If there's aclient_password(and aclient_id), they can be sent</span>
  76. <span>            as part of the form fields. But the OAuth2 specification recommends</span>
  77. <span>            sending theclient_idandclient_secret` (if any) using HTTP Basic
  78.             auth.
  79.             “””
  80.         ),
  81.     ] = None,
  82. ):
  83.     super().__init(
  84.         grant_type=grant_type,
  85.         username=username,
  86.         password=password,
  87.         scope=scope,
  88.         client_id=client_id,
  89.         client_secret=client_secret,
  90.     )

grant_type instance-attribute

  1. grant_type = grant_type

username instance-attribute

  1. username = username

password instance-attribute

  1. password = password

scopes instance-attribute

  1. scopes = split()

client_id instance-attribute

  1. client_id = client_id

client_secret instance-attribute

  1. client_secret = client_secret

OAuth2 Security Scopes in Dependencies

fastapi.security.SecurityScopes

  1. SecurityScopes(scopes=None)

This is a special class that you can define in a parameter in a dependency to obtain the OAuth2 scopes required by all the dependencies in the same chain.

This way, multiple dependencies can have different scopes, even when used in the same path operation. And with this, you can access all the scopes required in all those dependencies in a single place.

Read more about it in the FastAPI docs for OAuth2 scopes.

PARAMETERDESCRIPTION
scopes

This will be filled by FastAPI.

TYPE: Optional[List[str]] DEFAULT: None

Source code in fastapi/security/oauth2.py

  1. 611
  2. 612
  3. 613
  4. 614
  5. 615
  6. 616
  7. 617
  8. 618
  9. 619
  10. 620
  11. 621
  12. 622
  13. 623
  14. 624
  15. 625
  16. 626
  17. 627
  18. 628
  19. 629
  20. 630
  21. 631
  22. 632
  23. 633
  24. 634
  25. 635
  26. 636
  27. 637
  28. 638
  29. 639
  30. 640
  1. def init(
  2.     self,
  3.     scopes: Annotated[
  4.         Optional[List[str]],
  5.         Doc(
  6.             “””
  7.             This will be filled by FastAPI.
  8.             “””
  9.         ),
  10.     ] = None,
  11. ):
  12.     self.scopes: Annotated[
  13.         List[str],
  14.         Doc(
  15.             “””
  16.             The list of all the scopes required by dependencies.
  17.             “””
  18.         ),
  19.     ] = (
  20.         scopes or []
  21.     )
  22.     self.scope_str: Annotated[
  23.         str,
  24.         Doc(
  25.             “””
  26.             All the scopes required by all the dependencies in a single string
  27.             separated by spaces, as defined in the OAuth2 specification.
  28.             “””
  29.         ),
  30.     ] = “ “.join(self.scopes)

scopes instance-attribute

  1. scopes = scopes or []

The list of all the scopes required by dependencies.

scope_str instance-attribute

  1. scope_str = join(scopes)

All the scopes required by all the dependencies in a single string separated by spaces, as defined in the OAuth2 specification.

OpenID Connect

fastapi.security.OpenIdConnect

  1. OpenIdConnect(
  2.     *,
  3.     openIdConnectUrl,
  4.     scheme_name=None,
  5.     description=None,
  6.     auto_error=True
  7. )

Bases: SecurityBase

OpenID Connect authentication class. An instance of it would be used as a dependency.

PARAMETERDESCRIPTION
openIdConnectUrl

The OpenID Connect URL.

TYPE: str

scheme_name

Security scheme name.

It will be included in the generated OpenAPI (e.g. visible at /docs).

TYPE: Optional[str] DEFAULT: None

description

Security scheme description.

It will be included in the generated OpenAPI (e.g. visible at /docs).

TYPE: Optional[str] DEFAULT: None

auto_error

By default, if no HTTP Auhtorization header is provided, required for OpenID Connect 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 OpenID Connect or in a cookie).

TYPE: bool DEFAULT: True

Source code in fastapi/security/open_id_connect_url.py

  1. 17
  2. 18
  3. 19
  4. 20
  5. 21
  6. 22
  7. 23
  8. 24
  9. 25
  10. 26
  11. 27
  12. 28
  13. 29
  14. 30
  15. 31
  16. 32
  17. 33
  18. 34
  19. 35
  20. 36
  21. 37
  22. 38
  23. 39
  24. 40
  25. 41
  26. 42
  27. 43
  28. 44
  29. 45
  30. 46
  31. 47
  32. 48
  33. 49
  34. 50
  35. 51
  36. 52
  37. 53
  38. 54
  39. 55
  40. 56
  41. 57
  42. 58
  43. 59
  44. 60
  45. 61
  46. 62
  47. 63
  48. 64
  49. 65
  50. 66
  51. 67
  52. 68
  53. 69
  54. 70
  55. 71
  56. 72
  57. 73
  1. def init(
  2.     self,
  3.     *,
  4.     openIdConnectUrl: Annotated[
  5.         str,
  6.         Doc(
  7.             “””
  8.         The OpenID Connect URL.
  9.         “””
  10.         ),
  11.     ],
  12.     schemename: Annotated[
  13.         Optional[str],
  14.         Doc(
  15.             “””
  16.             Security scheme name.
  18.             It will be included in the generated OpenAPI (e.g. visible at /docs).
  19.             “””
  20.         ),
  21.     ] = None,
  22.     description: Annotated[
  23.         Optional[str],
  24.         Doc(
  25.             “””
  26.             Security scheme description.
  28.             It will be included in the generated OpenAPI (e.g. visible at /docs).
  29.             “””
  30.         ),
  31.     ] = None,
  32.     autoerror: Annotated[
  33.         bool,
  34.         Doc(
  35.             “””
  36.             By default, if no HTTP Auhtorization header is provided, required for
  37.             OpenID Connect authentication, it will automatically cancel the request
  38.             and send the client an error.
  40.             If auto_error is set to False, when the HTTP Authorization header
  41.             is not available, instead of erroring out, the dependency result will
  42.             be None.
  44.             This is useful when you want to have optional authentication.
  46.             It is also useful when you want to have authentication that can be
  47.             provided in one of multiple optional ways (for example, with OpenID
  48.             Connect or in a cookie).
  49.             “””
  50.         ),
  51.     ] = True,
  52. ):
  53.     self.model = OpenIdConnectModel(
  54.         openIdConnectUrl=openIdConnectUrl, description=description
  55.     )
  56.     self.schemename = schemename or self.__class.__name
  57.     self.auto_error = auto_error

model instance-attribute

  1. model = OpenIdConnect(
  2.     openIdConnectUrl=openIdConnectUrl,
  3.     description=description,
  4. )

scheme_name instance-attribute

  1. scheme_name = scheme_name or __name__

auto_error instance-attribute

  1. auto_error = auto_error