[LFXV2-888] Auth flows docs#20
[LFXV2-888] Auth flows docs#20mauriciozanettisalomao wants to merge 14 commits intolinuxfoundation:mainfrom
Conversation
- Introduced new documentation files detailing various authentication flows, including M2M profile lookup, SSR OIDC login, profile updates, social identity linking, and passwordless email linking. - Added comprehensive sequence diagrams for each flow to illustrate the interactions between components. - Created subjects documentation for email lookups, email verification, identity linking, user emails, and user metadata operations, enhancing clarity on service interactions. This update improves the overall understanding of the authentication processes and their implementation within the system. Jira Ticket: https://linuxfoundation.atlassian.net/browse/LFXV2-888 Generated with [Claude Code](https://claude.com/claude-code) Signed-off-by: Mauricio Zanetti Salomao <mauriciozanetti86@gmail.com>
…thentication flows - Renamed access tokens in sequence diagrams for clarity, changing `access_token0`, `access_token1`, and `access_token2` to more descriptive names like `access_token_m2m_read`, `access_token_lfxv2`, and `access_token_mgmt_self`. - Enhanced documentation in the README to provide a comprehensive overview of authentication flows, including descriptions of clients, token usage, and key architecture patterns. - Added a new README file to centralize information about the authentication architecture and flows used in LFX One. This update improves the clarity and usability of the authentication documentation. Jira Ticket: https://linuxfoundation.atlassian.net/browse/LFXV2-888 Generated with [Claude Code](https://claude.com/claude-code) Signed-off-by: Mauricio Zanetti Salomao <mauriciozanetti86@gmail.com>
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughAdds a new auth-flows documentation suite (Flows A–E) with sequence diagrams and control-flow descriptions, updates several relative documentation links to subject-scoped paths, and removes the "Auth0 Configuration Requirements" subsection from internal Auth0 docs. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs). Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Jira integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (6)
docs/auth-flows/A-auth-service-m2m-profile-lookup.md(1 hunks)docs/auth-flows/B-lfx-one-login-ssr-oidc.md(1 hunks)docs/auth-flows/C-auth-service-m2m-profile-update.md(1 hunks)docs/auth-flows/D-spa-social-identity-linking.md(1 hunks)docs/auth-flows/E-passwordless-email-linking.md(1 hunks)docs/auth-flows/README.md(1 hunks)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Agent
- GitHub Check: MegaLinter
🔇 Additional comments (8)
docs/auth-flows/C-auth-service-m2m-profile-update.md (1)
3-48: Flow documentation is clear and accurate.The sequence diagram, validation step (C5), and NATS integration are well documented. The cross-reference to Flow B and the validation that
id_token_user.sub == access_token_mgmt_self.subcorrectly enforces user identity consistency.docs/auth-flows/README.md (3)
16-22: Flow table is well-organized; update cross-reference if Flow C filename changes.The table clearly maps flows to clients, audiences, and purposes. However, if the Flow C filename is updated (per the previous review), line 20's reference to
C-auth-service-m2m-profile-update.mdwill need to be updated to match the new filename.
24-50: Client and token documentation is accurate and well-structured.Descriptions are clear and consistent with individual flow documents. Token audience and scope mappings align with the documented flows. The distinction between ignored tokens (
access_token_social,access_token_pwdless) and used tokens is helpful.
52-82: Architecture patterns and security considerations are comprehensive.The sections cover NATS pub/sub, Auth Service abstraction, token validation, flow dependencies, and key security principles (principle of least privilege, subject validation, email verification, token scoping). This provides good context for understanding the overall architecture.
docs/auth-flows/A-auth-service-m2m-profile-lookup.md (1)
1-34: Clear documentation of Auth Service M2M flow with appropriate security emphasis.The sequence diagram accurately shows token caching, client_credentials grant, and proper scope restrictions (read:users only). The emphasis on "NOT update:users" aligns with the principle of least privilege documented in the README.
docs/auth-flows/E-passwordless-email-linking.md (1)
1-59: Comprehensive passwordless email linking flow documentation.The sequence diagram clearly illustrates the OTP verification process, email validation step (E6), and secure linking via the Management API token from Flow C. The flow is well-organized and cross-references Flow C appropriately.
docs/auth-flows/B-lfx-one-login-ssr-oidc.md (1)
1-40: Standard OIDC flow documentation is accurate and well-presented.The sequence diagram correctly shows the authorization_code grant flow with proper audience and client identification. The note about token usage (line 39) clarifies scope. References to Traefik/Heimdall provide helpful architectural context.
docs/auth-flows/D-spa-social-identity-linking.md (1)
1-52: Social identity linking flow documentation is clear and comprehensive.The sequence diagram accurately shows the popup/webmessage pattern, client reuse with Flow C ("LFX One Profile"), and proper use of the Management API token. The "no audience" pattern is correct for social provider authentication.
There was a problem hiding this comment.
Pull request overview
This pull request adds comprehensive documentation for authentication flows and NATS subjects in LFX One, providing detailed sequence diagrams and step-by-step descriptions to help developers understand the authentication architecture.
- Introduces five authentication flow diagrams (A-E) covering M2M profile lookups, SSR OIDC login, self-service profile updates, social identity linking, and passwordless email linking
- Adds NATS subject documentation for user metadata, user emails, identity linking, email verification, and email lookups
- Creates a centralized README explaining flow relationships, client responsibilities, token usage, and security considerations
Reviewed changes
Copilot reviewed 6 out of 11 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/auth-flows/README.md | Central overview of authentication flows, clients, tokens, and architecture patterns |
| docs/auth-flows/A-auth-service-m2m-profile-lookup.md | Documents M2M flow for Auth Service reading user profiles |
| docs/auth-flows/B-lfx-one-login-ssr-oidc.md | Documents main SSR OIDC login flow for LFX One |
| docs/auth-flows/C-auth-service-m2m-profile-update.md | Documents self-service profile update flow via Management API |
| docs/auth-flows/D-spa-social-identity-linking.md | Documents social identity linking via popup authentication |
| docs/auth-flows/E-passwordless-email-linking.md | Documents passwordless email verification and linking flow |
| docs/subjects/user_metadata.md | Documents NATS subjects for user metadata read/update operations |
| docs/subjects/user_emails.md | Documents NATS subjects for retrieving user email addresses |
| docs/subjects/identity_linking.md | Documents NATS subject for linking verified identities |
| docs/subjects/email_verification.md | Documents two-step email verification flow with OTP |
| docs/subjects/email_lookups.md | Documents NATS subjects for email-to-username and email-to-sub lookups |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
mauriciozanettisalomao
changed the title
…umentation - Renamed the SSR Client to LFX One Client for consistency and clarity in the README and sequence diagrams. - Updated descriptions for various clients to accurately reflect their roles and functionalities within the authentication architecture. - Enhanced the sequence diagram for the LFX One Login (SSR OIDC) flow to specify the "LFX One" client in the authorization requests. Jira Ticket: https://linuxfoundation.atlassian.net/browse/LFXV2-888 Generated with [Claude Code](https://claude.com/claude-code) Signed-off-by: Mauricio Zanetti Salomao <mauriciozanetti86@gmail.com>
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Jira integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (2)
docs/auth-flows/B-lfx-one-login-ssr-oidc.md(1 hunks)docs/auth-flows/README.md(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/auth-flows/README.md
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: MegaLinter
- Added new dependencies: `github.com/google/uuid` and `github.com/lestrrat-go/jwx/v2`. - Updated existing dependencies to their latest versions, including `goa.design/goa/v3` and various `golang.org/x` packages. - Revised documentation links in the README and related files to reflect the new directory structure for subjects. - Adjusted paths in documentation files to ensure correct navigation to internal resources. Jira Ticket: https://linuxfoundation.atlassian.net/browse/LFXV2-888 Signed-off-by: Mauricio Zanetti Salomao <mauriciozanetti86@gmail.com>
- Corrected the path for the Email Verification Documentation in the README to reflect the new directory structure for subjects. Jira Ticket: https://linuxfoundation.atlassian.net/browse/LFXV2-888 Signed-off-by: Mauricio Zanetti Salomao <mauriciozanetti86@gmail.com>
- Introduced a new documentation file detailing the second OIDC flow for the Auth0 Management API audience, enabling users to manage their own profiles. - Updated Flow D and Flow E documentation to reference the new access token naming convention. - Revised the README to link to the new Flow C documentation. This addition enhances the clarity and usability of the authentication documentation for self-service profile updates. Jira Ticket: https://linuxfoundation.atlassian.net/browse/LFXV2-888 Reviewed with [GitHub Copilot](https://github.com/features/copilot) Signed-off-by: Mauricio Zanetti Salomao <mauriciozanetti86@gmail.com>
- Updated the description of Flow C to clarify its purpose and relationship with Flow D's SPA client. - Removed outdated token validation details from the README to streamline the content. These changes enhance the clarity and accuracy of the documentation for the self-service profile update flow. Jira Ticket: https://linuxfoundation.atlassian.net/browse/LFXV2-888 Signed-off-by: Mauricio Zanetti Salomao <mauriciozanetti86@gmail.com>
mauriciozanettisalomao
changed the title
…dates and social identity linking; remove outdated SPA flow documentation; update README with architecture changes Jira Ticket: https://linuxfoundation.atlassian.net/browse/LFXV2-888 Assisted by [Claude Code](https://claude.ai/code) Signed-off-by: Mauricio Zanetti Salomao <mauriciozanetti86@gmail.com>
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (5)
docs/auth-flows/D-social-identity-linking.md (2)
4-4: Clarify terminology: "webmessage" pattern description.The term "webmessage" may be unclear to readers unfamiliar with OAuth/OIDC response modes. Consider clarifying whether you mean the response_mode=form_post pattern, a custom message-passing pattern, or replacing with "web-based message" or "popup redirect" pattern for clarity.
1-48: Add error handling and edge-case documentation.The sequence diagram and description cover the happy path clearly, but the documentation lacks guidance on common error scenarios:
- What happens if the user denies social provider authentication (e.g., rejects Google login)?
- What if the identity is already linked to another user?
- What if the identity is already linked to the same user?
- How are Management API errors (403, 409, etc.) handled and communicated back to the UI?
Consider adding a dedicated "Error Scenarios" or "Error Handling" section, or defer this to a separate troubleshooting guide referenced in the central README.
docs/auth-flows/C-profile-update.md (3)
33-33: Document C5 validation failure handling.Step C5 performs a critical security check (id_token_user.sub == access_token_mgmt_self.sub), but the documentation does not explain what happens if this validation fails:
- Should SSR reject the request and return an error to the UI?
- What error status/message is appropriate?
- Should this be logged for security auditing?
Add a subsection describing the validation failure path and error handling.
31-31: Clarify scope and capabilities of access_token_mgmt_self.The diagram shows that access_token_mgmt_self is issued in step C4 and used later in Flow D. The documentation should clarify:
- What are the claims/scopes included in access_token_mgmt_self (e.g.,
aud,sub, management API scopes)?- What specific Management API operations can this token authorize?
- Why is id_token_mgmt (returned in C4) marked "IGNORE"?
- What is the token lifetime and are there refresh/expiration considerations?
Add a brief note or reference to token specifications (link to Auth0 docs, if applicable).
1-48: Add security considerations section.Both Flow C and Flow D documentation include brief notes that "Auth Service abstracts all Auth0 Management API calls," but lack explicit security considerations. Consider adding a dedicated section covering:
- Why the C5 subject validation is critical (prevents cross-user attacks).
- Token scope limitations (management API token is restricted to the authenticated user).
- Audit logging recommendations (what events should be logged when?).
- OIDC/OAuth best practices being followed (PKCE for authorization code grant, signed tokens, etc.).
This may be appropriate as a shared section in the central README or as a subsection in Flow C documentation (since C5 is the security checkpoint).
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Jira integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (5)
docs/auth-flows/C-profile-update.md(1 hunks)docs/auth-flows/D-social-identity-linking.md(1 hunks)docs/auth-flows/E-passwordless-email-linking.md(1 hunks)docs/auth-flows/README.md(1 hunks)internal/infrastructure/auth0/README.md(0 hunks)
💤 Files with no reviewable changes (1)
- internal/infrastructure/auth0/README.md
🚧 Files skipped from review as they are similar to previous changes (2)
- docs/auth-flows/README.md
- docs/auth-flows/E-passwordless-email-linking.md
🧰 Additional context used
🪛 LanguageTool
docs/auth-flows/D-social-identity-linking.md
[grammar] ~4-~4: Ensure spelling is correct
Context: ... server-side redirects instead of popup/webmessage pattern. ## Sequence Diagram ```merma...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: MegaLinter
…tion flow descriptions Jira Ticket: https://linuxfoundation.atlassian.net/browse/LFXV2-888 Assisted by [Claude Code](https://claude.ai/code) Signed-off-by: Mauricio Zanetti Salomao <mauriciozanetti86@gmail.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/auth-flows/README.md (1)
1-75: Consider adding dedicated audiences section and troubleshooting guidance for completeness.The README provides a solid overview of flows, clients, and architecture patterns. However, three areas could be enhanced:
Dedicated Audiences Documentation: While audiences (
auth0_mgmt,lfxv2) are referenced in tables and descriptions, a standalone section explaining each audience's purpose, configuration, and integration points would improve clarity.Troubleshooting Guidance: Adding common troubleshooting scenarios (e.g., token validation failures, audience mismatches, refresh token issues) would help developers debug issues faster.
Code References: Links to relevant implementation details (e.g., Auth Service token validation, NATS handlers, profile update endpoints) would connect documentation to code.
These additions would benefit the documentation but may belong in individual flow-specific files or a separate troubleshooting guide rather than in this overview README.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Jira integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
docs/auth-flows/README.md(1 hunks)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: MegaLinter
Jira Ticket: https://linuxfoundation.atlassian.net/browse/LFXV2-888 Reviewed with [GitHub Copilot](https://github.com/features/copilot) Signed-off-by: Mauricio Zanetti Salomao <mauriciozanetti86@gmail.com>
|
Can we add a step to "flow D" that id_token_3 (which is "id_token_social" in the sequence diagram) must be validated to confirm that it is in fact a social identity, NOT a database user ( |
… error handling and sequence of operations. Jira Ticket: https://linuxfoundation.atlassian.net/browse/LFXV2-888 Generated with [Claude Code](https://claude.com/claude-code) Signed-off-by: Mauricio Zanetti Salomao <mauriciozanetti86@gmail.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/auth-flows/D-social-identity-linking.md (1)
31-31: Clarify whyaccess_token_socialshould be ignored.The diagram notes
access_token_socialis returned for/userinfo (IGNORE)but doesn't explain why this token is ignored whileaccess_token_mgmt_selffrom Flow C is used instead. Consider adding a brief note explaining that the social access token is not needed because the linking operation requires the Management API token (from Flow C) rather than a userinfo-scoped token.📝 Suggested clarification
- Auth0-->>SSR: D4: access_token_social<br/>for /userinfo (IGNORE) +<br/>id_token_social + Auth0-->>SSR: D4: access_token_social<br/>for /userinfo (not used - linking requires Mgmt API token) +<br/>id_token_social🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/auth-flows/D-social-identity-linking.md` at line 31, Update the diagram text to briefly explain why access_token_social (returned to SSR for /userinfo) is ignored: add a short note stating that access_token_social is userinfo-scoped and cannot call the Management API, and therefore the linking operation uses access_token_mgmt_self from Flow C which contains Management API scopes/permissions required for identity linking; reference the tokens access_token_social, access_token_mgmt_self, the /userinfo call, and Flow C in the note so readers can connect the explanation to the diagram.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/auth-flows/D-social-identity-linking.md`:
- Around line 33-49: Docs describe Flow D (social identity linking) but the
service lacks the implementation; add a handler for social linking that mirrors
Flow E's LinkIdentity logic: create a new NATS subject/handler for the social
link request, validate id_token_social.sub — if it startsWith "auth0|" return
the same error used in docs ("cannot link two LFID accounts"), otherwise call
the management-linking flow using access_token_mgmt_self and the id_token_social
claims, perform the identity link via the Auth0 management client, publish the
response back on NATS, and wire this handler into the dispatcher where
message_handler.go references social linking (the same place that registers
LinkIdentity) so the documented Flow D behavior is implemented end-to-end.
---
Nitpick comments:
In `@docs/auth-flows/D-social-identity-linking.md`:
- Line 31: Update the diagram text to briefly explain why access_token_social
(returned to SSR for /userinfo) is ignored: add a short note stating that
access_token_social is userinfo-scoped and cannot call the Management API, and
therefore the linking operation uses access_token_mgmt_self from Flow C which
contains Management API scopes/permissions required for identity linking;
reference the tokens access_token_social, access_token_mgmt_self, the /userinfo
call, and Flow C in the note so readers can connect the explanation to the
diagram.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: e84e2ceb-7a80-4d0f-bedf-7ddb29725662
📒 Files selected for processing (1)
docs/auth-flows/D-social-identity-linking.md
Overview
Jira Ticket: https://linuxfoundation.atlassian.net/browse/LFXV2-888
This pull request significantly improves the documentation for LFX One authentication by adding detailed sequence diagrams for all major authentication flows, introducing a comprehensive overview of the authentication architecture, and reorganizing subject-specific documentation for better clarity and maintainability.
Important
Flow has changed - more details below:
Authentication Flow Documentation:
Centralized Overview and Architecture:
README.mdthat explains the purpose and relationships of each authentication flow, describes the different Auth0 clients, and provides tables for token usage and client responsibilities.Updating dependencies to fix the following run