Login Token Schema

TL;DR

This guide explains how to design a secure login token schema for your application. We’ll cover the essential components, best practices, and example structures.

1. Understanding Login Tokens

Login tokens (also known as access tokens or JWTs) are credentials used to verify a user’s identity after they have successfully logged in. They allow users to access protected resources without repeatedly entering their username and password. A well-designed schema is crucial for security.

2. Essential Token Components

1. Header: Contains metadata about the token, including the signing algorithm (e.g., HS256, RS256).
2. Payload: Holds claims – statements about the user and the token itself. This is where you store information like user ID, roles, expiry time, etc.
3. Signature: Ensures the token hasn’t been tampered with. It’s created using a secret key (or private key) and the header and payload.

3. Payload Claims – What to Include

Carefully consider what information you put in the payload. More data isn’t always better; it increases token size and potential security risks.

• sub (Subject): Unique identifier for the user (e.g., User ID). Required
• iss (Issuer): The entity that issued the token (your application’s name/URL). Recommended
• aud (Audience): Who the token is intended for (usually your application itself). Recommended
• exp (Expiration Time): When the token expires. Crucial for security! Short expiry times are better, with refresh tokens used to obtain new ones. Required
• iat (Issued At): When the token was issued. Useful for detecting replay attacks. Recommended
• roles: User’s roles or permissions. Use cautiously; consider more granular access control mechanisms if possible.

Example Payload (JSON):

{
  "sub": "1234567890",
  "iss": "https://example.com",
  "aud": "my-application",
  "exp": 1678886400,
  "iat": 1678882800,
  "roles": ["user", "admin"]
}

4. Choosing a Signing Algorithm

Select an algorithm appropriate for your security needs.

• HS256 (HMAC with SHA-256): Symmetric key algorithm. Simpler to implement but requires keeping the secret key secure on both the server and client side (not ideal).
• RS256 (RSA with SHA-256): Asymmetric key algorithm. More secure; uses a private key for signing and a public key for verification. The private key is kept securely on the server, while the public key can be distributed. Recommended

5. Token Storage (Client Side)

How you store tokens on the client side impacts security.

• HTTP-only Cookies: Most secure option for web applications. Prevents JavaScript access, mitigating XSS attacks.
• LocalStorage/SessionStorage: Less secure; vulnerable to XSS attacks. Avoid if possible. If used, implement strict input validation and output encoding.

6. Refresh Tokens

Use refresh tokens to obtain new access tokens without requiring the user to re-enter their credentials.

• Longer Expiry Time: Refresh tokens should have a longer expiry time than access tokens.
• Separate Storage: Store refresh tokens securely (e.g., in an HTTP-only cookie).
• Rotation: Rotate refresh tokens regularly to limit the impact of compromise.

7. Example Token Structure (JWT)

A JWT consists of three parts separated by dots:

Header.Payload.Signature

Example:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkJWT" . eyJzdWIiOiIxMjM0NTY3ODkwIiwiaXNzIjoihttps://example.com", "aud":"my-application","exp":1678886400,"iat":1678882800} . Sdfjklasdjfklasdjfklasdjfklasdjf

8. Security Considerations

• Keep Secrets Secure: Protect your signing keys (symmetric or private).
• Validate Tokens: Always validate tokens on the server side before granting access to protected resources.
• Use HTTPS: Ensure all communication is encrypted using HTTPS.
• Regularly Audit: Review your token schema and implementation for vulnerabilities.