Files

Phil Skentelbery 68669b9a6a docs: add reference IndieAuth identity page implementation

Add minimal, production-ready static HTML identity page as reference
implementation for IndieAuth authentication.

Includes:
- Complete identity-page.html with h-card and IndieAuth endpoints
- Architectural documentation and rationale
- ADR-010: Static Identity Page decision record
- Customization guide for users

The example is zero-dependency, copy-paste ready, and guaranteed to
work with IndieLogin.com and StarPunk. Pre-configured for
thesatelliteoflove.com as working example.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-11-19 13:03:49 -07:00

4.4 KiB

Raw Blame History

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:

Authentication Endpoint Discovery - Provides rel links to IndieAuth endpoints
Identity Verification - Contains h-card microformats with user information
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 <head>:

<link rel="authorization_endpoint" href="https://indieauth.com/auth">
<link rel="token_endpoint" href="https://tokens.indieauth.com/token">

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:

<div class="h-card">
  <h1 class="p-name">User Name</h1>
  <a class="u-url" href="https://example.com" rel="me">https://example.com</a>
</div>

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:

<a href="https://github.com/username" rel="me">GitHub</a>

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.

4.4 KiB Raw Blame History