
Collecting and storing only necessary personal info in tools with logins
This page has been translated by machine translation. View original
Introduction
Recently, I built 4 tools with login functionality. In these 4 tools, I minimized the personal information of users that I store. To minimize the data an attacker can obtain when a breach occurs, I retrieve data only when it is needed and only as much as is needed. I'll introduce 4 techniques for doing so, along with samples using Cloudflare Workers and GitHub OAuth.
What is damage control?
Damage control is an approach that assumes damage will occur and minimizes its scope. The term originally refers to measures to keep flooding of a damaged ship confined to some compartments in order to prevent it from sinking. In a security context, it is often used to mean a design philosophy for minimizing the damage after a breach.
Target audience
- People building personal or internal tools with login functionality
- People who delegate authentication to external services or libraries and cannot fully grasp what data is stored
References
- Scopes for OAuth apps (GitHub Docs)
- REST API endpoints for OAuth authorizations (GitHub Docs)
- Cron Triggers (Cloudflare Docs)
Background
Breaches such as user account takeovers and attacks exploiting website vulnerabilities cannot be completely prevented, no matter how many layers of countermeasures you add. When a breach succeeds, what the attacker can obtain is the data the tool stores. Attackers cannot obtain data that is not stored. Therefore, minimizing the data you store is a means of damage control.
The principle of least privilege is a security design principle of granting only the minimum privileges necessary for processing. I apply this principle not only to the permissions requested from users but also to the data the tool stores. Specifically, it takes the form of retrieving data only when it is needed and only as much as is needed.
I put this policy into practice through several techniques. At the data acquisition stage, it is "don't acquire" or "acquire but don't store", and at the data storage stage, it is "store it hashed or encrypted" and "set an expiration and delete it". In the following sections, I'll explain each technique in detail.
Practice
From here, I'll explain with concrete code using a sample. The sample runs on Cloudflare Workers and D1, and assumes a tool where users log in with GitHub. As for the tool's purpose, please imagine "a tool that verifies, through a GitHub account, whether a participant is who they claim to be when they sign up for a study group".
Only the following 2 tables are created in the database.
CREATE TABLE sessions (
token_hash TEXT PRIMARY KEY,
github_id INTEGER NOT NULL,
expires_at INTEGER NOT NULL
);
CREATE TABLE credentials (
github_id INTEGER NOT NULL,
purpose TEXT NOT NULL,
ciphertext TEXT NOT NULL,
PRIMARY KEY (github_id, purpose)
);
The sessions table stores sessions that identify logged-in users.
Each section shows only the key parts of the sample. The whole sample is as follows.
src/index.ts
export interface Env {
DB: D1Database;
GITHUB_CLIENT_ID: string;
GITHUB_CLIENT_SECRET: string;
TOKEN_KEY: string;
}
// ---- 共通 ----
declare function verifyState(request: Request): Promise<boolean>;
declare function exchangeCode(env: Env, code: string): Promise<string>;
const encoder = new TextEncoder();
const toBase64 = (bytes: Uint8Array) => btoa(String.fromCharCode(...bytes));
const fromBase64 = (value: string) => Uint8Array.from(atob(value), (c) => c.charCodeAt(0));
const now = () => Math.floor(Date.now() / 1000);
// ---- 1. 取得しない ----
export function redirectToGitHub(env: Env, state: string): Response {
const url = new URL("https://github.com/login/oauth/authorize");
url.searchParams.set("client_id", env.GITHUB_CLIENT_ID);
url.searchParams.set("state", state);
// 公開情報の読み取りだけを許可するアクセストークンを要求する
url.searchParams.set("scope", "");
return Response.redirect(url.toString(), 302);
}
async function fetchGitHubId(accessToken: string): Promise<number> {
const res = await fetch("https://api.github.com/user", {
headers: {
Authorization: `Bearer ${accessToken}`,
Accept: "application/vnd.github+json",
"User-Agent": "sample-app",
},
});
if (!res.ok) throw new Error("GitHub user request failed");
// 応答には名前やアイコンも含まれるが、id 以外は参照しない
const { id } = (await res.json()) as { id: number };
return id;
}
// ---- 2. 取得しても保管しない ----
export async function handleGitHubCallback(request: Request, env: Env): Promise<Response> {
const code = new URL(request.url).searchParams.get("code");
if (!code || !(await verifyState(request))) return new Response("Bad Request", { status: 400 });
const accessToken = await exchangeCode(env, code);
try {
const githubId = await fetchGitHubId(accessToken);
return await startSession(env.DB, githubId);
} finally {
// GitHub の利用者 ID を取得したら、アクセストークンは保管せずに失効させる
await revokeToken(env, accessToken);
}
}
async function revokeToken(env: Env, accessToken: string): Promise<void> {
await fetch(`https://api.github.com/applications/${env.GITHUB_CLIENT_ID}/token`, {
method: "DELETE",
headers: {
Authorization: `Basic ${btoa(`${env.GITHUB_CLIENT_ID}:${env.GITHUB_CLIENT_SECRET}`)}`,
Accept: "application/vnd.github+json",
"User-Agent": "sample-app",
},
body: JSON.stringify({ access_token: accessToken }),
});
}
// ---- 3. ハッシュ化・暗号化して保管する ----
const SESSION_TTL = 7 * 24 * 60 * 60;
async function sha256(value: string): Promise<string> {
return toBase64(new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(value))));
}
async function startSession(db: D1Database, githubId: number): Promise<Response> {
const token = toBase64(crypto.getRandomValues(new Uint8Array(32)));
await db
.prepare("INSERT INTO sessions (token_hash, github_id, expires_at) VALUES (?, ?, ?)")
.bind(await sha256(token), githubId, now() + SESSION_TTL)
.run();
return new Response(null, {
status: 302,
headers: {
Location: "/",
"Set-Cookie": `session=${token}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=${SESSION_TTL}`,
},
});
}
export async function findSession(db: D1Database, token: string): Promise<number | null> {
const row = await db
.prepare("SELECT github_id FROM sessions WHERE token_hash = ? AND expires_at > ?")
.bind(await sha256(token), now())
.first<{ github_id: number }>();
return row?.github_id ?? null;
}
async function importKey(env: Env): Promise<CryptoKey> {
return crypto.subtle.importKey("raw", fromBase64(env.TOKEN_KEY), "AES-GCM", false, ["encrypt", "decrypt"]);
}
export async function encryptToken(env: Env, token: string, githubId: number, purpose: string): Promise<string> {
const iv = crypto.getRandomValues(new Uint8Array(12));
const ciphertext = await crypto.subtle.encrypt(
// GitHub の利用者 ID と用途を復号の条件にする。別の行へ複製すると復号できない
{ name: "AES-GCM", iv, additionalData: encoder.encode(`${githubId}:${purpose}`) },
await importKey(env),
encoder.encode(token),
);
return `${toBase64(iv)}.${toBase64(new Uint8Array(ciphertext))}`;
}
export async function decryptToken(env: Env, stored: string, githubId: number, purpose: string): Promise<string> {
const [iv, ciphertext] = stored.split(".");
const plaintext = await crypto.subtle.decrypt(
{ name: "AES-GCM", iv: fromBase64(iv), additionalData: encoder.encode(`${githubId}:${purpose}`) },
await importKey(env),
fromBase64(ciphertext),
);
return new TextDecoder().decode(plaintext);
}
// ---- 4. 有効期限を設けて削除する ----
export default {
async scheduled(_controller, env) {
const time = now();
await env.DB.batch([
env.DB.prepare("DELETE FROM sessions WHERE expires_at <= ?").bind(time),
// 有効なセッションが残っていない利用者のアクセストークンも削除する
env.DB.prepare(
"DELETE FROM credentials WHERE github_id NOT IN (SELECT github_id FROM sessions WHERE expires_at > ?)",
).bind(time),
]);
},
} satisfies ExportedHandler<Env>;
Don't acquire
When requesting authorization with GitHub OAuth, leave the scope empty. An access token without scopes is permitted only to read public information.
export function redirectToGitHub(env: Env, state: string): Response {
const url = new URL("https://github.com/login/oauth/authorize");
url.searchParams.set("client_id", env.GITHUB_CLIENT_ID);
url.searchParams.set("state", state);
// Request an access token that is permitted only to read public information
url.searchParams.set("scope", "");
return Response.redirect(url.toString(), 302);
}
async function fetchGitHubId(accessToken: string): Promise<number> {
const res = await fetch("https://api.github.com/user", {
headers: {
Authorization: `Bearer ${accessToken}`,
Accept: "application/vnd.github+json",
"User-Agent": "sample-app",
},
});
if (!res.ok) throw new Error("GitHub user request failed");
// The response also includes the name and icon, but nothing other than id is referenced
const { id } = (await res.json()) as { id: number };
return id;
}
The only data needed to identify a logged-in user is the GitHub user ID. Therefore, even if the /user response contains the name and public email address, nothing other than id is referenced.
With this setting, even if an access token is stolen, an attacker cannot read or write private repositories. Also, even if the database is leaked, users' names and email addresses are not leaked. However, the downside is that there is no way to contact users.
Acquire but don't store
The access token obtained for login is revoked as soon as the GitHub user ID has been retrieved, and is not stored. Only the GitHub user ID is tied to the session.
export async function handleGitHubCallback(request: Request, env: Env): Promise<Response> {
const code = new URL(request.url).searchParams.get("code");
if (!code || !(await verifyState(request))) return new Response("Bad Request", { status: 400 });
const accessToken = await exchangeCode(env, code);
try {
const githubId = await fetchGitHubId(accessToken);
return await startSession(env.DB, githubId);
} finally {
// Once the GitHub user ID has been retrieved, revoke the access token without storing it
await revokeToken(env, accessToken);
}
}
async function revokeToken(env: Env, accessToken: string): Promise<void> {
await fetch(`https://api.github.com/applications/${env.GITHUB_CLIENT_ID}/token`, {
method: "DELETE",
headers: {
Authorization: `Basic ${btoa(`${env.GITHUB_CLIENT_ID}:${env.GITHUB_CLIENT_SECRET}`)}`,
Accept: "application/vnd.github+json",
"User-Agent": "sample-app",
},
body: JSON.stringify({ access_token: accessToken }),
});
}
※ verifyState is the process that verifies the state, and exchangeCode is the process that exchanges the authorization code for an access token. Both are omitted.
To revoke the access token, I use GitHub's DELETE /applications/{client_id}/token. This API is called with Basic authentication using the OAuth app's client ID and client secret.
With this process, the GitHub access token is stored neither in the database nor in a cookie. However, the downside is that the tool can no longer call the GitHub API with the user's permissions after login.
Store it hashed or encrypted
Data that must be stored is stored in a form that cannot be used as is. Values used only for verification are hashed, and values whose original form must be used are encrypted.
The session token is used only for comparison against the value sent by the user, and the original value is not needed. Therefore, only the SHA-256 hash is stored in the database.
const SESSION_TTL = 7 * 24 * 60 * 60;
async function startSession(db: D1Database, githubId: number): Promise<Response> {
const token = toBase64(crypto.getRandomValues(new Uint8Array(32)));
await db
.prepare("INSERT INTO sessions (token_hash, github_id, expires_at) VALUES (?, ?, ?)")
.bind(await sha256(token), githubId, now() + SESSION_TTL)
.run();
return new Response(null, {
status: 302,
headers: {
Location: "/",
"Set-Cookie": `session=${token}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=${SESSION_TTL}`,
},
});
}
export async function findSession(db: D1Database, token: string): Promise<number | null> {
const row = await db
.prepare("SELECT github_id FROM sessions WHERE token_hash = ? AND expires_at > ?")
.bind(await sha256(token), now())
.first<{ github_id: number }>();
return row?.github_id ?? null;
}
The session token is a 32-byte random number. Therefore, even if the database is leaked, an attacker cannot recover the session token from the hash.
On the other hand, a tool that calls the GitHub API after login needs the original value of the access token. In that case, the access token is encrypted with AES-GCM and stored. The encryption key is stored not in the database but in the Workers Secrets.
export async function encryptToken(env: Env, token: string, githubId: number, purpose: string): Promise<string> {
const iv = crypto.getRandomValues(new Uint8Array(12));
const ciphertext = await crypto.subtle.encrypt(
// Make the GitHub user ID and the purpose conditions for decryption. Copying it to another row makes decryption impossible
{ name: "AES-GCM", iv, additionalData: encoder.encode(`${githubId}:${purpose}`) },
await importKey(env),
encoder.encode(token),
);
return `${toBase64(iv)}.${toBase64(new Uint8Array(ciphertext))}`;
}
AES-GCM decryption fails unless additionalData matches between encryption and decryption. So I specify the GitHub user ID and the purpose as additionalData. With this, even if an attacker copies a ciphertext to another user's row, the tool cannot decrypt that ciphertext.
With these processes, if only the database is leaked, the attacker can use neither the session tokens nor the access tokens. However, the downside is the effort of storing and rotating the encryption key.
Set an expiration and delete it
Sessions have a 7-day expiration, which is not extended even while in use. startSession in the previous section saves the expiration, and findSession treats only sessions within their expiration as valid.
Expired sessions are deleted daily with Cron Triggers. At the same time, the access tokens of users who have no valid sessions remaining are also deleted.
export default {
async scheduled(_controller, env) {
const time = now();
await env.DB.batch([
env.DB.prepare("DELETE FROM sessions WHERE expires_at <= ?").bind(time),
// Also delete the access tokens of users who have no valid sessions remaining
env.DB.prepare(
"DELETE FROM credentials WHERE github_id NOT IN (SELECT github_id FROM sessions WHERE expires_at > ?)",
).bind(time),
]);
},
} satisfies ExportedHandler<Env>;
{
"triggers": {
"crons": ["0 3 * * *"]
}
}
With this process, the period during which a stolen session token can be used is at most 7 days. Also, the access tokens of users who no longer log in are deleted from the database. However, the downside is that users have to log in again every 7 days.
Comparison of the 4 techniques
The following table shows, for the 4 techniques above, the data that attackers can no longer obtain and the downsides.
| Technique | What attackers can no longer obtain when a breach occurs | Downside |
|---|---|---|
| Don't acquire | Access permissions to private repositories, users' names and email addresses | No way to contact users |
| Acquire but don't store | GitHub access tokens | Cannot call the GitHub API after login |
| Store it hashed or encrypted | Usable session tokens and access tokens when only the database is leaked | Effort of storing and rotating the encryption key |
| Set an expiration and delete it | Expired sessions, access tokens of users who no longer log in | Re-login every 7 days |
Discussion
While writing this article, I made a list of the data stored in the databases, cookies, and logs of the 4 tools. As a result, I found a tool that was storing email addresses and display names following the authentication library's default table definition. I had not noticed that storage until I made the list.
In these tools I delegate much of the implementation to AI, and when having the AI review the plan I ask, "Is this minimal from a security perspective?" Even so, I didn't notice, which makes me think that the more you delegate implementation to libraries and AI, the more the data you store grows in unintended places.
I believe that to minimize the data you store, in addition to knowing the techniques, you need to understand for yourself what data you are storing. Storing data means taking responsibility for it when it is leaked. I think it's good to take this awareness as the starting point for data minimization.
Summary
If you are building a tool with login functionality, it is a good idea to first make a list of the data stored in your tool's database, cookies, and logs. Then, for each item on the list, consider introducing the techniques of "don't acquire", "acquire but don't store", "store it hashed or encrypted", and "set an expiration and delete it".
I hope this article is helpful to those who build tools with login functionality.