13 feature enable api authentication with both application token and user identity by Aravinda-HWK · Pull Request #16 · OpenGovMail/pingmailer

Aravinda-HWK · 2026-02-19T13:29:54Z

Description

This PR is to secure the /notify endpoint in the PingMailer system.

Type of Change

Changes Made

Need a Bearer token to access the endpoint with valid username and password to send emails.

Testing

Checklist

My code follows the project's coding standards
I have tested my changes
I have updated the documentation (if needed)
My changes don't introduce new warnings or errors

Related Issues

Fixes #13

- Implemented OAuth2 authentication flow for application-level access tokens. - Created a new `auth.go` file to handle token extraction and validation. - Added health check endpoint to monitor server status. - Updated README.md and added QUICKREF.md for better documentation. - Introduced example scripts in Bash and Python for demonstrating API usage. - Enhanced Docker Compose setup to include OAuth2 configuration. - Added error handling for missing OAuth2 credentials and token validation failures. - Implemented asynchronous email sending with user-provided SMTP credentials. - Created a comprehensive testing guide to validate the dual authentication implementation.

…validation

…ssage and status

…files

…Mailer API

… client credentials

gemini-code-assist · 2026-02-19T13:30:17Z

Summary of Changes

Hello @Aravinda-HWK, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the security of the PingMailer API by introducing a robust dual authentication system. It implements application-level authentication using OAuth2 Bearer tokens for the '/notify' endpoint, ensuring that only authorized applications can send emails. Additionally, it adds a health check endpoint for better operational visibility and updates all relevant documentation and configuration to support these new features.

Highlights

OAuth2 Application Authentication: Implemented OAuth2-based application authentication for the '/notify' endpoint, requiring a Bearer token which is validated via a configurable introspection URL.
Health Check Endpoint: Introduced a new '/health' endpoint to provide a simple status check for the API server, which does not require authentication.
Updated Documentation and Configuration: Extensively updated the README and environment examples to reflect the new dual authentication mechanism, API usage, and required OAuth2 configuration.

Changelog

api-server/.env.example
- Added OAUTH2_INTROSPECT_URL configuration.
- Included notes explaining OAuth2 token validation and usage.
api-server/README.md
- Updated the API description to mention dual authentication.
- Added a new 'Features' section detailing dual authentication, secure email delivery, custom templates, HTTPS, and health monitoring.
- Introduced a dedicated 'Authentication' section explaining application and user authentication.
- Updated 'API Usage' to include an 'Authentication Flow' guide and modified the 'curl' example for '/notify' to include the 'Authorization' header.
- Added documentation for the new '/health' endpoint.
- Expanded 'Running Locally' instructions to include OAUTH2_INTROSPECT_URL and updated 'go run' commands.
- Added a 'Command-line Flags' table.
- Included an 'Example Scripts' section with 'test-auth.sh' and 'client.py'.
api-server/auth.go
- Added a new file containing OAuth2 authentication logic.
- Defined OAuth2Config and IntrospectionResponse structs.
- Implemented extractBearerToken to parse the Authorization header.
- Implemented validateAccessToken to perform OAuth2 token introspection against a configured URL.
- Implemented authMiddleware to protect HTTP handlers with token validation.
api-server/docker-compose.https.yml
- Added OAUTH2_INTROSPECT_URL as an environment variable for the 'api-server' service.
api-server/entrypoint.sh
- Modified the script to dynamically build the 'api-server' command.
- Ensured OAUTH2_INTROSPECT_URL is passed as a required command-line argument.
- Added error handling if OAUTH2_INTROSPECT_URL is not set.
api-server/handlers.go
- Added handleHealth function to provide a simple JSON health status.
- Modified handleNotify to return a structured JSON success response and log successful email sends.
api-server/main.go
- Added 'oauth2 OAuth2Config' field to the 'config' struct.
- Registered a command-line flag for 'oauth2-introspect-url'.
- Added validation to ensure 'oauth2-introspect-url' is provided at startup.
api-server/routes.go
- Applied the new 'app.authMiddleware' to the '/notify' endpoint, making it protected.
- Registered the new 'app.handleHealth' endpoint as an unprotected route.

Activity

The pull request was created by Aravinda-HWK to address issue [FEATURE] Enable API Authentication with Both Application Token and User Identity #13, focusing on enabling API authentication.
The author has marked the changes as a new feature and confirmed adherence to project coding standards, testing, and documentation updates.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

