feat(event_handler): mutualTLS Security Scheme for OpenAPI (#5484)

* mutualtls security scheme implementation

* security scheme documentation updates

* Adding mTLS test

* Adding mTLS test

---------

Co-authored-by: Justin <[email protected]>
Co-authored-by: Leandro Damascena <[email protected]>

Author: 3 people

aws_lambda_powertools/event_handler/openapi/models.py

@@ -363,6 +363,7 @@ class SecuritySchemeType(Enum):
     http = "http"
     oauth2 = "oauth2"
     openIdConnect = "openIdConnect"
+    mutualTLS = "mutualTLS"
 
 
 class SecurityBase(OpenAPIExtensions):
@@ -440,7 +441,11 @@ class OpenIdConnect(SecurityBase):
     openIdConnectUrl: str
 
 
-SecurityScheme = Union[APIKey, HTTPBase, OAuth2, OpenIdConnect, HTTPBearer]
+class MutualTLS(SecurityBase):
+    type_: SecuritySchemeType = Field(default=SecuritySchemeType.mutualTLS, alias="type")
+
+
+SecurityScheme = Union[APIKey, HTTPBase, OAuth2, OpenIdConnect, HTTPBearer, MutualTLS]
 
 
 # https://swagger.io/specification/#components-object

docs/core/event_handler/api_gateway.md

@@ -1111,6 +1111,7 @@ OpenAPI 3 lets you describe APIs protected using the following security schemes:
 | [API keys](https://swagger.io/docs/specification/authentication/api-keys/https://swagger.io/docs/specification/authentication/api-keys/){target="_blank"} (e.g: query strings, cookies) | `APIKey`        | API keys in headers, query strings or [cookies](https://swagger.io/docs/specification/authentication/cookie-authentication/){target="_blank"}.                                                                                                                                      |
 | [OAuth 2](https://swagger.io/docs/specification/authentication/oauth2/){target="_blank"}                                                                                                | `OAuth2`        | Authorization protocol that gives an API client limited access to user data on a web server.                                                                                                                                                                                        |
 | [OpenID Connect Discovery](https://swagger.io/docs/specification/authentication/openid-connect-discovery/){target="_blank"}                                                             | `OpenIdConnect` | Identity layer built [on top of the OAuth 2.0 protocol](https://openid.net/developers/how-connect-works/){target="_blank"} and supported by some OAuth 2.0.                                                                                                                         |
+| [Mutual TLS](https://swagger.io/specification/#security-scheme-object){target="_blank"}.                                                                                                | `MutualTLS`     | Client/server certificate mutual authentication scheme. |
 
 ???-note "Using OAuth2 with the Swagger UI?"
     You can use the `OAuth2Config` option to configure a default OAuth2 app on the generated Swagger UI.

tests/functional/event_handler/_pydantic/test_openapi_security_schemes.py

@@ -3,6 +3,7 @@
     APIKey,
     APIKeyIn,
     HTTPBearer,
+    MutualTLS,
     OAuth2,
     OAuthFlowImplicit,
     OAuthFlows,
@@ -110,3 +111,24 @@ def handler():
     open_id_connect_scheme = security_schemes["openIdConnect"]
     assert open_id_connect_scheme.type_.value == "openIdConnect"
     assert open_id_connect_scheme.openIdConnectUrl == "https://example.com/oauth2/authorize"
+
+
+def test_openapi_security_scheme_mtls():
+    app = APIGatewayRestResolver()
+
+    @app.get("/")
+    def handler():
+        raise NotImplementedError()
+
+    schema = app.get_openapi_schema(
+        security_schemes={
+            "mutualTLS": MutualTLS(description="mTLS Authentication"),
+        },
+    )
+
+    security_schemes = schema.components.securitySchemes
+    assert security_schemes is not None
+
+    assert "mutualTLS" in security_schemes
+    mtls_scheme = security_schemes["mutualTLS"]
+    assert mtls_scheme.description == "mTLS Authentication"