Security Controls

Token Handling, Headers, CORS & CSRF Protection

---

1. Token Strategy

OpenG2P uses OIDC-compliant tokens issued by the Identity Provider (Keycloak).

---

1.1 Token Types

Token	Purpose	Usage in OpenG2P
ID Token	Represents authenticated user identity	Used by frontend / IAM layer (not for API authorization)
Access Token	Grants access to APIs	Used by backend APIs for authentication & RBAC

---

1.2 ID Token Handling

The ID Token contains user identity claims such as:

• sub (user id)

• email

• name

• preferred_username

Usage Guidelines

• Used only during authentication phase

• Used by IAM API for session/user context

• NOT used for API authorization

Important: Authorization decisions must always be based on the Access Token, not the ID Token.

---

1.3 Access Token Handling (Primary Security Token)

The Access Token is the authoritative token for:

• API authentication

• Role extraction

• RBAC enforcement

---

1.4 Token Storage (Cookie-Based Approach)

The Access Token is stored in a secure HTTP-only cookie.

Cookie Configuration

Set-Cookie: access_token=abc123;
  Domain=.dev.openg2p.org;
  HttpOnly;
  Secure;
  SameSite=Lax;
  Path=/api;
  Max-Age=900

---

1.5 Attribute Explanation

Attribute	Purpose
HttpOnly	Prevents JavaScript access (protects against XSS)
Secure	Ensures transmission only over HTTPS
SameSite=Lax	Protects against CSRF
Domain=.dev.openg2p.org	Enables sharing across subdomains, within the same environment. openg2p.org - represents the domain dev - represents the environment (within the domain)
Path=/api	Restricts usage to API endpoints
Max-Age=900	Token lifetime (15 minutes)

---

---

1.7 Design Rationale

Decision	Reason
Use cookies for Access Token	Protects against XSS
HttpOnly flag	Prevents token theft via JS
Separate ID & Access usage	Aligns with OIDC best practices
Avoid ID token for APIs	Prevents misuse of identity token

---

2. Security Headers

IAM APIs enforce security headers:

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block

---

2.1 Header Purpose

Header	Description
nosniff	Prevents MIME-type sniffing
DENY	Blocks iframe embedding (clickjacking protection)
X-XSS-Protection	Legacy browser protection

---

3. CORS Configuration

3.1 Allowed Origins

allow_origins = [
    "https://staff-portal.openg2p.org",
    "https://registry-staff-portal.openg2p.org",
    "https://pbms-staff-portal.openg2p.org",
]

---

3.2 Credentials Support

allow_credentials = True

Implications

• Cookies (including access token) are sent automatically

• Requires strict origin whitelisting

---

4. CSRF Protection Mechanism

Since authentication is cookie-based, CSRF protection is mandatory.

---

4.1 CSRF Token Cookie

Set-Cookie: csrf_token=UUID;
  Domain=.dev.openg2p.org;
  Secure;
  SameSite=Lax;
  Path=/api;
  Max-Age=900

---

4.2 Cookie Comparison

Cookie	HttpOnly	Purpose
access_token	✅ Yes	Authentication
csrf_token	❌ No	CSRF validation

---

4.3 Frontend Implementation

fetch("/api/update", {
  method: "POST",
  credentials: "include",
  headers: {
    "X-CSRF-Token": getCookie("csrf_token")
  }
})

---

4.4 Backend Validation (in all APIs)

if request.headers.get("X-CSRF-Token") != request.cookies.get("csrf_token"):
    raise Exception("CSRF validation failed")

---

4.5 Security Model

This implements the Double Submit Cookie Pattern.

• Browser sends cookies automatically

• Only your frontend can read csrf_token

• Attackers cannot forge matching header + cookie

---

5. Content Security Policy

The UI layer (next.js) has to implement this.

Content-Security-Policy: default-src 'self'; script-src 'self'; connect-src 'self' https://*.openg2p.org; img-src 'self' data:; style-src 'self' 'unsafe-inline'; -— Do we need this?? Can our UI work without this? object-src 'none'; frame-ancestors 'none';

6. End-to-End Flow (With Both Tokens)

Step-by-Step

1. User authenticates via IdP

2. IAM API receives:

   • ID Token (identity)

   • Access Token (authorization)

3. IAM API:

   • Stores access_token in HttpOnly cookie

   • Issues csrf_token cookie

   • Processes ID token for user context

4. Frontend:

   • Uses session (no direct access to access_token)

   • Reads csrf_token

   • Implements Content Security Policy (next.js)

5. API Request:

   • Browser sends access_token automatically

   • Frontend adds CSRF header

6. Backend:

   • Validates Access Token

   • Validates CSRF token

   • Processes request

---

6. Security Guarantees

Threat	Protection
XSS	HttpOnly cookies
CSRF	Double submit cookie
Token misuse	Access vs ID token separation
Clickjacking	X-Frame-Options
MIME attacks	nosniff
Browser execution	CSP implemented by the UI

---