カスタム処理から外部APIにOAuthで接続できますか？

はい。apiプラグインのoauth_connectionにOAuth接続の名前を指定すると、そのOAuth接続で取得したアクセストークンをAuthorizationヘッダーに付与してリクエストを送信します。 事前にOAuth接続を作成し、[接続・再認可]でステータスを有効にしておきます。

{assign_array var=queries values=""}
{append var=queries index="limit" value=10}
{api oauth_connection="example_api"
     endpoint="https://api.example.com/v1/items"
     queries=$queries
     json_var="result" status_var="ok" http_code_var="http_code" error_var="oauth_error"}

{if $ok}
    {* $result に JSON をデコードした値が格納されます *}
{elseif $oauth_error}
    {* OAuth接続のエラー。$oauth_error に理由が格納されます *}
{else}
    {* 接続先から2xx以外のレスポンス。$http_code を確認します *}
{/if}

クエリパラメータの配列は、assign_arrayとappendで作成してからqueriesに指定します。Kurocoのテンプレートでは['limit' => 10]のような配列リテラルは使用できません。詳しくは配列を作るときのベストプラクティスを参照してください。

注記

外部MCPサーバーを接続先にした場合も、apiプラグインが行うのはOAuthのアクセストークンを付与したHTTPリクエストの送信です。MCPのツールを呼び出す機能には対応していません。

OAuth接続を作成する

外部APIに接続する場合の手順です。各項目の詳細はOAuth接続を参照してください。OAuth接続の作成には、スーパーユーザーが必要です。

1. [外部システム連携] -> [OAuth接続]をクリックし、[追加]をクリックします。
2. [名前]を入力し、[接続先の種類]で外部API（手動設定）を選択します。[名前]はapiプラグインのoauth_connectionに指定する値です。
3. [グラントタイプ]を選択します。
4. [リソースURL]、[スコープ]、[クライアント情報]、[認可サーバー]の各項目を、接続先サービスで発行・公開されている値に合わせて入力します。JWT Bearerの場合は[JWTのSubject]、[JWT audience]、[秘密鍵 (PEM)]も入力します。
5. Authorization Code + PKCEの場合は、[登録するリダイレクトURI]に表示されたURIを接続先サービスのクライアント設定へ登録します。
6. [保存する]をクリックします。
7. [接続・再認可]をクリックし、認可の手順に従ってトークンを取得します。
8. [ステータス]が有効になったことを確認します。

ヒント

外部MCPサーバーに接続する場合は、[接続先の種類]で外部MCPサーバー（自動探索）を選択し、[保存する]の後に[メタデータを取得]を実行してから[接続・再認可]を実行します。詳しくはOAuth接続を参照してください。

利用できる場所と保存できる管理者

• oauth_connectionを指定したapiは、カスタム処理とバッチ処理でのみ使用できます。それ以外の場所には保存できず、実行時もエラーになります。
• oauth_connectionを指定したapiを含む処理は、スーパーユーザーのみ保存できます。

トークンの更新と再送

• アクセストークンの有効期限が切れている場合は、リクエストの前にトークンを更新・再取得します。
• 接続先が401を返した場合は、トークンを一度だけ更新・再取得して同じリクエストを再送します。再送でも401の場合は、OAuth接続のステータスが要再認可になり、error_varにreauthorization_requiredが格納されます。
• トークンの更新時に認可サーバーが5xx・429を返した場合や通信障害が発生した場合は、保存済みのリフレッシュトークンを維持します。

注意

401の場合の再送は、POSTなどのメソッドでも行われます。接続先が冪等キー（Idempotency-Keyヘッダーなど）に対応している場合は、必要に応じてheadersで指定してください。

制限事項

oauth_connectionを指定した場合は、次の制限があります。

• endpointは必須です。OAuth接続の[リソースURL]と同じオリジンで、リソースURLのパスまたはその配下のパスのみ指定できます。それ以外のURLにはトークンを送信しません。
• 接続先は、公開されているHTTPSの443番ポートのURLのみです。IPアドレスを直接指定したURLやプライベートIPアドレスへの接続はできません。
• リダイレクトは行いません。接続先が3xxを返した場合はエラーになります。
• レスポンスは最大16MiBです。認可サーバーのメタデータとトークンのレスポンスは最大64KiBです。
• cache_time、files、dl_flg、tmp_dl_flg、sslcert、sslkey、cainfoは使用できません。
• headersにAuthorization、Host、Proxy-Authorizationは指定できません。

これらの属性の指定に誤りがある場合は、テンプレートのエラーになります。

oauth_connectionを指定しないapiの動作は変わりません。

結果の格納

結果	status_var	http_code_var	error_var
接続先が2xxを返した	1	HTTPステータスコード	空
接続先が2xx以外を返した	0	HTTPステータスコード	空
OAuth接続のエラーで送信できなかった	0	0	エラー理由

error_varに格納される主な値は次の通りです。

値	内容
reauthorization_required	OAuth接続の認可が必要です。ステータスが要再認可・失効済みの場合や、Authorization Code + PKCEでトークンを取得・更新できない場合に格納されます。管理画面の[OAuth接続]で[接続・再認可]を実行してください。
not_found	指定した名前のOAuth接続が存在しません。
invalid_resource	endpointがOAuth接続のリソースURLの範囲外です。
unsafe_endpoint	接続先が公開されているHTTPSのURLではありません。
redirect_not_allowed	接続先がリダイレクトを返しました。
response_too_large	レスポンスのサイズが上限を超えました。
transport_error	通信に失敗しました。

このほか、認可サーバーが返したエラーの理由が格納される場合があります。

関連ドキュメント

• OAuth接続
• Smarty プラグイン（api）