Claude CodeのDuendeプラグインでIdentityServerの実装指針を使う

duende-skillsは、.NETの認証基盤Duende IdentityServerを作る人向けに、Duende Softwareが配っているClaude Codeプラグインです。OAuth 2.0とOpenID Connectの基礎、IdentityServerの設定、トークンの保護、BFF、ASP.NET Coreの認証・認可までを、スキルとして同梱しています。

認証まわりは、モデルの一般知識だけで書くと「それらしいが古い」コードになりやすい領域です。このプラグインは、その差を埋めるための指針集という位置づけです。導入から、どのスキルがいつ効くか、v7からv8への移行での使い方、導入前に知っておきたい注意点までを順に扱います。

duende-skillsに入っているもの

プラグインの中身は、スキル26個とエージェント2つです。マーケットプレイスの掲載ページでは、提供元はDuende Software、インストール数は470と表示されています。

スキルはREADMEの「Identity & OAuth」表にまとまっています。名前の接頭辞で担当が分かれます。

エージェントは2つです。identity-server-specialist はクライアント定義、トークンの発行、ストア、署名鍵、デプロイを扱い、認証失敗やredirect URI不一致の切り分けも守備範囲に挙げています。oauth-oidc-specialist はRFC、フローの選択、プロトコルのデバッグ、FAPIを担当します。

READMEの注記によると、npx skills で入れるとスキルだけが入り、エージェントはプラグイン経由か手動コピーで入れる形です。

Claude Codeに導入する

Claude Code上では、マーケットプレイスを登録してからプラグインを入れます。READMEに書かれた手順は次の2行です。

/plugin marketplace add DuendeSoftware/duende-skills
/plugin install duende-skills

Claude Codeのドキュメントによると、セッション内の /plugin install はその場でインストールせず、プラグインの詳細画面を開きます。内容を確認し、スコープを選んでから入れる流れです。更新は /plugin marketplace update で行います。

シェルから入れたいときは、プラグイン名とマーケットプレイス名を @ でつなぎます。READMEではCopilot CLIの例として duende-skills@duende-skills と書かれています。Claude Codeでも同じ形式で指定できます。

claude plugin install duende-skills@duende-skills

チームで同じ指針を使いたいなら、プラグインの配り方に落とし穴があります。URLでマーケットプレイスを配る場合の注意はClaude CodeのプラグインマーケットプレイスをURLで配る落とし穴にまとめています。

一緒に入れると良いとされるもの

READMEは、一般的な.NET開発の指針をまとめた別リポジトリ dotnet-skills も勧めています。duende-skillsは認証・認可に絞っており、C#の書き方、EF Core、DI、Playwrightテストなどは対象外と明記されているためです。

/plugin marketplace add Aaronontheweb/dotnet-skills
/plugin install dotnet-skills

どのスキルがいつ効くのか

スキルはスラッシュコマンドとして打つ前提ではなく、Claudeが作業内容に合わせて読み込む知識として作られています。たとえば identityserver-token-security のSKILL.mdは、冒頭に次のようなfrontmatterを持ちます。

---
name: identityserver-token-security
description: Advanced token security features in Duende IdentityServer including DPoP, mTLS certificate binding, Pushed Authorization Requests (PAR), JWT Secured Authorization Requests (JAR), and FAPI 2.0 compliance configuration.
invocable: false
---

Claude Codeのドキュメントでは、description が「Claudeがいつそのスキルを使うかを決める材料」と説明されています。プラグイン同梱のスキルは /plugin-name:skill-name の名前空間で呼び出せます。つまり「DPoPで保護したいがPARも要るか」といった質問を投げると、説明文に合うスキルが読み込まれる設計です。

なお、このfrontmatterの invocable: false というキー名は、Claude Codeのドキュメントにあるfrontmatter表には載っていません。表にあるのは user-invocable と disable-model-invocation です。キーを足しても何が起きるかは、手元のバージョンで / のメニューに出るかを見て確かめるのが確実です。

用途別に見る、スキルの当たりどころ

実例: v7からv8への移行で使う

指針集の価値が最も分かりやすいのは移行です。identityserver-upgrade-v7-to-v8 は、v7.4からv8.0への移行に絞ったスキルで、18段階の手順を持ちます。

最初の原則は、v8が.NET 10を要求するので対象フレームワークを先に更新すること、そして破壊的変更はすべてコンパイルエラーとして出ることです。挙動が黙って変わることはない、という前提で、機械的な置換で進められると書かれています。

IClock から TimeProvider への置換は、スキルがBefore/Afterで示す典型です。プロパティ UtcNow がメソッド GetUtcNow() に変わる点まで書かれています。

// v7
public DateTime Now => _clock.UtcNow.UtcDateTime;
 
// v8
public DateTime Now => _timeProvider.GetUtcNow().UtcDateTime;

移行の落とし穴が先に分かる

スキル末尾の「Common Pitfalls」は、ビルドが通ってから出る問題を集めています。公式ドキュメントを順に読むと見落としやすい項目です。

• HybridCacheは [FromKeyedServices("ConfigurationStoreCache")] で注入する。素のHybridCacheを注入すると別のインスタンスになる
• v8形式のライセンスキーは、v7以前やBFFのランタイムで IDX10503 の署名検証エラーになる
• Server-Side Sessions、自動鍵管理、SAMLは、ライセンスはあるのに権限が足りないと起動時に例外になる。下位環境にも本番のライセンスキーを入れて確かめる

最後の項目は、v8が未ライセンスの機能を黙って無効にしなくなった、という変更です。ステージング環境で検証を飛ばすと、本番で初めて落ちます。

BFFと署名鍵のスキルが先回りで挙げる失敗

