Manual Testing

Manual Testing

The spec/dummy directory contains a Rails application for testing the engine. The dummy app includes a /callback endpoint that displays authorization codes returned from the OAuth flow, and helper scripts that guide you through the complete OAuth flow.

Setup

1. Start the dummy app server:

cd spec/dummy
bin/rails db:migrate
bin/rails server

2. Create a test user in the Rails console:

bin/rails console

User.create!(email: "test@example.com", password: "password")

Testing the OAuth Flow

For pre-registered clients, first create a client in the console:

TokenAuthority::Client.create!(
  name: "Test Client",
  client_type: "confidential",
  redirect_uris: ["http://localhost:3000/callback"]
)

Then run one of the helper scripts:

bin/rails runner script/generate_link_for_authorize_endpoint.rb

The script will display an authorization URL. Open it in your browser, sign in with the test user, and approve the authorization. After being redirected to the callback page, copy the authorization code and enter it into the script prompt. The script will output a curl command to exchange the code for tokens.

OAuth Flow Scripts

Script	Description
public_client.rb	Public client with PKCE
confidential_client.rb	Confidential client (minimal params, no PKCE)
confidential_client_pkce.rb	Confidential client with PKCE
confidential_client_full.rb	Confidential client with PKCE and redirect_uri
dynamic_client_registration.rb	Dynamic client registration + OAuth flow
client_metadata_document.rb	URL-based client (Client Metadata Document)
serve_client_metadata.rb	WEBrick server for hosting client metadata (use with ngrok)

Dynamic Client Registration (RFC 7591)

The dummy app has dynamic client registration enabled by default. You can test the full flow (public client registration + PKCE authorization):

bin/rails runner script/dynamic_client_registration.rb

This script:

1. Registers a public client via /oauth/register
2. Generates PKCE parameters
3. Displays the authorization URL
4. Prompts for the authorization code
5. Exchanges the code for tokens

Additional DCR Scripts

Script	Description
dynamic_client_registration.rb	Public client with PKCE (DCR + OAuth flow)
register_confidential_client.rb	Register confidential client (client_secret_basic)
register_public_client.rb	Register public client (token_endpoint_auth_method: none)
register_client_secret_post.rb	Register client with client_secret_post auth
register_client_with_private_key_jwt.rb	Register client with private_key_jwt auth
register_client_with_initial_access_token.rb	Test protected registration
register_client_with_software_statement.rb	Register with software statement JWT

Testing with curl

Register a client manually:

curl -X POST http://localhost:3000/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_uris": ["http://localhost:3000/callback"],
    "client_name": "My App",
    "token_endpoint_auth_method": "none"
  }'

Testing with Scopes

The dummy app has scopes configured by default (read, write, delete, profile). To test the OAuth flow with scopes:

1. Add the scope parameter to the authorization URL:

   GET /oauth/authorize?client_id=...&scope=read%20write&...
   

2. The consent screen will display the requested scopes with their descriptions

3. When exchanging the code for tokens, the response includes a scope field:

   {
     "access_token": "...",
     "refresh_token": "...",
     "token_type": "bearer",
     "expires_in": 300,
     "scope": "read write"
   }

4. The access token JWT includes a scope claim with the space-delimited scope tokens

URL-Based Client Identifiers (Client Metadata Documents)

URL-based client identifiers allow clients to use an HTTPS URL as their client_id. The authorization server fetches client metadata from the URL at runtime, enabling lightweight client registration without pre-registration.

Quick Start with the Metadata Server

The dummy app includes scripts for testing URL-based client identifiers:

Terminal 1 - Start the metadata server:

cd spec/dummy
ruby script/serve_client_metadata.rb

Terminal 2 - Expose it via ngrok:

ngrok http 4567

Copy the ngrok HTTPS URL (e.g., https://abc123.ngrok-free.app) and paste it into Terminal 1 when prompted.

Terminal 3 - Start the Rails server:

cd spec/dummy
bin/rails server

Terminal 4 - Run the OAuth flow:

cd spec/dummy
bin/rails runner script/client_metadata_document.rb

1. Enter the client_id URL shown in Terminal 1 (e.g., https://abc123.ngrok-free.app/oauth-client)
2. Press Enter to accept the default redirect_uri
3. The script automatically opens the authorization URL in your browser
4. Sign in and approve the authorization
5. Copy the authorization code from the callback page
6. Paste it back into Terminal 4

The script exchanges the code for tokens and displays the result.

Key Differences from Registered Clients

URL-based clients:

• Are always treated as public clients (no client secret)
• Must always use PKCE (code_challenge/code_verifier)
• Must always provide redirect_uri in both authorization and token requests
• Require the metadata document to be accessible via HTTPS

Client Metadata Document Format

The metadata document served at your client_id URL must be valid JSON with at least these fields:

{
  "client_id": "https://your-server.example.com/oauth-client",
  "client_name": "My Application",
  "redirect_uris": ["https://your-server.example.com/callback"]
}

The client_id field must match the URL where the document is hosted.

Testing Scripts

Script	Description
serve_client_metadata.rb	WEBrick server that hosts a metadata document (use with ngrok)
client_metadata_document.rb	Full OAuth flow with URL-based client (PKCE + token exchange)

Manual Testing with curl

After completing the authorization flow and receiving an authorization code, exchange it for tokens:

curl -X POST http://localhost:3000/oauth/token \
  -d "grant_type=authorization_code" \
  -d "code=YOUR_AUTH_CODE" \
  -d "client_id=https://YOUR-NGROK-URL/oauth-client" \
  -d "redirect_uri=http://localhost:3000/callback" \
  -d "code_verifier=YOUR_CODE_VERIFIER"

See Also

• Installation Guide - Setting up TokenAuthority
• Configuration Reference - Configuration options