docs(admin-ui): update Accessing Config API section of docs#2608
docs(admin-ui): update Accessing Config API section of docs#2608
Conversation
Signed-off-by: duttarnab <arnab.bdutta@gmail.com>
Signed-off-by: duttarnab <arnab.bdutta@gmail.com>
📝 WalkthroughWalkthroughThis PR rewrites Admin UI auth docs to a browser-backed, session-centric model: Admin UI validates a UJWT, persists a SessionID↔UJWT mapping, issues a session cookie, generates AT2 via the Token Server/update-token script, and uses AT2 to call Config API with session verification and 403 handling. Changes
Sequence Diagram(s)sequenceDiagram
participant Browser
participant AdminUI as Admin UI Backend
participant DB as Session Store
participant TokenServer as Token Server (AT2)
participant ConfigAPI as Config API
Browser->>AdminUI: POST /auth (UJWT)
AdminUI->>AdminUI: validate UJWT
AdminUI->>DB: create SessionID↔UJWT (persist)
AdminUI-->>Browser: Set-Cookie SessionID
Browser->>ConfigAPI: request (Session cookie)
ConfigAPI->>AdminUI: verify SessionID (cookie)
AdminUI->>DB: lookup SessionID -> UJWT
alt session exists
AdminUI->>TokenServer: request AT2 (client_credentials) using validated UJWT
TokenServer-->>AdminUI: AT2
AdminUI-->>ConfigAPI: call with AT2
ConfigAPI-->>Browser: 200/response
else session missing
ConfigAPI-->>Browser: 403 Forbidden
end
sequenceDiagram
participant AdminUI as Admin UI Backend
participant TokenServer as Jans Token Server
participant UpdateScript as Update Token Script
participant DB as Session Store
AdminUI->>TokenServer: request AT2 (service client)
alt AT2 via Update Token Script
TokenServer->>UpdateScript: run update-token script
UpdateScript-->>TokenServer: return AT2
TokenServer-->>AdminUI: AT2 returned
else direct AT2
TokenServer-->>AdminUI: AT2 returned
end
AdminUI->>DB: store AT2 metadata (optional)
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
mo-auto
added
area-documentation
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
docs/admin/admin-ui/auth-server-interaction.md (3)
7-7: Update heading level to H2.Based on learnings, this repository's Markdown documentation should use H2 headings (##) as the top-level convention. The H1 level is reserved for titles provided by file metadata or external scaffolding.
📝 Proposed fix
-# Interaction with Jans Auth Server +## Interaction with Jans Auth Server
76-79: Correct the sequence diagram title.The diagram title says "License Verification" but this diagram is in the "Authorization Code Flow" section and illustrates the authorization code flow, not license verification.
📝 Proposed fix
```mermaid sequenceDiagram -title License Verification +title Authorization Code Flow autonumber
167-169: Update conclusion to reflect the new implementation.The conclusion references "API protection and scopes," which was the name of the old section. Since this PR replaces that section with "Accessing Config-API Endpoints" and introduces a session-based authentication mechanism, the conclusion should be updated to reflect these changes.
📝 Suggested revision
Consider updating line 169 to something like:
-The Gluu Flex Admin UI simplifies the process of managing configuration and features of the Jans Auth Server through an intuitive graphical user interface. By following the Authorization Code Flow and leveraging API protection and scopes, the Gluu Flex Admin UI ensures secure and controlled interaction with the Jans Auth Server's REST API layer. This seamless interaction empowers administrators to efficiently manage the Jans Auth Server's settings while adhering to strict access controls and security protocols. +The Gluu Flex Admin UI simplifies the process of managing configuration and features of the Jans Auth Server through an intuitive graphical user interface. By following the Authorization Code Flow and implementing session-based authentication with role-based access control, the Gluu Flex Admin UI ensures secure and controlled interaction with the Jans Auth Server's REST API layer. This seamless interaction empowers administrators to efficiently manage the Jans Auth Server's settings while adhering to strict access controls and security protocols.
🤖 Fix all issues with AI agents
In `@docs/admin/admin-ui/auth-server-interaction.md`:
- Around line 94-111: Add an explicit sentence after step 6 (or within step 8)
clarifying that the UJWT retrieved from the adminUISession table is forwarded to
the Token Server as part of the AT2 (client_credential) generation request so
the Token Server's update-token script can validate that UJWT and determine
scopes/roles for the AT2; reference the adminUISession-stored UJWT, the Admin UI
Backend request to the Token Server, the update-token script, and the resulting
AT2 in this clarification.
- Around line 94-111: Replace the incorrect adjective "presence" with "present"
in the two sentences that check the session ID in the adminUISession table (the
sentence in the step that fetches/validates the Session ID/UJWT and the final
step that sends 403), and remove the trailing whitespace found after the
sentence "The AT2 will be used to call Config API endpoint." to clean up
formatting.
- Around line 149-165: Update the sequence diagram so the "ujwt" token label is
consistently capitalized as "UJWT"; specifically change the message from
JansServer->>Script: Verify ujwt to JansServer->>Script: Verify UJWT (the
diagram entries involving JansServer, Script, and the UJWT verification are the
ones to edit).
- Around line 112-147: Fix typos and align the diagram with the documented
persistence behavior: correct "persistance" to "persistence" and "atleast" to
"at least" in the sequenceDiagram, change the text "checks presence of session
in cache or database" to explicitly reference the implemented persistence store
(adminUISession table / Jans persistence) or add a note about caching if a cache
layer exists, and either remove or document the "clear expired Admin UI sessions
from persistence" step in the numbered steps (or reference expiry_date in
adminUISession) so the cleanup mechanism is described consistently between the
diagram and the numbered steps.
Signed-off-by: duttarnab <arnab.bdutta@gmail.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@docs/admin/admin-ui/auth-server-interaction.md`:
- Around line 96-105: The doc uses the singular "client_credential" in
descriptions of the token/flow; update those occurrences to the OAuth-standard
plural "client_credentials" (e.g., when describing the token generated by the
Admin UI Backend, the AT2 generation step that requests the Token Server, and
the parameter example grant_type=client_credentials) so references around POST
/session, the adminUISession-backed session flow, and the AT2/token request use
the correct "client_credentials" terminology consistently.
♻️ Duplicate comments (2)
docs/admin/admin-ui/auth-server-interaction.md (2)
102-110: Fix “present” wording and remove trailing whitespace.These lines still use “presence” instead of “present,” and line 108 has trailing whitespace.
📝 Proposed fix
-5. The Admin UI Backend will intercept the request. It will check if the valid session cookie is present in request. +5. The Admin UI Backend will intercept the request. It will check if the valid session cookie is present in the request. ... -11. The AT2 will be used to call Config API endpoint. +11. The AT2 will be used to call Config API endpoint. -13. If the cookie's Session ID is not presence in `adminUISession` table, send **403-Forbidden** error in response asking Admin UI to force logout. +13. If the cookie's Session ID is not present in `adminUISession` table, send **403-Forbidden** error in response asking Admin UI to force logout.
134-136: Align diagram with persistence-only flow (and cleanup).The diagram still mentions “cache or database” checks and a cleanup step that aren’t described in the numbered steps. Either document the cache/cleanup behavior in the steps or align the diagram to the adminUISession persistence flow.
📝 Possible diagram alignment
- Backend->>Backend: clear expired Admin UI sessions from persistence (ran after at least 5 minutes) - Backend->>Backend: checks presence of session in cache or database + Backend->>Backend: checks presence of session in adminUISession (Jans persistence)
Signed-off-by: duttarnab <arnab.bdutta@gmail.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@docs/admin/admin-ui/auth-server-interaction.md`:
- Line 108: Remove the trailing whitespace at the end of the sentence "11. The
AT2 will be used to call Config API endpoint." in the docs file by editing that
line (the line containing that exact sentence) and deleting the final space
character so the line ends immediately after the period.
♻️ Duplicate comments (2)
docs/admin/admin-ui/auth-server-interaction.md (2)
96-96: Improve phrasing for better readability.The phrase "by following below steps" is somewhat awkward. Consider rewording to "by following the steps below" for more natural English.
📝 Proposed improvement
-To access Config API endpoints, Admin UI Backend generates client_credentials token by following below steps: +To access Config API endpoints, Admin UI Backend generates client_credentials token by following the steps below:
110-110: Fix grammatical error: "presence" → "present"Line 110 uses "is not presence in" which is grammatically incorrect. The adjective form "present" should be used instead.
This issue was flagged in a previous review but remains unfixed.
📝 Proposed fix
-13. If the cookie's Session ID is not presence in `adminUISession` table, send **403-Forbidden** error in response asking Admin UI to force logout. +13. If the cookie's Session ID is not present in `adminUISession` table, send **403-Forbidden** error in response asking Admin UI to force logout.
| 8. To generate an AT2, the backend requests the Token Server. **The Token Server and Authorization Server can be the same or different.** | ||
| 9. The Token Server employs an `update-token script` that validates the UJWT and refers to the role-scope mapping in the persistence. | ||
| 10. The update-token script validates the UJWT and includes the appropriate scopes in AT2 based on the user's role. | ||
| 11. The AT2 will be used to call Config API endpoint. |
There was a problem hiding this comment.
Remove trailing whitespace.
Static analysis detected a trailing space at the end of Line 108. This should be removed to maintain clean formatting.
📝 Proposed fix
Remove the single trailing space at the end of line 108.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
108-108: Trailing spaces
Expected: 0 or 2; Actual: 1
(MD009, no-trailing-spaces)
🤖 Prompt for AI Agents
In `@docs/admin/admin-ui/auth-server-interaction.md` at line 108, Remove the
trailing whitespace at the end of the sentence "11. The AT2 will be used to call
Config API endpoint." in the docs file by editing that line (the line containing
that exact sentence) and deleting the final space character so the line ends
immediately after the period.
3 participants
closes #2605
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.