IndieWeb Concepts

This document explains the IndieWeb concepts and protocols implemented by django-indieweb.

What is IndieWeb?

The IndieWeb is a people-focused alternative to the “corporate web”. It’s a community of independent website owners who want to own their data and stay connected. Key principles include:

  • Own your data - Your content lives on your domain

  • Syndicate elsewhere - Cross-post to social networks

  • Interoperability - Standards-based protocols for communication

IndieAuth Protocol

IndieAuth is a federated login protocol that uses your own domain name as your identity. It’s built on top of OAuth 2.0 but simplified for the IndieWeb use case.

How IndieAuth Works

        graph TD
    A[User owns domain.com] --> B[User wants to sign in to app.com]
    B --> C[App redirects to user's auth endpoint]
    C --> D[User authenticates on their own site]
    D --> E[Auth endpoint redirects back with code]
    E --> F[App exchanges code for verification]
    F --> G[User is logged in as domain.com]

Key Components

  1. Identity (me) - Your domain name (e.g., https://example.com)

  2. Client ID - The application requesting authentication

  3. Authorization Endpoint - Where users approve access

  4. Token Endpoint - Where codes are exchanged for tokens

  5. Redirect URI - Where to return after authorization

IndieAuth vs OAuth

While similar to OAuth, IndieAuth has key differences:

  • Your identity is your domain, not an account on a service

  • No client registration required

  • Simpler flow focused on authentication and authorization

  • Designed for individual website owners

Micropub Protocol

Micropub is a protocol for creating posts on your website using third-party clients.

Core Concepts

        graph LR
    A[Micropub Client] --> B[Sends POST request]
    B --> C[With access token]
    C --> D[To Micropub endpoint]
    D --> E[Creates content]
    E --> F[Returns 201 Created]

Post Types

Micropub supports various post types through the h parameter:

  • h-entry - Standard blog posts, notes, articles

  • h-event - Events with start/end times

  • h-card - Profile/contact information

Common Properties

  • content - The main post content

  • name - Post title

  • category - Tags/categories

  • in-reply-to - URL being replied to

  • location - Geographic coordinates

  • photo - Image URLs

Implementation Architecture

django-indieweb implements these protocols with three main components:

        classDiagram
    class Auth {
        +key: str
        +owner: User
        +client_id: str
        +redirect_uri: str
        +scope: str
        +me: str
        +created: datetime
    }

    class Token {
        +key: str
        +owner: User
        +client_id: str
        +me: str
        +scope: str
        +created: datetime
    }

    class AuthView {
        +get() : authorization code
        +post() : verify code
    }

    class TokenView {
        +post() : access token
    }

    class MicropubView {
        +get() : configuration
        +post() : create content
    }

    Auth --> AuthView : creates
    AuthView --> TokenView : provides code
    TokenView --> Token : creates
    Token --> MicropubView : authenticates

Data Flow

  1. Authorization Phase

    • User visits AuthView with client details

    • Django authenticates user (standard login)

    • Auth object created with temporary code

    • User redirected back to client with code

  2. Token Exchange

    • Client POSTs code to TokenView

    • Code validated (exists, not expired, matches parameters)

    • Token object created with access key

    • Access token returned to client

  3. Content Creation

    • Client sends POST to MicropubView with token

    • Token validated (exists, active user, scope matches the requested operation)

    • The configured MicropubContentHandler creates the entry (the in-memory handler ships by default; see Micropub Implementation Guide for custom handlers)

    • 201 Created returned with a Location header pointing at the new entry

Security Model

Authorization Codes

  • Single use - deleted after exchange

  • Time limited - 60 seconds by default

  • Bound to specific client_id and redirect_uri

  • Random 32-character strings

Access Tokens

  • Expire after INDIEWEB_TOKEN_EXPIRES_IN seconds (default 86400, i.e. 24 hours); reissuing the token via the IndieAuth flow refreshes the expiration

  • Tokens issued before expiration tracking was added have expires_at=NULL and remain valid until they are reissued or deleted

  • Bound to user, client, and scope

  • Can be revoked by deleting the Token object

  • Should be transmitted over HTTPS only

Scopes

Scopes limit what actions a token can perform. During authorization, django-indieweb normalizes the requested scope string by splitting on whitespace, removing duplicate tokens while preserving first-seen order, and joining the result with single spaces. Unknown scope names are accepted and preserved because IndieAuth/Micropub scopes are extension-defined.

The token endpoint issues the normalized scope stored with the auth code. If a token exchange includes a scope parameter, the submitted value is normalized and must exactly match the stored auth-code scope; clients cannot broaden, narrow, or replace the approved scope at token issuance time. An explicitly empty scope= parameter normalizes to no scope and is accepted only for an auth code issued with no scope.

The Micropub resource server enforces scopes per operation; see API Reference and IndieAuth Implementation for the full mapping.

  • create - Required for POST requests that create new posts (legacy alias post is also accepted)

  • update - Required for POST action=update and GET ?q=source.

  • delete - Required for POST action=delete

  • undelete - Required for POST action=undelete

Best Practices

For Service Providers

  1. Always use HTTPS in production

  2. Validate all parameters strictly

  3. Implement rate limiting

  4. Log authorization attempts

  5. Consider token expiration

For Users

  1. Only authorize apps you trust

  2. Use unique passwords for your domain

  3. Review authorized apps regularly

  4. Revoke unused tokens

Limitations

Current implementation limitations:

  1. No token revocation UI - Must delete via Django admin

  2. No media endpoint - Can’t upload images

Future Enhancements

Potential improvements for full IndieWeb support:

  1. Media Endpoint - Handle file uploads

  2. Token Management - UI for viewing/revoking tokens

  3. WebSub - Real-time updates

Resources