Choosing Session Storage in Ory Kratos: Cookie vs Token for Web Apps

Problem & Decision Context

When integrating Ory Kratos into a web application, you must decide how the session is transmitted between the client and Kratos. The two supported patterns are:

• Cookie‑based sessions – Kratos sets an HTTP‑only cookie that the browser automatically sends with each request.
• Token‑based sessions – The client receives a session token (e.g., JWT or opaque string) and attaches it to API requests via the Authorization header.

This decision impacts security posture, cross‑domain behavior, and client implementation complexity. The following guide helps you pick the right strategy for your use case.

Decision Table

Feature	Cookie	Token
Browser auto‑handling	✓ – no extra code	✗ – client must store & send header
Same‑Site enforcement	✓ – configure SameSite attribute	✗ – header cannot carry SameSite
CSRF protection	✓ – requires SameSite or CSRF token	✗ – token not sent automatically, so CSRF less of a risk
XSS risk	✓ – HttpOnly flag prevents JS access	✗ – token stored in localStorage/IndexedDB is XSS‑vulnerable
Cross‑domain API	✗ – cookie limited to domain unless CORS + credentials	✓ – header works across origins
Non‑browser clients	✗ – browsers only	✓ – works for mobile, desktop, CLI
Sliding expiration	✓ – Kratos renews cookie automatically	✓ – client must refresh token via API
Implementation effort	✗ – minimal code	✓ – extra storage & header logic

Trade‑Off Analysis

• Security – Cookies with HttpOnly and Secure reduce XSS risk, but you must guard against CSRF with SameSite=Lax/Strict or a separate CSRF token. Tokens avoid automatic CSRF but expose the token to XSS if stored insecurely.
• Cross‑Domain & API – If your front‑end and API run on different origins, token headers simplify CORS handling. Cookie sessions require Access-Control-Allow-Credentials: true and the browser must allow cross‑origin credentials.
• Client complexity – Cookie sessions are almost zero‑code for browsers, whereas token sessions need a secure storage mechanism and header injection logic.
• Compliance & Auditing – Tokens can be introspected or signed, providing audit trails. Cookies are opaque; you must query Kratos for session details.

Concrete Implementation – Cookie Session

Below is a minimal kratos.yaml snippet that enables cookie‑based sessions with secure defaults. Adjust public_url and admin_url to match your deployment.

dsn: memory
public_url: https://auth.example.com
admin_url: https://auth.example.com
session:
  cookie:
    name: ory_kratos_session
    http_only: true
    secure: true
    same_site: lax
    max_age: 3600  # 1 hour
    renew: true
    renew_window: 1800  # 30 minutes before expiry

Deploy Kratos with the above config and restart the service. The ory_kratos_session cookie will be set after a successful login.

Validation Steps

1. Login and inspect cookie

   # Use a browser to navigate to https://auth.example.com/login
   # After successful login, open Developer Tools → Application → Cookies
   # Verify that ory_kratos_session exists and has attributes:
   #   HttpOnly: true
   #   Secure: true
   #   SameSite: Lax
   

2. Protected API request without cookie

   curl -i https://api.example.com/user
   # Expected response: 401 Unauthorized
   

3. Protected API request with cookie

   curl -i \
     -H "Cookie: ory_kratos_session=YOUR_SESSION_ID" \
     https://api.example.com/user
   # Expected response: 200 OK with user data
   

4. Session expiration test

   # Edit kratos.yaml: session.cookie.max_age: 10
   # Restart Kratos
   # Wait 15 seconds, then repeat the protected API request
   # Expected: 401 Unauthorized, redirect to login flow
   

Rollback

To revert to a previous configuration, replace the edited kratos.yaml with the backup copy and restart Kratos. No state changes are made beyond the session cookie itself, which will expire automatically.

When to Choose Token Sessions

If your architecture includes:

• Multiple origins (e.g., SPA on app.example.com and API on api.example.com)
• Mobile or desktop clients that cannot rely on browser cookies
• Need for fine‑grained token introspection or revocation

then configuring Kratos to issue a token and having clients store it in a secure vault (e.g., SecureStore on iOS) is preferable. The same kratos.yaml can be adapted by enabling the token strategy under session and implementing a client‑side interceptor to attach the token to every request.

Conclusion

Cookie‑based sessions are ideal for pure browser workflows where CSRF safeguards are in place. Token sessions shine in cross‑domain or non‑browser environments but demand careful XSS protection. Use the table and trade‑off analysis above to match your application’s security model and architecture.