# IndieAuth Identity Page Architecture
## Overview
An IndieAuth identity page serves as the authoritative source for a user's online identity in the IndieWeb ecosystem. This document defines the minimal requirements and best practices for creating a static HTML page that functions as an IndieAuth identity URL.
## Purpose
The identity page serves three critical functions:
1. **Authentication Endpoint Discovery** - Provides rel links to IndieAuth endpoints
2. **Identity Verification** - Contains h-card microformats with user information
3. **Social Proof** - Optional rel="me" links for identity consolidation
## Technical Requirements
### 1. HTML Structure
```
DOCTYPE html5
├── head
│ ├── meta charset="utf-8"
│ ├── meta viewport (responsive)
│ ├── title (user's name)
│ ├── rel="authorization_endpoint"
│ ├── rel="token_endpoint"
│ └── optional: rel="micropub"
└── body
└── h-card
├── p-name (full name)
├── u-url (identity URL)
├── u-photo (optional avatar)
└── rel="me" links (optional)
```
### 2. IndieAuth Discovery
The page MUST include these link elements in the ``:
```html
```
These endpoints:
- **authorization_endpoint**: Handles the OAuth 2.0 authorization flow
- **token_endpoint**: Issues access tokens for API access
### 3. Microformats2 h-card
The h-card provides machine-readable identity information:
```html
```
Required properties:
- `p-name`: The person's full name
- `u-url`: The canonical identity URL (must match the page URL)
Optional properties:
- `u-photo`: Avatar image URL
- `p-note`: Brief biography
- `u-email`: Contact email (consider privacy implications)
### 4. rel="me" Links
For identity consolidation and social proof:
```html
GitHub
```
Best practices:
- Only include links to profiles you control
- Ensure reciprocal rel="me" links where possible
- Use HTTPS URLs whenever available
## Security Considerations
### 1. HTTPS Requirement
- Identity URLs MUST use HTTPS
- All linked endpoints MUST use HTTPS
- Mixed content will break authentication flows
### 2. Content Security
- No inline JavaScript required or recommended
- Minimal inline CSS only if necessary
- No external dependencies for core functionality
### 3. Privacy
- Consider what information to make public
- Email addresses can attract spam
- Phone numbers should generally be avoided
## Testing Strategy
### 1. IndieAuth Validation
- Test with https://indielogin.com/
- Verify endpoint discovery works
- Complete a full authentication flow
### 2. Microformats Validation
- Use https://indiewebify.me/
- Verify h-card is properly parsed
- Check all properties are detected
### 3. HTML Validation
- Validate with W3C validator
- Ensure semantic HTML5 compliance
- Check accessibility basics
## Common Pitfalls
### 1. Missing or Wrong URLs
- Identity URL must be absolute and match the actual page URL
- Endpoints must be absolute URLs
- rel="me" links must be to HTTPS when available
### 2. Incorrect Microformats
- Missing required h-card properties
- Using old hCard format instead of h-card
- Nesting errors in microformat classes
### 3. Authentication Failures
- Using HTTP instead of HTTPS
- Incorrect or missing endpoint declarations
- Not including trailing slashes consistently
## Minimal Implementation Checklist
- [ ] HTML5 DOCTYPE declaration
- [ ] UTF-8 character encoding
- [ ] Viewport meta tag for mobile
- [ ] Authorization endpoint link
- [ ] Token endpoint link
- [ ] h-card with p-name
- [ ] h-card with u-url matching page URL
- [ ] All URLs use HTTPS
- [ ] No broken links or empty hrefs
- [ ] Valid HTML5 structure
## Reference Implementations
See `/docs/examples/identity-page.html` for a complete, working example that can be customized for any IndieAuth user.
## Standards References
- [IndieAuth Specification](https://indieauth.spec.indieweb.org/)
- [Microformats2 h-card](http://microformats.org/wiki/h-card)
- [rel="me" specification](https://microformats.org/wiki/rel-me)
- [IndieWeb Authentication](https://indieweb.org/authentication)