OAuth のメタデータの URL と .htaccess


この機能は Ver. 3.3.0 で追加予定の、リリース前の機能です

このページは、アルファ版(Ver. 3.3.0-alpha.1)時点の内容です。正式版までに仕様や設定項目が変わる可能性があります。本番サイトでは使わず、検証環境でお試しください。

クライアントは 401 の応答とメタデータから認可サーバーを自動で見つけるため、ふつうはメタデータの URL を意識しなくてかまいません。つながらないときの確認と、既存のサイトの .htaccess の見直しに使ってください。OAuth 認可サーバーが無効のとき、メタデータはすべて 404 です。

メタデータの URL

置き場所は、ブログの URL がドメインの直下か、パスを持つかで変わります。

ドメインの直下のブログ(https://example.com/。サブドメインの子ブログも同じ)

パスのあるブログ(https://example.com/news/。パスで分けた子ブログ・サブディレクトリへの設置)

issuer(認可サーバーの識別子)

https://example.com

https://example.com/news/oauth

認可サーバーのメタデータ

https://example.com/.well-known/oauth-authorization-server・https://example.com/.well-known/openid-configuration

https://example.com/news/oauth/.well-known/openid-configuration

保護リソースのメタデータ(MCP)

https://example.com/.well-known/oauth-protected-resource/mcp/

https://example.com/news/oauth/.well-known/oauth-protected-resource/mcp/

保護リソースのメタデータ(REST API)

https://example.com/.well-known/oauth-protected-resource/rest-api/

https://example.com/news/oauth/.well-known/oauth-protected-resource/rest/

認可(ブラウザで開く画面)

https://example.com/admin/oauth_authorize/

ブログの URL の下の admin/oauth_authorize/

トークン・失効・動的登録

https://example.com/oauth/token/・/oauth/revoke/・/oauth/register/

https://example.com/news/oauth/token/・revoke/・register/

  • 401 の WWW-Authenticate ヘッダーの resource_metadata は、上の保護リソースのメタデータの URL を指します。

  • パスのあるブログは、ドメインの直下の /.well-known/ では答えません(サブディレクトリのサイトには届かず、パスで分けた子ブログで答えると親のブログの認可サーバーへつないでしまうため)。

  • Claude Code は、ドメインの直下の /.well-known/oauth-authorization-server だけを見ます(2026 年 11 月時点)。パスのあるブログには、Claude Code から OAuth で接続できません。API トークンを使ってください。

  • MCP サーバー・REST API のどちらかが無効なら、その保護リソースのメタデータは 404 になります。

  • メタデータの URL は、ブログの URL の設定から作ります。リクエストの Host ヘッダーは使いません。

# ドメインの直下のブログ
curl -i https://example.com/.well-known/oauth-authorization-server
curl -i https://example.com/.well-known/oauth-protected-resource/mcp/

# パスのあるブログ(ブログの URL が https://example.com/news/ のとき)
curl -i https://example.com/news/oauth/.well-known/openid-configuration
curl -i https://example.com/news/oauth/.well-known/oauth-protected-resource/mcp/

認可サーバーのメタデータの例

ドメインの直下のブログで、CIMD と動的登録をオンにしたときの応答です。応答のヘッダーは次のとおりです(どこからでも読めるよう、access-control-allow-origin: * が付きます)。

HTTP/2 200
content-type: application/json; charset=utf-8
cache-control: no-store
x-robots-tag: noindex
access-control-allow-origin: *
{
  "issuer": "https://example.com",
  "authorization_endpoint": "https://example.com/admin/oauth_authorize/",
  "token_endpoint": "https://example.com/oauth/token/",
  "revocation_endpoint": "https://example.com/oauth/revoke/",
  "registration_endpoint": "https://example.com/oauth/register/",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none", "client_secret_basic", "client_secret_post"],
  "revocation_endpoint_auth_methods_supported": ["none", "client_secret_basic", "client_secret_post"],
  "scopes_supported": ["read", "write", "entries:read", "entries:write", "media:read", "media:write", "categories:read", "categories:write", "blogs:read", "blogs:write", "modules:read", "modules:write", "tags:read", "tags:write", "rules:read", "rules:write", "config-sets:read", "config-sets:write", "configs:read", "field-definitions:read", "cache:read", "cache:write", "fulltext:read", "fulltext:write"],
  "client_id_metadata_document_supported": true,
  "authorization_response_iss_parameter_supported": true,
  "service_documentation": "https://developer.a-blogcms.jp/rest-api/"
}

キー

内容

issuer

認可サーバーの識別子

authorization_endpoint

ブラウザで開く認可の画面(管理画面の oauth_authorize)

token_endpoint・revocation_endpoint

トークンの発行・失効

registration_endpoint

動的クライアント登録。「動的クライアント登録(DCR)」がオフのときは出ません

response_types_supported・grant_types_supported

認可コードフロー(code)と、authorization_code・refresh_token

code_challenge_methods_supported

PKCE は S256 だけ(必須)

token_endpoint_auth_methods_supported

none(公開クライアント)・client_secret_basic・client_secret_post

scopes_supported

OAuth で付与できるスコープ。専用スコープは「専用スコープの付与」がオンのときだけ並びます

client_id_metadata_document_supported

CIMD を受け付けるとき true。「CIMD の受け入れ」がオフのときは出ません

authorization_response_iss_parameter_supported

認可の応答に iss を付けます

service_documentation

開発者向けドキュメントの URL

保護リソースのメタデータの例

MCP サーバーの保護リソースのメタデータです。

{
  "resource": "https://example.com/mcp/",
  "authorization_servers": ["https://example.com"],
  "scopes_supported": ["read", "write", "entries:read", "entries:write", "media:read", "media:write", "categories:read", "categories:write", "blogs:read", "blogs:write", "modules:read", "modules:write", "tags:read", "tags:write", "rules:read", "rules:write", "config-sets:read", "config-sets:write", "configs:read", "field-definitions:read", "cache:read", "cache:write", "fulltext:read", "fulltext:write"],
  "bearer_methods_supported": ["header"]
}

キー

内容

resource

保護リソースの識別子(MCP サーバーの URL)。OAuth の resource パラメーターに使う値です

authorization_servers

認可サーバーの issuer

scopes_supported

OAuth で付与できるスコープ

bearer_methods_supported

トークンはヘッダー(Authorization: Bearer)で送ります

.htaccess の設定

既存のサイトの .htaccess は、アップデートで書き換わりません。Apache で OAuth と MCP を使うときは、同梱の htaccess.txt と比べて、次の 3 か所があるかを確かめます。

箇所

無いとどうなるか

ドットで始まるファイルの拒否から /.well-known/ を除く(<Files ~ "^\.(?!well-known$)">)

ドメインの直下の /.well-known/oauth-authorization-server が 403 になり、クライアントが認可サーバーを見つけられません

RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

サーバーの構成によっては Authorization ヘッダーが PHP に届かず、正しいトークンでも 401(missing_token)になります

「最後にスラッシュをつける」規則から rest-api・mcp・oauth と /.well-known/ のメタデータを除く 2 行

パスのあるブログの .../oauth/.well-known/openid-configuration が 301 になり、クライアントがメタデータを見つけられません。末尾に / の無い URL への POST も 301 になり、本文が失われます

同梱の htaccess.txt の該当部分です。ほかの規則はそのまま残し、この部分を合わせます。

# ---------------------------------------
# 隠しファイル(ドットファイル)へのアクセス禁止
# ---------------------------------------
# /.well-known/ は除く(OAuth の認可サーバーのメタデータ(RFC 8414)や、証明書の発行の確認などで外から読まれる場所のため)
<Files ~ "^\.(?!well-known$)">
  Require all denied
</Files>

# ---------------------------
# URL書き換え設定
# ---------------------------
RewriteEngine on
# RewriteBase /
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

# (中略。webp・存在するファイル・index.html の規則はそのまま)

# ---------------------------
# 最後にスラッシュをつける
# ---------------------------
# REST API・MCP・OAuth(予約セグメント rest-api・mcp・oauth を含むパス)はリダイレクトしない(POST・PATCH の本文がリダイレクトで失われるため)
# REST_API_SEGMENT・MCP_SEGMENT・OAUTH_SEGMENT を変更した場合は、rest-api・mcp・oauth を同じ値に書き換えてください
RewriteCond %{ENV:has_encoded_query} !1
RewriteCond %{REQUEST_URI} !(^|/)(rest-api|mcp|oauth)(/|$)
# ルートの OAuth のメタデータ(/.well-known/oauth-authorization-server・openid-configuration・oauth-protected-resource)もリダイレクトしない
RewriteCond %{REQUEST_URI} !^/\.well-known/(oauth-authorization-server|openid-configuration|oauth-protected-resource)(/|$)
RewriteCond %{REQUEST_URI} !/$
RewriteCond %{REQUEST_URI} !\.[^/\.]+$
RewriteRule ^.+[^/]$ %{REQUEST_SCHEME}://%{HTTP_HOST}%{REQUEST_URI}/ [R=301,L]

古いサイトでは、「最後にスラッシュをつける」規則が次の形になっています。上の例の 2 行(rest-api|mcp|oauth と .well-known の除外)を、RewriteCond %{REQUEST_URI} !/$ の前に足します。

# 古い .htaccess の例(この形のままだと OAuth のメタデータが 301 になる)
RewriteCond %{REQUEST_URI} !/$
RewriteCond %{REQUEST_URI} !\.[^/\.]+$
RewriteRule ^.+[^/]$ %{REQUEST_SCHEME}://%{HTTP_HOST}%{REQUEST_URI}/ [R=301,L]

config.server.php で REST_API_SEGMENT・MCP_SEGMENT・OAUTH_SEGMENT を変えた場合は、rest-api|mcp|oauth をその値に書き換えます(MCP サーバーを有効にする(設定項目の一覧))。

対応する仕様

  • OAuth 2.1 の認可コードフロー。PKCE は S256 が必須です。

  • グラントの種類は authorization_code と refresh_token。クライアントの認証方式は none・client_secret_basic・client_secret_post。

  • 認可サーバーのメタデータ(RFC 8414)。OpenID Connect Discovery の URL でも同じメタデータを返します(ID トークンは発行しません)。

  • 保護リソースのメタデータ(RFC 9728)と、接続先を指定する resource パラメーター(RFC 8707)。resource を省いた認可は、有効な入口(MCP サーバーを優先)を接続先にします。

  • 動的クライアント登録(RFC 7591)。公開クライアント(secret なし)だけを登録します。リダイレクト URI は 5 件まで、本文は 8 KB まで、サイト全体で 500 件までです。

  • クライアント ID のメタデータ文書(CIMD)。取得は 5 秒・5 KB まで、リダイレクトは追わず、application/json だけを受け付けます。リダイレクト URI は 10 件までです。

  • トークンの失効(RFC 7009)、認可の応答の iss(RFC 9207)。

  • MCP の認可の仕様(modelcontextprotocol.io)に沿っています。

よくある質問・つまずき

症状

原因と確かめ方

メタデータの URL が 404

OAuth 認可サーバーが無効、MCP サーバー(または REST API)が無効、またはパスのあるブログでドメインの直下の URL を見ています。上の表のブログの置き方に合った URL で確かめます。

メタデータの URL が 403

.htaccess のドットで始まるファイルの拒否から /.well-known/ を除いていません。

メタデータの URL が 301

.htaccess の「最後にスラッシュをつける」規則の除外がありません。

メタデータの URL が CMS のページ(HTML)を返す

ウェブサーバーの設定で、/.well-known/ へのリクエストが CMS(index.php)に届いていません。.htaccess やウェブサーバーの設定で、/.well-known/ を別の場所へ向けていないかを確かめます。