Aravinda-HWK · 2026-02-19T13:30:20Z

@maneeshaxyz I will update the PR and let you know to review.

gemini-code-assist

Code Review

This pull request introduces OAuth2-based authentication for the /notify endpoint, a significant security enhancement. The implementation includes a new authentication middleware, token introspection logic, and necessary configuration updates. The documentation has also been updated accordingly.

My review focuses on improving security and performance. I've identified a potential information disclosure vulnerability in the error handling, a performance issue related to HTTP client instantiation, and a shell scripting bug in the entrypoint script that could lead to unexpected behavior. The proposed changes will make the authentication flow more robust and secure.

… parameters

…ccessToken

…tion

Aravinda-HWK · 2026-02-20T06:03:16Z

@maneeshaxyz Now you can start to review this PR.

maneesha-xyz · 2026-02-20T07:18:00Z

+See the `examples/` directory for usage examples:
+
+- `test-auth.sh` - Bash script demonstrating the complete authentication flow
+- `client.py` - Python client library with dual authentication


Where is this examples directory? I think it has not been pushed.

maneesha-xyz

LGTM.

Aravinda-HWK added 7 commits February 19, 2026 13:59

feat: Implement OAuth2 token introspection for enhanced security and …

3fe3dc6

…validation

feat: Update email notification response format to include success me…

0ba56a9

…ssage and status

chore: Remove outdated architecture and authentication documentation …

5b92b0e

…files

chore: remove outdated QUICKREF and TESTING documentation files

9cd2619

chore: remove example client and test authentication scripts for Ping…

25bec0c

…Mailer API

feat: update OAuth2 configuration to use introspection URL and remove…

d8e1a34

… client credentials

Aravinda-HWK requested a review from maneesha-xyz February 19, 2026 13:29

Aravinda-HWK self-assigned this Feb 19, 2026

Aravinda-HWK linked an issue Feb 19, 2026 that may be closed by this pull request

[FEATURE] Enable API Authentication with Both Application Token and User Identity #13

Closed

gemini-code-assist Bot reviewed Feb 19, 2026

View reviewed changes

Comment thread api-server/auth.go Outdated

Comment thread api-server/entrypoint.sh Outdated

Comment thread api-server/auth.go Outdated

Aravinda-HWK added 5 commits February 20, 2026 11:07

fix: update unauthorized error message to be more descriptive

0487d76

refactor: streamline command building in entrypoint script for OAuth2…

3e01151

… parameters

refactor: use shared HTTP client for token introspection in validateA…

c9137ff

…ccessToken

fix: handle JSON encoding errors in health and notify response handlers

da88d88

fix: validate OAuth2 introspection URL format and scheme in configura…

b2101f6

…tion

Aravinda-HWK marked this pull request as ready for review February 20, 2026 06:03

Aravinda-HWK added the enhancement New feature or request label Feb 20, 2026

maneesha-xyz reviewed Feb 20, 2026

View reviewed changes

Update README.md

99aabcb

maneesha-xyz approved these changes Feb 20, 2026

View reviewed changes

maneesha-xyz merged commit c64bba5 into main Feb 20, 2026
2 checks passed

maneesha-xyz deleted the 13-feature-enable-api-authentication-with-both-application-token-and-user-identity branch February 20, 2026 09:16

Navigation Menu

13 feature enable api authentication with both application token and user identity - #16

13 feature enable api authentication with both application token and user identity#16
maneesha-xyz merged 13 commits into
mainfrom
13-feature-enable-api-authentication-with-both-application-token-and-user-identity

Aravinda-HWK commented Feb 19, 2026

Uh oh!

gemini-code-assist Bot commented Feb 19, 2026

Uh oh!

Aravinda-HWK commented Feb 19, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Aravinda-HWK commented Feb 20, 2026

Uh oh!

maneesha-xyz Feb 20, 2026

Uh oh!

maneesha-xyz left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Aravinda-HWK commented Feb 19, 2026

Description

Type of Change

Changes Made

Testing

Checklist

Related Issues

Uh oh!

gemini-code-assist Bot commented Feb 19, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

Aravinda-HWK commented Feb 19, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Aravinda-HWK commented Feb 20, 2026

Uh oh!

maneesha-xyz Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

maneesha-xyz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants