docs(event_handler): demonstrate handling optional security routes

[leandrodamascena]

Issue number: #5893

Summary

Changes

The OpenAPI v3 specification defines an optional security mechanism with {}, so this means that if you add a security scheme on a specific route like this @app.get("/unprotected", security=[{}]) it will make the authorization optional in that specific route.

Reference: spec.openapis.org/oas/v3.1.0.html#fixed-fields

A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition. To make security optional, an empty security requirement ({}) can be included in the array.

User experience

from aws_lambda_powertools import Logger, Tracer
from aws_lambda_powertools.event_handler import (
    APIGatewayRestResolver,
)
from aws_lambda_powertools.event_handler.openapi.models import (
    OAuth2,
    OAuthFlowAuthorizationCode,
    OAuthFlows,
)

tracer = Tracer()
logger = Logger()

app = APIGatewayRestResolver(enable_validation=True)


@app.get("/protected", security=[{"oauth": ["admin"]}])  # (1)!
def protected() -> dict:
    return {"hello": "world"}


@app.get("/unprotected", security=[{}])  # (1)!
def unprotected() -> dict:
    return {"hello": "world"}


@logger.inject_lambda_context
@tracer.capture_lambda_handler
def lambda_handler(event, context):
    return app.resolve(event, context)


if __name__ == "__main__":
    print(
        app.get_openapi_json_schema(
            title="My API",
            security_schemes={
                "oauth": OAuth2(
                    flows=OAuthFlows(
                        authorizationCode=OAuthFlowAuthorizationCode(
                            authorizationUrl="https://xxx.amazoncognito.com/oauth2/authorize",
                            tokenUrl="https://xxx.amazoncognito.com/oauth2/token",
                        ),
                    ),
                ),
            },
        ),
    )

Checklist

If your change doesn't seem to apply, please leave them unchecked.

• Meet tenets criteria
• I have performed a self-review of this change
• Changes have been tested
• Changes are documented
• PR title follows conventional commit semantics

Is this a breaking change?

RFC issue number:

Checklist:

• Migration process documented
• Implement warnings (if it can live side by side)

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 96.20%. Comparing base (b74a659) to head (2961d7c).
Report is 1 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #5895   +/-   ##
========================================
  Coverage    96.20%   96.20%           
========================================
  Files          232      232           
  Lines        10956    10956           
  Branches      2027     2027           
========================================
  Hits         10540    10540           
  Misses         327      327           
  Partials        89       89           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[leandrodamascena]

Hey @anafalcao! Thanks a lot for the review! Can you please check again?

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[anafalcao]

APPROVED! Thank you Leo