Skip to content

Commit 2f2ced8

Browse files
duttarnabduttarnab
authored
docs(admin-ui): update Accessing Config API section of docs (#2608)
* docs: update Accessing Config API section of docs Signed-off-by: duttarnab <arnab.bdutta@gmail.com> * docs: update Accessing Config API section of docs Signed-off-by: duttarnab <arnab.bdutta@gmail.com> * docs: update docs Signed-off-by: duttarnab <arnab.bdutta@gmail.com> * docs: typo correction Signed-off-by: duttarnab <arnab.bdutta@gmail.com> --------- Signed-off-by: duttarnab <arnab.bdutta@gmail.com>
1 parent 4e30a08 commit 2f2ced8

File tree

1 file changed

+59
-44
lines changed

1 file changed

+59
-44
lines changed

‎docs/admin/admin-ui/auth-server-interaction.md‎

Lines changed: 59 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -91,63 +91,78 @@ Gluu Flex Admin UI->>Gluu Flex Admin UI: extract & store claims from UJWT
9191
9292
```
9393

94-
## API Protection and Scopes
95-
96-
To ensure security and access control, Gluu Flex Admin UI leverages API protection and scopes:
94+
## Accessing Config-API Endpoints
9795

98-
1. The Jans Config API's endpoints are protected and can only be accessed using a token (`AT2`) with the required scopes.
99-
2. To generate an AT2, the frontend requests the Token Server via the backend. **The Token Server and Authorization Server can be the same or different.**
100-
3. The Token Server employs an update-token script that validates the UJWT and refers to the role-scope mapping in the Token Server persistence.
101-
4. The update-token script validates the UJWT and includes the appropriate scopes in AT2 based on the user's role.
102-
5. The frontend receives AT2 and associated scopes from the backend.
103-
6. The scopes provided in AT2 determine which Config API–protected endpoints the Admin UI can access. Refer this [doc](./access-control.md) for GUI access control.
96+
To access Config API endpoints, Admin UI Backend generates client_credentials token by following below steps:
97+
98+
1. Admin UI Frontend calls **POST** `/session` endpoint of Admin UI Backend by passing User-Info JWT (UJWT) as parameter.
99+
2. The Admin UI backend verifies the signature of the UJWT. If the signature is valid, it creates session cookie with a random Session ID. Store the mapping of Session ID and UJWT along with created_date and expiry_date into the Jans persistence (in `adminUISession` table).
100+
3. The session cookie is sent back to Admin UI Frontend in response and is stored in browser.
101+
4. For making any request to Config API endpoints the Admin UI Frontend (Browser) will call Config API endpoint. The session cookie will be automatically paired with the request.
102+
5. The Admin UI Backend will intercept the request. It will check if the valid session cookie is present in request.
103+
6. Admin UI Backend will verify the cookie's Session ID presence in `adminUISession` table. Also fetch UJWT of the record from table.
104+
7. If the session cookie is valid then Admin UI Backend will generate client_credentials token (AT2).
105+
8. To generate an AT2, the backend requests the Token Server. **The Token Server and Authorization Server can be the same or different.**
106+
9. The Token Server employs an `update-token script` that validates the UJWT and refers to the role-scope mapping in the persistence.
107+
10. The update-token script validates the UJWT and includes the appropriate scopes in AT2 based on the user's role.
108+
11. The AT2 will be used to call Config API endpoint.
109+
12. The response obtained from Config API will be sent back to the Admin UI Frontend (Browser).
110+
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.
104111

105112
```mermaid
106-
107113
sequenceDiagram
108-
title License Verification
109-
autonumber
110-
actor User
114+
title Accessing Config API Endpoints
115+
autonumber
116+
117+
actor User
118+
participant Browser as Admin UI (Browser)
119+
participant Backend as Admin UI Backend
120+
participant ConfigAPI as Config API
121+
122+
User->>Browser: Login
123+
Browser->>Backend: POST /session
124+
Note right of Browser: userinfo JWT (UJWT)
125+
126+
Backend->>Backend: Verify UJWT
127+
Backend->>Backend: Create session cookie with opaque SessionID
128+
Backend->>Backend: Persist mapping of SessionID ↔ UJWT
129+
Backend->>Browser: Set session cookie
130+
Note right of Browser: Cookie stored in browser
131+
132+
Browser->>Backend: Call Config API endpoints
133+
Note right of Browser: Session cookie
134+
Backend->>Backend: check if session cookie is present in request
135+
Backend->>Backend: clear expired Admin UI sessions from persistence (ran after at least 5 minutes)
136+
Backend->>Backend: checks presence of session in cache or database
137+
alt Session exists in persistence
138+
Backend->>Backend: Generate client-credentials access token (AT2)
139+
Backend->>ConfigAPI: call endpoint
140+
Note right of Backend: AT2
141+
ConfigAPI->>ConfigAPI: verify AT2
142+
ConfigAPI->>Browser: endpoint response
143+
else Session does not exist in persistence
144+
Backend->>Browser: 403 Forbidden (force logout)
145+
end
111146
112-
Gluu Flex Admin UI->>Admin UI Backend: /api-protection-token?ujwt=...
113-
Admin UI Backend->>Jans Token Server: /token
114-
Jans Token Server->>Jans Token Server: Verify ujwt
115-
Jans Token Server->>Jans Token Server: Add scopes to token based on role (AT2)
116-
Jans Token Server->>Admin UI Backend: AT2
117-
Admin UI Backend->>Gluu Flex Admin UI: AT2
118-
Gluu Flex Admin UI->>Gluu Flex Admin UI:extracts scopes from AT2
119-
Gluu Flex Admin UI->>Gluu Flex Admin UI: AT2 determine which Config API–protected endpoints the Admin UI can access
120147
```
121-
## Accessing Config-API Endpoints
122-
123-
To access config-api endpoints, the following steps are taken:
124-
125-
1. The Admin UI frontend requests AT2 from the Token Server through the backend.
126-
2. Armed with AT2, the frontend sends a request to the desired Jans Config API endpoint. AT2 is included in the authorization header, along with other request parameters.
127-
3. At the Jans Config API, AT2 is validated, and the provided scopes are verified to ensure the necessary scope for the requested endpoint is present.
128-
4. If the above steps are successful, the requested data is fetched from the Jans Config API and forwarded to the frontend.
129148

130149
```mermaid
131150
132151
sequenceDiagram
133-
title License Verification
152+
title Details of generation of AT2
134153
autonumber
135154
actor User
155+
participant Backend as Admin UI Backend
156+
participant JansServer as Jans Token Server
157+
participant Script as Update Token Script
158+
159+
Backend->>JansServer: /token
160+
Note right of Backend: UJWT
161+
JansServer->>Script: Verify UJWT
162+
Script->>Script: Add scopes to token based on role (AT2)
163+
Script->>JansServer: AT2
164+
JansServer->>Backend: AT2
136165
137-
Gluu Flex Admin UI->>Admin UI Backend: /api-protection-token?ujwt=...
138-
Admin UI Backend->>Jans Token Server: /token
139-
Jans Token Server->>Jans Token Server: Verify ujwt
140-
Jans Token Server->>Jans Token Server: Add scopes to token based on role (AT2)
141-
Jans Token Server->>Admin UI Backend: AT2
142-
Admin UI Backend->>Gluu Flex Admin UI: AT2
143-
Gluu Flex Admin UI->>Jans Config API: request API with AT2
144-
Jans Config API<<->>Jans Token Server: introspect AT2
145-
Jans Token Server->>Jans Config API: AT2 JSON
146-
Jans Config API->>Jans Config API: Enforcement: verify required scopes
147-
Jans Config API->>Jans Config API: validate params
148-
Jans Config API->>Jans Auth Server:call API with request params
149-
Jans Auth Server->>Jans Config API:response
150-
Jans Config API->>Gluu Flex Admin UI:response
151166
```
152167

153168
## Conclusion

0 commit comments

Comments
 (0)