Merge 8f77416b76 into 76b324d95b

1 day ago · d5959ff31c
9 changed files with 426 additions and 0 deletions
--- a/docs/en/docs/advanced/security/api-key.md
+++ b/docs/en/docs/advanced/security/api-key.md
@ -0,0 +1,76 @@
+# API Key Authentication
+
+Another authentication method, particularly for machine-to-machine communication, is an API key. An API key is a string that the application will expect with each request from a particular client. The API key can be sent as a header, a cookie, or a query parameter.
+
+<!-- TODO: currently we return 403 in the implementation! discuss with @tiangolo et al -->
+If the API key is missing or invalid, the application returns an HTTP 401 "Unauthorized" error to the client.
+
+/// warning
+
+It is generally recommended to use API keys for programmatic access only, and to keep the API Key secret between the client(s) authenticated by the key and the server. Depending on your use case, this may mean storing this value in an environment variable or encrypted database (instead of hard-coding it, as in the examples below), and even providing a
+unique API key for each client trying to authenticate.
+
+///
+
+/// tip
+Please refer to the [API Reference](../../reference/security/index.md#api-key-security-schemes){.internal-link target=_blank} for specifics on the underlying security schemes used.
+///
+
+## Simple API Key Auth using Header
+
+* Import `APIKeyHeader`.
+* Create an `APIKeyHeader`, specifying what header to parse as the API key.
+* Create a `verify_api_key` function that checks the API Key in the Header.
+* Add `Depends(verify_api_key)` either globally or to a single endpoint (see example)
+
+```Python hl_lines="5  7  14  23"
+{!../../docs_src/security/tutorial008.py!}
+```
+
+The client will need to send a request with the correct header:
+
+```http
+GET /secure-data HTTP/1.1
+X-API-Key: mysecretapikey
+```
+
+## API Key Auth using Cookies
+
+The process is similar to using `APIKeyHeader`, except we use a `APIKeyCookie`
+instance, instead:
+
+```Python hl_lines="5  7  14  23"
+{!../../docs_src/security/tutorial009.py!}
+```
+
+The client will then need to pass in the key as a cookie (note that the name of the cookie is case-sensitive!):
+
+```http
+GET /secure-data HTTP/1.1
+Cookie: X-API-KEY=mysecretapikey
+```
+
+## API Key Auth using Query Param
+
+/// warning
+Passing API keys via query params is considered less secure, since it will be
+visible as part of the URL (for example, in browser history or access logs).
+///
+
+Again, similar to the approaches above, except we use `APIKeyQuery`:
+```Python hl_lines="5  7  14  23"
+{!../../docs_src/security/tutorial010.py!}
+```
+
+The client will then need to pass in the key as part of the query param:
+
+```http
+GET /secure-data?x-api-key=mysecretapikey HTTP/1.1
+```
+
+## Multiple Auth Schemes
+
+By default, these API key schemes set `auto_error=True`. This means that if no
+value is found in the expected location (header, cookie, or query param), the
+application will raise an exception (currently 403). If you'd like to have
+multiple auth schemes, then you can set `auto_error=False` on `APIKeyHeader`, etc.
--- a/docs/en/mkdocs.yml
+++ b/docs/en/mkdocs.yml
@ -171,6 +171,7 @@ nav:
      - advanced/security/index.md
      - advanced/security/oauth2-scopes.md
      - advanced/security/http-basic-auth.md
+      - advanced/security/api-key.md
    - advanced/using-request-directly.md
    - advanced/dataclasses.md
    - advanced/middleware.md
--- a/docs/es/docs/advanced/security/api-key.md
+++ b/docs/es/docs/advanced/security/api-key.md
@ -0,0 +1,80 @@
+# API Key Auth
+
+Otro método de autenticación, particularmente para communicación máquina-a-máquina (M2M) es un "API key". Un API key es una cadena de que la aplicación espera recibir con cada request del cliente. El API key puede ser enviado como "header", como "cookie", o como parámetro de query.
+
+<!-- TODO: currently we return 403 in the implementation! discuss with @tiangolo et al -->
+Si el API key no se incluye o es inválido, la aplicación devuelve un error HTTP 401 "Unauthorized".
+
+/// warning
+
+En general, se recomienda usar API keys para uso programático solamente. También
+se recomienda mantener el API Key como un secreto entre el cliente autentificado
+y el servidor. Dependiendo de tus requisitos, esto podría requerir tener el
+API key como variable de entorno o en una base de datos cifrada (en vez de en pleno
+código, como en los ejemplos que siguen), y hasta proveer una API key distinta
+para cada cliente que intente autentificar.
+
+///
+
+/// tip
+Puede referirse al [API Reference](../../reference/security/index.md#api-key-security-schemes){.internal-link target=_blank} para más detalles en cuanto a los esquemas discutidos.
+///
+
+## API Key como Header
+
+* Importe `APIKeyHeader`.
+* Cree una instancia de `APIKeyHeader`, especificando el nombre del header a probar.
+* Cree una función `verify_api_key` que verifique el API Key.
+* Añada un `Depends(verify_api_key)` globalmente o a un sólo "endpoint" (ver ejemplo).
+
+```Python hl_lines="5  7  14  23"
+{!../../docs_src/security/tutorial008.py!}
+```
+
+El cliente tendrá que enviar un request con el header correcto:
+
+```http
+GET /secure-data HTTP/1.1
+X-API-Key: mysecretapikey
+```
+
+## API Key como Cookie
+
+El proceso es similar al de `APIKeyHeader`, excepto que usamos `APIKeyCookie`:
+
+```Python hl_lines="5  7  14  23"
+{!../../docs_src/security/tutorial009.py!}
+```
+
+El cliente tendrá que enviar la API Key como cookie (recuerde que se distingue mayúscula y minúscula en el nombre de los cookies):
+
+```http
+GET /secure-data HTTP/1.1
+Cookie: X-API-KEY=mysecretapikey
+```
+
+## API Key como parámetro de Query
+
+/// warning
+Enviar API keys como párametro de query no es muy seguro, pues pueden
+ser vistos en el URL del request (por ejemplo, en tu browser o en los registros de acceso del servidor).
+///
+
+De nuevo, el proceso es similar a los anteriores, excepto usando `APIKeyQuery`:
+
+```Python hl_lines="5  7  14  23"
+{!../../docs_src/security/tutorial010.py!}
+```
+
+El cliente deberá enviar el API Key como parámetro:
+
+```http
+GET /secure-data?x-api-key=mysecretapikey HTTP/1.1
+```
+
+## Múltiples esquemas de autentificación
+
+Estaas esquemas de API Key tienen `auto_error=True`, por defecto. Esto
+significa que, si no hay un valor disponible en el lugar especificado (header, cookie, parámetro de query),
+la aplicación devolverá un error (403). Si desea tener múltiples de estas esquemas
+a la vez, puede configurar `auto_error=False` y combinar las esquemas deseadas.
--- a/docs_src/security/tutorial008.py
+++ b/docs_src/security/tutorial008.py
@ -0,0 +1,27 @@
+from fastapi import Depends, FastAPI, HTTPException
+from fastapi.security.api_key import APIKeyHeader
+
+# Replace with your actual API key, ideally injected as an Environment Variable
+# or stored in a secure DB.
+API_KEY = "mysecretapikey"
+
+API_KEY_NAME = "X-API-Key"
+api_key_header = APIKeyHeader(
+    name=API_KEY_NAME,
+    description="API Key required to access secure endpoints.",
+)
+
+
+def verify_api_key(api_key: str = Depends(api_key_header)):
+    if api_key != API_KEY:
+        raise HTTPException(status_code=401, detail="Invalid API Key")
+
+
+# Apply it for all endpoints
+app = FastAPI(dependencies=[Depends(verify_api_key)])
+
+
+# Apply it for specific endpoints
+@app.get("/secure-data")
+def secure_endpoint(api_key: str = Depends(verify_api_key)):
+    return {"message": "You have access to secure data"}
--- a/docs_src/security/tutorial009.py
+++ b/docs_src/security/tutorial009.py
@ -0,0 +1,29 @@
+from fastapi import Depends, FastAPI, HTTPException
+from fastapi.security.api_key import APIKeyCookie
+
+app = FastAPI()
+
+# Replace with your actual API key, ideally injected as an Environment Variable
+# or stored in a secure DB.
+API_KEY = "mysecretapikey"
+
+API_KEY_NAME = "X-API-KEY"  # case-sensitive!
+api_key_cookie = APIKeyCookie(
+    name=API_KEY_NAME,
+    description="API Key required to access secure endpoints.",
+)
+
+
+def verify_api_key(api_key: str = Depends(api_key_cookie)):
+    if api_key != API_KEY:
+        raise HTTPException(status_code=401, detail="Invalid API Key")
+
+
+# Apply it for all endpoints
+app = FastAPI(dependencies=[Depends(verify_api_key)])
+
+
+# Apply it for specific endpoints
+@app.get("/secure-data")
+def secure_endpoint(api_key: str = Depends(verify_api_key)):
+    return {"message": "You have access to secure data"}
--- a/docs_src/security/tutorial010.py
+++ b/docs_src/security/tutorial010.py
@ -0,0 +1,29 @@
+from fastapi import Depends, FastAPI, HTTPException
+from fastapi.security.api_key import APIKeyQuery
+
+app = FastAPI()
+
+# Replace with your actual API key, ideally injected as an Environment Variable
+# or stored in a secure DB.
+API_KEY = "mysecretapikey"
+
+API_KEY_NAME = "x-api-key"
+api_key_query = APIKeyQuery(
+    name=API_KEY_NAME,
+    description="API Key required to access secure endpoints.",
+)
+
+
+def verify_api_key(api_key: str = Depends(api_key_query)):
+    if api_key != API_KEY:
+        raise HTTPException(status_code=401, detail="Invalid API Key")
+
+
+# Apply it for all endpoints
+app = FastAPI(dependencies=[Depends(verify_api_key)])
+
+
+# Apply it for specific endpoints
+@app.get("/secure-data")
+def secure_endpoint(api_key: str = Depends(verify_api_key)):
+    return {"message": "You have access to secure data"}
--- a/tests/test_tutorial/test_security/test_tutorial008.py
+++ b/tests/test_tutorial/test_security/test_tutorial008.py
@ -0,0 +1,62 @@
+from fastapi.testclient import TestClient
+
+from docs_src.security.tutorial008 import app
+
+client = TestClient(app)
+
+openapi_schema = {
+    "openapi": "3.1.0",
+    "info": {"title": "FastAPI", "version": "0.1.0"},
+    "paths": {
+        "/secure-data": {
+            "get": {
+                "summary": "Secure Endpoint",
+                "operationId": "secure_endpoint_secure_data_get",
+                "responses": {
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {"application/json": {"schema": {}}},
+                    }
+                },
+                "security": [{"APIKeyHeader": []}],
+            }
+        }
+    },
+    "components": {
+        "securitySchemes": {
+            "APIKeyHeader": {
+                "type": "apiKey",
+                "description": "API Key required to access secure endpoints.",
+                "in": "header",
+                "name": "X-API-Key",
+            }
+        }
+    },
+}
+
+
+def test_openapi_schema():
+    response = client.get("/openapi.json")
+    assert response.status_code == 200, response.text
+    assert response.json() == openapi_schema
+
+
+def test_apikey_header():
+    auth = {"X-API-KEY": "mysecretapikey"}
+    response = client.get("/secure-data", headers=auth)
+    assert response.status_code == 200, response.text
+    assert response.json() == {"message": "You have access to secure data"}
+
+
+def test_apikey_header_no_credentials():
+    response = client.get("/secure-data", headers={})
+    # TODO: this should be 401 in the implementation! discuss with @tiangolo et al
+    assert response.status_code == 403, response.text
+    assert response.json() == {"detail": "Not authenticated"}
+
+
+def test_apikey_header_invalid_credentials():
+    auth = {"X-API-KEY": "totally-wrong-api-key"}
+    response = client.get("/secure-data", headers=auth)
+    assert response.status_code == 401, response.text
+    assert response.json() == {"detail": "Invalid API Key"}
--- a/tests/test_tutorial/test_security/test_tutorial009.py
+++ b/tests/test_tutorial/test_security/test_tutorial009.py
@ -0,0 +1,62 @@
+from fastapi.testclient import TestClient
+
+from docs_src.security.tutorial009 import app
+
+openapi_schema = {
+    "openapi": "3.1.0",
+    "info": {"title": "FastAPI", "version": "0.1.0"},
+    "paths": {
+        "/secure-data": {
+            "get": {
+                "summary": "Secure Endpoint",
+                "operationId": "secure_endpoint_secure_data_get",
+                "responses": {
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {"application/json": {"schema": {}}},
+                    }
+                },
+                "security": [{"APIKeyCookie": []}],
+            },
+        },
+    },
+    "components": {
+        "securitySchemes": {
+            "APIKeyCookie": {
+                "type": "apiKey",
+                "name": "X-API-KEY",
+                "description": "API Key required to access secure endpoints.",
+                "in": "cookie",
+            },
+        },
+    },
+}
+
+
+def test_openapi_schema():
+    client = TestClient(app, cookies={"X-API-KEY": "mysecretapikey"})
+    response = client.get("/openapi.json")
+    assert response.status_code == 200, response.text
+    assert response.json() == openapi_schema
+
+
+def test_apikey_cookie():
+    client = TestClient(app, cookies={"X-API-KEY": "mysecretapikey"})
+    response = client.get("/secure-data")
+    assert response.status_code == 200, response.text
+    assert response.json() == {"message": "You have access to secure data"}
+
+
+def test_apikey_cookie_no_key():
+    client = TestClient(app)
+    response = client.get("/secure-data")
+    # TODO: this should be 401 in the implementation! discuss with @tiangolo et al
+    assert response.status_code == 403, response.text
+    assert response.json() == {"detail": "Not authenticated"}
+
+
+def test_apikey_cookie_invalid_key():
+    client = TestClient(app, cookies={"X-API-KEY": "wrongkey"})
+    response = client.get("/secure-data")
+    assert response.status_code == 401, response.text
+    assert response.json() == {"detail": "Invalid API Key"}
--- a/tests/test_tutorial/test_security/test_tutorial010.py
+++ b/tests/test_tutorial/test_security/test_tutorial010.py
@ -0,0 +1,60 @@
+from fastapi.testclient import TestClient
+
+from docs_src.security.tutorial010 import app
+
+client = TestClient(app)
+
+openapi_schema = {
+    "openapi": "3.1.0",
+    "info": {"title": "FastAPI", "version": "0.1.0"},
+    "paths": {
+        "/secure-data": {
+            "get": {
+                "summary": "Secure Endpoint",
+                "operationId": "secure_endpoint_secure_data_get",
+                "responses": {
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {"application/json": {"schema": {}}},
+                    }
+                },
+                "security": [{"APIKeyQuery": []}],
+            },
+        },
+    },
+    "components": {
+        "securitySchemes": {
+            "APIKeyQuery": {
+                "type": "apiKey",
+                "name": "x-api-key",
+                "description": "API Key required to access secure endpoints.",
+                "in": "query",
+            },
+        },
+    },
+}
+
+
+def test_openapi_schema():
+    response = client.get("/openapi.json")
+    assert response.status_code == 200, response.text
+    assert response.json() == openapi_schema
+
+
+def test_security_api_key():
+    response = client.get("/secure-data?x-api-key=mysecretapikey")
+    assert response.status_code == 200, response.text
+    assert response.json() == {"message": "You have access to secure data"}
+
+
+def test_security_api_key_no_key():
+    response = client.get("/secure-data")
+    # TODO: this should be 401 in the implementation! discuss with @tiangolo et al
+    assert response.status_code == 403, response.text
+    assert response.json() == {"detail": "Not authenticated"}
+
+
+def test_security_api_key_invalid_key():
+    response = client.get("/secure-data?x-api-key=wrongkey")
+    assert response.status_code == 401, response.text
+    assert response.json() == {"detail": "Invalid API Key"}