TECH_DEBT: Adding documentation for security (#571)

### 🛠️ Description of Changes - **Documentation** - Updated the README to include a new "Kafka Retry Topics" entry and a new "Security" section with links to detailed documents. - Introduced new documents: - `oauth_cookie_flow.md` outlining the OAuth 2.0 authentication flow. - `security_overview.md` providing an overview of the security model and Role-Based Access Control (RBAC). ### 🧪 Testing Performed No testing necessary. Documentation updates only. ### 📓 Documentation Updated Pages added for security.  ## Summary by CodeRabbit - **New Features** - Introduced a "Security" section in the documentation, enhancing organization and clarity. - Added comprehensive documentation on security overview and OAuth authentication flow. - **Documentation** - Updated README to include links to new security-related documents. - Created detailed documentation files for "Security Overview" and "OAuth & Cookie Flow". - **Bug Fixes** - Removed duplicate entry for "Kafka Retry Topics" from the README.
lantanagroup · Dec 17, 2024 · 9b031a5 · 9b031a5
2 parents 8e055a6 + 6cc0e88
commit 9b031a5
Show file tree

Hide file tree

Showing 4 changed files with 247 additions and 1 deletion.
diff --git a/docs/README.md b/docs/README.md
@@ -8,10 +8,13 @@ This page and its references include documentation for Link's services and the f
 * [Admin UI](functionality/admin_ui.md)
 * [Census Management](functionality/census_management.md)
 * [Data Acquisition](functionality/data_acquisition.md)
+* [Kafka Retry Topics](functionality/retry_topics.md)
 * [Measure Evaluation](functionality/measure_eval.md)
 * [Notifications](functionality/notifications.md)
 * [Normalization](functionality/normalization.md)
-* [Kafka Retry Topics](functionality/retry_topics.md)
+* Security
+  * [Security Overview](functionality/security_overview.md)
+  * [OAuth & Cookie Flow](functionality/oauth_flow.md)
 * [Submission Folder Structure](functionality/submission_folder.md)
 * [Telemetry](functionality/telemetry.md)
 * [Tenant/Facility Management](functionality/tenant_mgmt.md)

diff --git a/docs/functionality/oauth_flow.md b/docs/functionality/oauth_flow.md
@@ -0,0 +1,165 @@
+## Overview
+
+The Link Admin BFF (Backend for Frontend) implements a secure authentication flow using OAuth 2.0 with cookie-based session management. This provides a robust security model where the BFF acts as the OAuth client and manages user sessions through secure HTTP-only cookies.
+
+## Authentication Flow
+
+1. **Initial Login Request**
+
+    - The UI redirects users to `/api/login` on the BFF
+    - The BFF initiates the OAuth authorization code flow by redirecting to the configured OAuth provider
+    - The OAuth provider authenticates the user and returns an authorization code
+
+2. **Token Exchange & Session Creation**
+
+    - The BFF exchanges the authorization code for access/refresh tokens
+    - The BFF creates a session and issues a secure HTTP-only cookie named "link_cookie"
+    - The cookie contains session information but not the actual OAuth tokens
+    - OAuth tokens are securely stored server-side and managed by the BFF
+
+3. **Subsequent Requests**
+
+    - The UI includes the session cookie automatically with each request
+    - The BFF validates the cookie and retrieves the associated session
+    - The BFF uses the OAuth tokens to make authenticated requests to backend services
+    - Token refresh is handled transparently by the BFF when needed
+
+## Cookie Security
+
+- Cookies are HTTP-only to prevent XSS attacks
+- Secure flag ensures cookies only sent over HTTPS
+- Anti-forgery protection enabled
+- Session cookies with server-side storage
+
+## Token Security
+
+- OAuth tokens never exposed to the frontend
+- Tokens stored securely server-side
+- Token refresh handled by BFF
+- Short-lived access tokens with automatic refresh
+
+## CORS Protection
+
+- Strict CORS policy configured
+- Credentials mode enabled for cookie transmission
+- Only trusted origins allowed
+
+## PKCE (Proof Key for Code Exchange)
+
+PKCE is implemented to secure the OAuth authorization code flow and prevent authorization code interception attacks:
+
+**Code Verifier Generation**
+
+   - A cryptographically random code verifier is generated for each authentication request
+   - The verifier is stored securely server-side in the BFF
+   - Length and character requirements follow OAuth PKCE specifications
+
+**Code Challenge**
+
+   - The code challenge is derived from the verifier using SHA-256
+   - Challenge is included in the initial authorization request
+   - The challenge method is set to "S256" (SHA-256)
+
+**Code Exchange**
+
+   - Original code verifier is included when exchanging the authorization code
+   - OAuth provider validates the code challenge/verifier pair
+   - Prevents malicious actors from using intercepted auth codes
+
+## State Parameter Protection
+
+The state parameter provides CSRF protection during the OAuth flow:
+
+**State Generation**
+
+   - Cryptographically secure random state value generated per request
+   - State is bound to the user's session
+   - Stored server-side in the BFF
+
+**State Validation**
+
+   - State parameter included in authorization request
+   - Returned state must match the original stored value
+   - Requests with invalid/missing state are rejected
+   - Protects against CSRF and replay attacks
+
+## Scope Restrictions
+
+OAuth scopes are strictly controlled to limit access:
+
+**Required Scopes**
+
+openid profile email
+
+**Scope Validation**
+
+- Only pre-configured scopes are allowed
+- Scope requests are validated against allowed list
+- Additional scopes require explicit configuration
+- Prevents scope elevation attacks
+
+**Scope Usage**
+
+- Scopes map to specific API permissions
+- Access tokens only receive approved scopes
+- Resource access is restricted by granted scopes
+
+## Configuration
+
+The BFF's OAuth and cookie settings are configured in `appsettings.json`:
+
+```json
+"Authentication": {
+  "DefaultScheme": "link_cookie",
+  "DefaultChallengeScheme": "link_oauth2",
+  "Schemas": {
+    "Cookie": {
+      "HttpOnly": true,
+      "Domain": "",
+      "Path": "/"
+    },
+    "Oauth2": {
+      "Enabled": true,
+      "ClientId": "",
+      "ClientSecret": "",
+      "Endpoints": {
+        "Authorization": "",
+        "Token": "",
+        "UserInformation": ""
+      },
+      "CallbackPath": "/api/signin-oauth2"
+    }
+  }
+}
+```
+
+## UI Integration
+
+The UI application interacts with the BFF's authentication system through:
+
+### Login
+
+```javascript
+// Redirect to BFF login endpoint
+window.location.href = '/api/login';
+```
+
+### Session Status
+
+```javascript
+// Check if user is authenticated
+fetch('/api/user', {
+credentials: 'include' // Important for cookie transmission
+});
+```
+
+### Logout
+
+```javascript
+// Redirect to BFF logout endpoint
+    window.location.href = '/api/logout';
+```
+
+---
+
+The UI never directly handles OAuth tokens or credentials - all authentication is delegated to and managed by the BFF.
diff --git a/docs/functionality/security_overview.md b/docs/functionality/security_overview.md
@@ -0,0 +1,78 @@
+# Security Overview
+
+The Link system implements Role-Based Access Control (RBAC) through a claims-based authorization model. Currently, the system has a single "Admin" role configured which has access to all available permissions.
+
+![RBAC](../images/security.png)
+
+## Claims/Permissions
+
+The following claims define what actions users can perform in the system:
+
+| Claim                       | Description                                          |
+|-----------------------------|------------------------------------------------------|
+| CanViewLogs                 | Allows viewing system audit and activity logs        |
+| CanViewNotifications        | Allows viewing system notifications and alerts       |
+| CanViewTenantConfigurations | Allows viewing tenant configuration settings         |
+| CanEditTenantConfigurations | Allows modifying tenant configuration settings       |
+| CanAdministerAllTenants     | Grants full administrative access across all tenants |
+| CanViewResources            | Allows viewing system resources                      |
+| CanViewReports              | Allows viewing generated reports                     |
+| CanGenerateReports          | Allows generating new reports                        |
+| CanGenerateEvents           | Allows generating system events                      |
+| CanViewAccounts             | Allows viewing user accounts                         |
+| CanAdministerAccounts       | Allows creating/modifying/deleting user accounts     |
+| IsLinkAdmin                 | Designates the user as a system administrator        |
+
+## Roles
+
+Currently, only a single role is configured in the system:
+
+**Admin Role**
+
+- Has access to all claims/permissions listed above
+- Full system administrative capabilities
+- No tenant-level restrictions
+
+## Implementation
+
+The RBAC system is implemented through:
+
+- Claims defined in `LinkSystemPermissions` enum
+- Authorization policies that map to individual claims
+- Role and user entities that maintain claim assignments
+- Claims-based authorization checks in the application
+
+## Future Considerations
+
+### Expanded Claims
+
+The system is designed to support additional claims, particularly:
+- UI-specific permissions for granular interface control
+- Additional operational permissions as new features are added
+- Workflow-specific permissions
+
+### Additional Roles
+
+Plans for expanding role definitions include:
+
+- Creating non-administrative roles with limited permissions
+- Role hierarchies
+- Custom role definitions per tenant
+
+### Tenant Restrictions
+
+Future updates will include:
+
+- Tenant-specific role definitions
+- User-to-tenant mapping
+- Tenant-scoped permissions
+- Multi-tenant authorization policies
+
+## Technical Details
+
+The authorization system is built on ASP.NET Core's authorization framework using:
+
+- Policy-based authorization
+- Claims-principal based identity
+- Role and claim persistence in SQL database
+- Cached authorization decisions for performance
diff --git a/docs/images/security.png b/docs/images/security.png