Add OAuth2/OIDC authentication integration (#169)

[sathish-k7]

Description

Implements JWT token validation middleware with OIDC support for securing HealthChain API endpoints. Enables the Gateway to act as an authorization server for client applications accessing health data with role-based access control.

Related Issue

Resolves #169

Changes Made

• Added JWT authentication middleware for FastAPI with OIDC support
• Implemented OIDC provider configuration with auto-discovery, JWKS, and token introspection
• Created role-based access control (RBAC) decorators: require_role, require_roles, require_scope
• Added support for multiple OIDC providers (Keycloak, Auth0, Okta, Azure AD)
• Implemented scope-based authorization for FHIR resources
• Created comprehensive Keycloak integration example with complete setup
• Added complete documentation and cookbook guide
• Updated dependencies: pyjwt[crypto]>=2.8.0,<3 and cryptography>=41.0.0,<44

Testing

• Unit tests: 8/8 passing (100%)
• Tested with pytest: uv run pytest tests/gateway/test_oidc_auth.py -v
• Pre-commit hooks: all checks passing (ruff, ruff-format, trailing whitespace)
• Real-world healthcare scenarios validated (doctors, nurses, pharmacists, patients)
• Role extraction tested for Keycloak, Auth0, and standard token formats
• FHIR scope-based access control verified
• Access control decision matrix validated

Checklist

• I have read the contributing guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

Additional Notes

• All files follow the uv dependency management workflow as specified in CONTRIBUTING.md
• Documentation includes complete Keycloak setup guide with step-by-step instructions
• Examples include production-ready code with proper error handling
• Implementation supports healthcare-specific role hierarchies and FHIR scopes
• Middleware includes path exclusion and optional authentication support

[jenniferjiangkells]

Thanks for the contribution. This issue is currently in the design phase (Stage: Design), and the maintainers have not yet agreed on an approach for auth and OIDC integration. For core concerns like authentication/authorization, we only review implementation PRs once there is an accepted design/RFC linked from the issue.

For now, we are closing this PR. If you are interested in helping, please join the design discussion on the issue so we can first agree on the architecture and responsibilities of the Gateway and auth components.