Claude-skill-registry external-integration

外部サービス連携（External Service Integration）機能の開発・修正を行う際に使用。HTTP Request Executor, MappingRule, OAuth/HMAC認証実装時に役立つ。

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/external-integration" ~/.claude/skills/majiayu000-claude-skill-registry-external-integration && rm -rf "$T"

manifest: skills/data/external-integration/SKILL.md

source content

外部サービス連携（External Service Integration）開発ガイド

ドキュメント

documentation/docs/content_03_concepts/06-security-extensions/concept-02-external-service-integration.md

- 外部連携概念

機能概要

外部サービス連携は、HTTP経由で外部APIと連携する層。

HTTP Request Executor: リトライロジック付きHTTPクライアント
MappingRule: JSONPath + 変換関数によるデータマッピング
認証: OAuth 2.0, HMAC, Basic認証
冪等性: Idempotency-Keyヘッダー対応
Rate Limiting: Retry-Afterヘッダー対応

モジュール構成

libs/
└── idp-server-platform/                     # プラットフォーム基盤
    └── .../platform/
        ├── http/
        │   ├── HttpRequestExecutor.java
        │   └── retry/
        │       └── RetryStrategy.java
        ├── mapper/
        │   ├── MappingRule.java            # マッピングルール
        │   ├── FunctionSpec.java           # 関数仕様
        │   ├── ConditionSpec.java          # 条件仕様
        │   ├── TypeConverter.java          # 型変換
        │   ├── ObjectCompositor.java       # オブジェクト合成
        │   └── functions/
        │       ├── FormatFunction.java
        │       ├── TrimFunction.java
        │       ├── ReplaceFunction.java
        │       ├── RegexReplaceFunction.java
        │       └── ... (その他のマッピング関数)
        └── auth/
            ├── OAuth2Authenticator.java
            └── HmacAuthenticator.java

MappingRule

idp-server-platform/mapper/MappingRule.java

内の実際の構造:

public class MappingRule {
    String from;             // JSONPathソース
    Object staticValue;      // 静的値（fromの代わり）
    String to;              // マッピング先
    List<FunctionSpec> functions;  // 変換関数
    ConditionSpec condition;       // 条件

    public MappingRule(String from, String to) {
        this.from = from;
        this.to = to;
    }

    public MappingRule(
        String from,
        String to,
        List<FunctionSpec> functions
    ) {
        this.from = from;
        this.to = to;
        this.functions = functions;
    }
}

Mapping Rule設定

{
  "mapping_rules": [
    {
      "from": "$.response.user.id",
      "to": "external_user_id"
    },
    {
      "from": "$.response.user.roles",
      "to": "custom_properties.roles",
      "functions": [
        {
          "name": "join",
          "args": {
            "separator": ","
          }
        }
      ]
    }
  ]
}

Mapping Functions

idp-server-platform/mapper/functions/

内に実装:

クラス	説明	使用例
`FormatFunction`	テンプレート置換	`{"template": "Bearer {{value}}"}`
`TrimFunction`	空白除去	-
`ReplaceFunction`	文字列置換	`{"from": "a", "to": "b"}`
`RegexReplaceFunction`	正規表現置換	`{"pattern": "...", "replacement": "..."}`

使用場所: Federation（userinfo_mapping_rules）、Identity Verification（mapping_rules）

HTTP Request Executor

idp-server-platform/http/

内:

HTTP Request Executorは、リトライロジックとRate Limiting対応を提供します。

E2Eテスト

e2e/src/tests/
└── (外部連携は各機能のテスト内で検証)
    ├── integration/ida/           # Identity Verification外部連携
    └── usecase/advance/          # Federation外部連携

コマンド

# ビルド
./gradlew :libs:idp-server-platform:compileJava

# テスト
cd e2e && npm test -- integration/ida/
cd e2e && npm test -- usecase/advance/

トラブルシューティング

HTTP Request失敗

URLが正しいか確認
認証情報（OAuth, HMAC）を確認

MappingRuleが動作しない

JSONPath (
```
from
```
) が正しいか確認
ソースデータの構造を確認
FunctionSpecの設定を確認

変換関数が失敗

関数名が正しいか確認（FormatFunction, TrimFunction等）
関数のargsが正しいか確認