Installation Guide

Installation Guide

This guide covers advanced installation options for TokenAuthority.

Basic Installation

Add TokenAuthority to your Gemfile:

gem "token_authority"

Run bundle install:

$ bundle

Run the install generator:

$ bin/rails generate token_authority:install

Run the migration:

$ bin/rails db:migrate

Generator Options

The generator accepts the following options:

Option	Default	Description
--user_table_name	users	Name of your application's user table
--user_foreign_key_type	bigint	Primary key type of your user table (bigint, uuid, integer)

Custom Table Names

If your user table is named something other than users:

$ bin/rails generate token_authority:install --user_table_name=accounts

Custom Foreign Key Types

If your user table uses UUID primary keys:

$ bin/rails generate token_authority:install --user_foreign_key_type=uuid

Combined Options

You can combine options:

$ bin/rails generate token_authority:install --user_table_name=accounts --user_foreign_key_type=uuid

What the Generator Creates

The generator creates three things:

1. Database Migration

A migration file that creates the required database tables (see Database Tables below).

2. Initializer

An initializer at config/initializers/token_authority.rb with default configuration. See the Configuration Reference for all available options.

3. Views

Customizable views at app/views/token_authority/. See Customizing Views for details.

Database Tables

The migration creates the following tables:

Table	Purpose
token_authority_clients	OAuth client applications (stores client credentials and settings)
token_authority_authorization_grants	Authorization codes issued during the OAuth flow
token_authority_challenges	PKCE code challenges for enhanced security
token_authority_sessions	Tracks issued tokens and their status (created, expired, refreshed, revoked)
token_authority_jwks_caches	Cached JWKS documents for private_key_jwt authentication
token_authority_client_metadata_document_caches	Cached client metadata documents for URL-based client identifiers

All tables use the token_authority_ prefix to avoid conflicts with your application's tables.

Subdomain Development Setup

If you're using subdomain constraints for multiple protected resources, you'll need additional configuration for local development.

Why This Is Needed

Rails subdomain constraints (e.g., constraints subdomain: "mcp") require a domain that properly resolves subdomains. localhost doesn't support subdomains out of the box.

Using lvh.me

The lvh.me domain resolves to 127.0.0.1 and supports subdomains, making it ideal for development:

• http://lvh.me:3000 → your main app
• http://mcp.lvh.me:3000 → MCP subdomain
• http://api.lvh.me:3000 → API subdomain

Configuration

Add lvh.me to your allowed hosts in config/environments/development.rb:

config.hosts << /.*\.lvh\.me/

Update your environment variables to use lvh.me:

TOKEN_AUTHORITY_BASE_URL=http://lvh.me:3000
TOKEN_AUTHORITY_MCP_URL=http://mcp.lvh.me:3000/

Note: Some OAuth clients may append a trailing slash to resource URLs. Include the trailing slash in your TOKEN_AUTHORITY_MCP_URL to ensure exact matches during authorization validation.

Example Routes

Rails.application.routes.draw do
  token_authority_auth_server_routes

  constraints subdomain: "mcp" do
    token_authority_protected_resource_route
    post "/", to: "model_context_protocol#index"
  end
end

With this configuration:

• Authorization server metadata: http://lvh.me:3000/.well-known/oauth-authorization-server
• Protected resource metadata: http://mcp.lvh.me:3000/.well-known/oauth-protected-resource
• MCP endpoint: http://mcp.lvh.me:3000/

Next Steps

After installation:

1. Configure TokenAuthority for your environment
2. Set up user authentication integration
3. Mount the engine routes in your application