Implement authorization code flow with Azul and Data Browser (#7954) by hannes-ucsc · Pull Request #7961 · DataBiosphere/azul

hannes-ucsc · 2026-04-27T15:56:15Z

Linked issues: #7954

Notes

This PR has the upgrade label. Operator to add the required CL items to this PR and the corresponding promotion PR.

Checklist

Author

¹ when the issue title describes a problem, the corresponding PR
title is Fix: followed by the issue title

Author (partiality)

Added p tag to titles of partial commits
This PR is labeled partial _{or completely resolves all linked issues}
This PR partially resolves each of the linked issues _{or does not have the partial label}

Author (reindex)

Added r tag to commit title _{or the changes introduced by this PR will not require reindexing of any deployment}
This PR is labeled reindex:dev _{or the changes introduced by it will not require reindexing of dev}
This PR is labeled reindex:anvildev _{or the changes introduced by it will not require reindexing of anvildev}
This PR is labeled reindex:anvilprod _{or the changes introduced by it will not require reindexing of anvilprod}
This PR is labeled reindex:prod _{or the changes introduced by it will not require reindexing of prod}
This PR is labeled reindex:partial and its description documents the specific reindexing procedure for dev, anvildev, anvilprod and prod _{or requires a full reindex or carries none of the labels reindex:dev, reindex:anvildev, reindex:anvilprod and reindex:prod}

Author (mirror)

This PR is labeled mirror:dev _{or the changes introduced by it will not require mirroring of dev}
This PR is labeled mirror:anvildev _{or the changes introduced by it will not require mirroring of anvildev}
This PR is labeled mirror:anvilprod _{or the changes introduced by it will not require mirroring of anvilprod}
This PR is labeled mirror:prod _{or the changes introduced by it will not require mirroring of prod}
This PR is labeled mirror:partial and its description documents the specific mirroring procedure for dev, anvildev, anvilprod and prod _{or requires a full mirroring or carries none of the labels mirror:dev, mirror:anvildev, mirror:anvilprod and mirror:prod}

Author (API changes)

This PR and its linked issues are labeled API _{or this PR does not modify a REST API}
Added a (A) tag to commit title for backwards (in)compatible changes _{or this PR does not modify a REST API}
Updated REST API version number in app.py _{or this PR does not modify a REST API}

Author (upgrading deployments)

Ran make docker_images.json and committed the resulting changes _{or this PR does not modify azul_docker_images, or any other variables referenced in the definition of that variable}
Documented upgrading of deployments in UPGRADING.rst _{or this PR does not require upgrading deployments}
Added u tag to commit title _{or this PR does not require upgrading deployments}
This PR is labeled upgrade _{or does not require upgrading deployments}
This PR is labeled deploy:shared _{or does not modify docker_images.json, and does not require deploying the shared component for any other reason}
This PR is labeled deploy:gitlab _{or does not require deploying the gitlab component}
This PR is labeled deploy:runner _{or does not require deploying the runner image}

Author (hotfixes)

Added F tag to main commit title _{or this PR does not include permanent fix for a temporary hotfix}
Reverted the temporary hotfixes for any linked issues _{or the none of the stable branches (anvilprod and prod) have temporary hotfixes for any of the issues linked to this PR}

Author (before every review)

Rebased PR branch on develop, squashed fixups from prior reviews
Ran make requirements_update _{or this PR does not modify Dockerfile, environment, requirements*.txt, common.mk, Makefile or environment.boot}
Added R tag to commit title _{or this PR does not modify requirements*.txt}
This PR is labeled reqs _{or does not modify requirements*.txt}
make integration_test passes in personal deployment _{or this PR does not modify functionality that could affect the IT outcome}
PR is awaiting requested review from a peer
Status of PR is Review requested
PR is assigned to only the peer and the author

Peer reviewer (after approval)

Note that after requesting changes, the PR must be assigned to only the author.

Actually approved the PR
PR is not a draft
PR is awaiting requested review from system administrator
Status of PR is Review requested
PR is assigned to only the system administrator and the author

System administrator (after approval)

Actually approved the PR
Labeled linked issues as demo or no demo
Commented on linked issues about demo expectations _{or all linked issues are labeled no demo}
Decided if PR can be labeled no sandbox
A comment to this PR details the completed security design review
PR title is appropriate as title of merge commit
N reviews label is accurate
Status of PR is Approved
PR is assigned to only the operator and the author

Operator

Checked reindex:… labels and r commit title tag
Checked mirror:… labels
Checked that demo expectations are clear _{or all linked issues are labeled no demo}
Squashed PR branch and rebased onto develop
Sanity-checked history
Pushed PR branch to GitHub

Operator (deploy `.shared` and `.gitlab` components)

Ran _select dev.shared && CI_COMMIT_REF_NAME=develop make -C terraform/shared apply_keep_unused _{or this PR is not labeled deploy:shared}
Ran _select dev.gitlab && CI_COMMIT_REF_NAME=develop make -C terraform/gitlab apply _{or this PR is not labeled deploy:gitlab}
Ran _select anvildev.shared && CI_COMMIT_REF_NAME=develop make -C terraform/shared apply_keep_unused _{or this PR is not labeled deploy:shared}
Ran _select anvildev.gitlab && CI_COMMIT_REF_NAME=develop make -C terraform/gitlab apply _{or this PR is not labeled deploy:gitlab}
Checked the items in the next section _{or this PR is labeled deploy:gitlab}
PR is assigned to only the system administrator and the author _{or this PR is not labeled deploy:gitlab}

System administrator (post-deploy of `.gitlab` component)

Background migrations for dev.gitlab are complete _{or this PR is not labeled deploy:gitlab}
Background migrations for anvildev.gitlab are complete _{or this PR is not labeled deploy:gitlab}
PR is assigned to only the operator and the author

Operator (deploy runner image)

Ran _select dev.gitlab && make -C terraform/gitlab/runner _{or this PR is not labeled deploy:runner}
Ran _select anvildev.gitlab && make -C terraform/gitlab/runner _{or this PR is not labeled deploy:runner}

Operator (sandbox build)

Operator (merge the branch)

All status checks passed and the PR is mergeable
The title of the merge commit starts with the title of this PR
Added PR # reference to merge commit title
Collected commit title tags in merge commit title _{but only included p if the PR is also labeled partial}
Pushed merge commit to GitHub
Status of PR is Merged lower
Status of blocked issues is Triage _{or no issues are blocked on the linked issues}

Operator (main build)

Pushed merge commit to GitLab dev
Pushed merge commit to GitLab anvildev
Build passes on GitLab dev
Reviewed build logs for anomalies on GitLab dev
Build passes on GitLab anvildev
Reviewed build logs for anomalies on GitLab anvildev
Ran _select dev.shared && make -C terraform/shared apply _{or this PR is not labeled deploy:shared}
Ran _select anvildev.shared && make -C terraform/shared apply _{or this PR is not labeled deploy:shared}

Operator (upgrading)

Followed instructions in UPGRADING.rst for dev
Followed instructions in UPGRADING.rst for anvildev

Operator (main build cont'd)

Deleted PR branch from GitHub
PR is assigned to only the operator
Deleted PR branch from GitLab dev
Deleted PR branch from GitLab anvildev
Status of linked issues is Lower, or Triage, if PR is partial

Operator (reindex)

Operator (mirroring)

Started mirroring in dev _{or this PR is not labelled mirror:dev}
Started mirroring in anvildev _{or this PR is not labelled mirror:anvildev}
Checked for, triaged and possibly requeued messages in mirror fail queue in dev _{or this PR is not labelled mirror:dev}
Checked for, triaged and possibly requeued messages in mirror fail queue in anvildev _{or this PR is not labelled mirror:anvildev}
Emptied mirror fail queue in dev _{or this PR is not labelled mirror:dev}
Emptied mirror fail queue in anvildev _{or this PR is not labelled mirror:anvildev}

Operator

Propagated Operator (upgrading) section relevant to the promotion PRs
Propagated the deploy:shared, deploy:gitlab, deploy:runner, API, reindex:partial, reindex:anvilprod, reindex:prod, mirror:partial, mirror:anvilprod and mirror:prod labels to the next promotion PRs _{or this PR carries none of these labels}
Propagated any specific instructions related to the deploy:shared, deploy:gitlab, deploy:runner, API, reindex:partial, reindex:anvilprod, reindex:prod, mirror:partial, mirror:anvilprod and mirror:prod labels, from the description of this PR to that of the next promotion PRs _{or this PR carries none of these labels}
PR is assigned to no one

Shorthand for review comments

L line is too long
W line wrapping is wrong
Q bad quotes
F other formatting problem

… in preparation for the extraction of a delegatee

codecov · 2026-04-27T17:57:57Z

Codecov Report

❌ Patch coverage is 61.68224% with 41 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.93%. Comparing base (e24cb4a) to head (7c0f020).
⚠️ Report is 11 commits behind head on develop.

Files with missing lines	Patch %	Lines
src/azul/service/user_controller.py	61.76%	13 Missing ⚠️
test/integration_test.py	0.00%	11 Missing ⚠️
src/azul/service/user_service.py	59.09%	9 Missing ⚠️
src/azul/oauth2.py	77.77%	8 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #7961      +/-   ##
===========================================
- Coverage    85.01%   84.93%   -0.08%     
===========================================
  Files          162      164       +2     
  Lines        23341    23422      +81     
===========================================
+ Hits         19843    19894      +51     
- Misses        3498     3528      +30

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

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

coveralls · 2026-04-27T17:58:50Z

coverage: 85.017% (-0.08%) from 85.093% — issues/hannes-ucsc/7954-oauth-flow into develop

…7954)

hannes-ucsc · 2026-04-29T01:36:15Z

This comment was generated by Claude Code.

Security Design Review

PR: Implement authorization code flow with Azul and Data Browser (#7954)
Scope: New POST /user/authorize endpoint, UserController, UserService, refactoring of OAuth2Client into OAuth2Client + CredentialedClient

Architecture Summary

This PR implements the Backend-for-Frontend (BFF) pattern for OAuth 2.0 authorization code exchange. A browser-based SPA (Data Browser) obtains an authorization code from Google's authorization server via the Google Sign-In JS library, then sends that code to Azul's new /user/authorize endpoint. Azul exchanges the code for tokens server-side using the client secret, strips the refresh token, and returns the access token and ID token to the browser.

Positive Security Properties

BFF pattern correctly applied: The client secret never reaches the browser. The refresh token is explicitly stripped (response.pop('refresh_token')) before returning to the client. This follows the IETF draft best practice for browser-based apps (draft-ietf-oauth-browser-based-apps, section 6.1).
Client secret stored in AWS Secrets Manager (user_service.py:28-31): Fetched on each invocation (not cached in memory long-term), limiting exposure window.
Type validation on request and response: Both the incoming Authorization and outgoing TokenForCodeResponse are validated with is_of_type(), ensuring structural conformance. Unknown request fields are stripped via the annotation-key filter (user_controller.py:141-145).
Security headers: The existing middleware applies HSTS, CSP (default-src 'self', frame-ancestors 'none'), X-Frame-Options: DENY, X-Content-Type-Options: nosniff, and X-XSS-Protection.
redirect_uri: 'postmessage' is the correct, standard approach for Google's JS-library-initiated authorization code flows, and restricts code exchange to the postMessage channel.
No authentication required (interactive=False): Correct — this endpoint IS the authentication mechanism. Requiring prior auth would be circular.

Findings

Finding 1 (Low, fixed): Scope check used substring matching
user_service.py:38: 'openid' in authorization['scope'] performed a Python substring check on the scope string. Fixed by splitting on whitespace before checking membership.

Finding 2 (Low, accepted): Token values in assertion message
user_service.py:47: assert 'id_token' in response, response uses the full TokenForCodeResponse dict (containing access_token, refresh_token) as the assertion message. This is a bare assertion (not wrapped in R()), so it correctly propagates as a 500 internal error rather than a 400. Chalice's _unhandled_exception_to_response() returns the full traceback (including the assertion message) only when debug is True (AZUL_DEBUG > 1). In production and shared deployments (AZUL_DEBUG 0 or 1), the client receives a generic InternalServerError message. The token values do appear in CloudWatch logs via exc_info=True, but that is server-side only. Personal dev deployments with AZUL_DEBUG=2 would expose tokens in the HTTP response, but only to the developer using their own tokens.

Finding 3 (Informational): Wildcard CORS
cors=True in Chalice defaults to Access-Control-Allow-Origin: *. For this specific endpoint this is acceptable because: (a) it doesn't use cookies/credentials, (b) authorization codes are single-use and unguessable, and (c) the response only contains the caller's own tokens. Restricting origins to the Data Browser domain would be defense-in-depth but is not strictly necessary.

Finding 4 (Informational): PKCE not enforced client-side
The flow does not appear to enforce PKCE. Since the BFF holds a client secret, PKCE is not strictly required for security — an intercepted authorization code cannot be exchanged without the secret. Google may enforce PKCE server-side depending on client type configuration.

Conclusion

No blocking issues found. All findings are low or informational severity.

hannes-ucsc · 2026-04-29T02:22:31Z

hannes-ucsc · 2026-04-29T02:27:58Z

@achave11-ucsc please note the Notes section.

achave11-ucsc

Pro forma approval.

hannes-ucsc self-assigned this Apr 27, 2026

hannes-ucsc linked an issue Apr 27, 2026 that may be closed by this pull request

Implement authorization code flow with Azul and Data Browser #7954

Open

hannes-ucsc force-pushed the issues/hannes-ucsc/7954-oauth-flow branch from 726c9bf to b82e299 Compare April 27, 2026 16:30

hannes-ucsc added 6 commits April 27, 2026 09:46

Fix formatting

92bf189

Rename class

ee57df8

… in preparation for the extraction of a delegatee

Extract class and delegate to it

8fbd47c

Reorder module members

795bb1c

Rename method

0f56f56

Rename variable

23a2096

hannes-ucsc force-pushed the issues/hannes-ucsc/7954-oauth-flow branch from b82e299 to 3802fb2 Compare April 27, 2026 16:46

Assert shape of OAuth2 /tokeninfo response

40f185e

hannes-ucsc force-pushed the issues/hannes-ucsc/7954-oauth-flow branch from 3802fb2 to d56c0a4 Compare April 27, 2026 17:47

Add caveat about possibly outdated instruction in README

0a06e2c

hannes-ucsc added API API change affecting callers upgrade [process] PR includes commit requiring manual upgrade labels Apr 28, 2026

hannes-ucsc force-pushed the issues/hannes-ucsc/7954-oauth-flow branch from d56c0a4 to ea0fc8b Compare April 28, 2026 14:31

hannes-ucsc added 2 commits April 28, 2026 18:34

[u a] Implement authorization code flow with Azul and Data Browser (#…

e3fb7c4

…7954)

Add FIXME (#7625)

7c0f020

hannes-ucsc force-pushed the issues/hannes-ucsc/7954-oauth-flow branch from ea0fc8b to 7c0f020 Compare April 29, 2026 01:35

hannes-ucsc assigned achave11-ucsc Apr 29, 2026

achave11-ucsc added the sandbox [process] Resolution is being verified in sandbox deployment label Apr 29, 2026

achave11-ucsc approved these changes Apr 29, 2026

View reviewed changes

achave11-ucsc merged commit e18d4f9 into develop Apr 29, 2026
10 checks passed

achave11-ucsc deleted the issues/hannes-ucsc/7954-oauth-flow branch April 29, 2026 21:57

achave11-ucsc unassigned hannes-ucsc Apr 29, 2026

achave11-ucsc assigned dsotirho-ucsc and unassigned achave11-ucsc May 4, 2026

dsotirho-ucsc removed their assignment May 6, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Implement authorization code flow with Azul and Data Browser (#7954)#7961

Implement authorization code flow with Azul and Data Browser (#7954)#7961
achave11-ucsc merged 10 commits into
developfrom
issues/hannes-ucsc/7954-oauth-flow

hannes-ucsc commented Apr 27, 2026 •

edited by dsotirho-ucsc

Loading

Uh oh!

codecov Bot commented Apr 27, 2026 •

edited

Loading

Uh oh!

coveralls commented Apr 27, 2026 •

edited

Loading

Uh oh!

hannes-ucsc commented Apr 29, 2026 •

edited

Loading

Uh oh!

hannes-ucsc commented Apr 29, 2026

Uh oh!

hannes-ucsc commented Apr 29, 2026

Uh oh!

achave11-ucsc left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

hannes-ucsc commented Apr 27, 2026 • edited by dsotirho-ucsc Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Notes

Checklist

Author

Author (partiality)

Author (reindex)

Author (mirror)

Author (API changes)

Author (upgrading deployments)

Author (hotfixes)

Author (before every review)

Peer reviewer (after approval)

System administrator (after approval)

Operator

Operator (deploy .shared and .gitlab components)

System administrator (post-deploy of .gitlab component)

Operator (deploy runner image)

Operator (sandbox build)

Operator (merge the branch)

Operator (main build)

Operator (upgrading)

Operator (main build cont'd)

Operator (reindex)

Operator (mirroring)

Operator

Shorthand for review comments

Uh oh!

codecov Bot commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

coveralls commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hannes-ucsc commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Security Design Review

Architecture Summary

Positive Security Properties

Findings

Conclusion

Uh oh!

hannes-ucsc commented Apr 29, 2026

Security design review

Uh oh!

hannes-ucsc commented Apr 29, 2026

Uh oh!

achave11-ucsc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

hannes-ucsc commented Apr 27, 2026 •

edited by dsotirho-ucsc

Loading

Operator (deploy `.shared` and `.gitlab` components)

System administrator (post-deploy of `.gitlab` component)

codecov Bot commented Apr 27, 2026 •

edited

Loading

coveralls commented Apr 27, 2026 •

edited

Loading

hannes-ucsc commented Apr 29, 2026 •

edited

Loading