移行以外でも、スキルの末尾には「Common Pitfalls」が置かれています。ビルドも起動も通るのに、運用で壊れる型が集めてあります。

duende-bff: SPAのトークンをブラウザに出さない

duende-bff の原則は、OAuthトークンをサーバー側にだけ置き、ブラウザにはHTTP-only・Secure・SameSiteのCookieだけを見せることです。すべてのBFF APIエンドポイントで X-CSRF: 1 ヘッダーを必須にする点も、原則として挙げられています。落とし穴の例は次のとおりです。

/bff/login と /bff/logout を fetch() で呼ぶ失敗も挙がっています。この2つはOIDCのリダイレクトを起こすので、window.location.href によるブラウザ遷移で呼ぶ必要があります。ミドルウェアは UseRouting() のあと、UseAuthorization() の前に UseBff() を置く順序で、ずれてもエラーは出ずにアンチフォージェリが効かなくなる、という注意書きまでついています。

identityserver-key-management: 鍵の入れ替えは段階的に

署名鍵のスキルは、鍵を一気に切り替えると検証失敗が起きるため、移行期間を置く段階的な入れ替えか、自動の鍵管理を使うよう指針を示します。主な落とし穴は次のとおりです。

• keys ディレクトリをソース管理に入れない。開発用のData Protection鍵で保護されたまま本番に持ち込むと、読めなくなることがある
• Data Protectionの鍵と署名鍵は別物。前者は保存時の対称暗号、後者はトークン署名の非対称暗号で、両方を設定する
• IdentityServerはX.509証明書の有効期限を検証しない。期限切れの証明書でも署名はできてしまう。期限は技術的な強制ではなく、運用上の取り決めになる
• PropagationTime は、クライアントやAPIがキーをキャッシュする最長時間より長くする

署名に使えるアルゴリズムの一覧や、HSMやクラウドKMSで署名する構成、鍵が漏えいしたときの対応手順も、このスキルの節に分かれています。

指針を実装に引き込む使い方

プラグインを入れただけでは、Claudeがどのスキルを使うかは作業の文面しだいです。プロジェクトの CLAUDE.md に、認証まわりの作業でスキルを確認するよう書いておくと、読み込まれやすくなります。次は記述の一例です。

## 認証・認可
- IdentityServerの設定やトークン関連の変更では、duende-skillsのスキルを参照する
- クライアント定義を変えたら、`dotnet build` と統合テストを実行して結果を確認する
- ライセンスの権限エラーに備え、Server-Side Sessionsや鍵管理を触る変更では起動確認まで行う

テストの書き方は identity-testing-patterns が扱い、WebApplicationFactoryでトークン発行をモックする方針です。ASP.NET Core側の統合テストの回し方はClaude CodeでASP.NET Core Web APIを開発するに手順があります。プラグインやスキルの全体像はClaude Codeの全体像を参照してください。

DPoPを入れる例で読み方を確認する

identityserver-token-security はDPoPの設定を、サーバー側とAPI側の両方で示します。クライアント側では RequireDPoP = true を指定します。API側ではJWT bearerにDPoP処理を足し、リプレイ検出用にキー付きHybridCacheを登録します。

DPoPのリプレイ検出は既定で有効で、キー付きHybridCacheが未登録だと、証明の検証時に InvalidOperationException が出ると書かれています。複数インスタンスで動かすときは、HybridCacheの第2層として IDistributedCache(Redisなど)も登録する、という指針です。一般的なDPoP解説では抜けやすい点です。

エディション条件も明記されています。同スキルの表では、DPoPはEnterpriseエディションが必要で、mTLSは全エディションで使える項目を含みます。導入するトークン保護の方式が、契約中のライセンスで使えるかは先に確かめる価値があります。

提供元の評価結果をどう読むか

READMEは、各スキルを7〜18個の現実的なプロンプトで評価していると説明します。スキルを読み込んだ場合と、読み込まない基準の場合の両方で答えさせ、あらかじめ決めた判定項目で採点する方式です。2026年10月16日の結果(claude-opus-5.5、6回目)は、277の評価・26スキル・1,236項目で、スキルありが1,236項目中1,236項目(100%)、スキルなしが875項目(70.8%)と載っています。

差分が大きいのは、新しい機能や、公開情報が少ない機能のスキルです。

一般に知られた設定(identityserver-configuration)では差が11%にとどまり、プレビュー機能や新版の移行では大きく開きます。モデルの学習時点にない情報ほど、スキルの効き目が大きいという読み方ができます。

ただし、この数字は提供元が自分で用意した判定項目での自己評価です。第三者の再現は載っていません。自分のプロジェクトで効くかは、実際の作業で「スキルあり」と「なし」を比べて見るのが確実です。

導入前に押さえる注意点

• 対象は認証・認可に限られます。C#の一般的な書き方やEF Coreは別のスキル集の領分です
• スキルの内容はDuendeのバージョンに依存します。移行スキルが前提とするのはv7.4からv8.0です。それ以外の版を使っているなら、スキルが示すAPI名が手元のコードと合うか確かめてください
• 認証基盤の変更は、Claudeに書かせたあとにテストで確かめます。署名鍵、redirect URI、ライセンスは、コードが通っても運用で落ちる箇所です
• 利用できるのはClaude Codeに限りません。READMEはCopilot CLI、VS Code、Cursor、Codexへの導入手順も載せています

まとめ

duende-skillsは、IdentityServerを使う.NETチームが、設定・トークン保護・BFF・移行をClaude Codeに任せるときの下地になります。効果が出やすいのは、v8への移行のように、モデルの一般知識だけでは外しやすい作業です。まず identityserver-upgrade-v7-to-v8 が要る場面で入れて、結果をテストで確かめるところから始めると、効き目を測りやすくなります。