Pega 外部API連携の OAuth 2.0 認証設計|グラント選択とトークン管理の判断

「Pega の OAuth 設定」と言っても、ユーザーを Pega にログインさせる inbound の SSO と、Pega が外部 API を叩く outbound の連携認証はまったくの別物だ。本稿は後者、コネクタの認証プロファイル(Authentication Profile)における OAuth 2.0 設計にフォーカスする。バックエンド連携で Client Credentials を選ぶべき理由、トークンの期限切れと再取得をどう設計するか、そして移送で崩れないシークレット/スコープ管理までを扱う。

結論から:システム間連携は Client Credentials、まず inbound と outbound を切り分ける

「Pega で OAuth の設定をしたい」という相談は頻繁に受けますが、この一言には性質のまったく違う 2 つの話が混ざっています。ひとつはユーザーを Pega にログインさせる認証(inbound の SSO / OpenID Connect)。もうひとつは、Pega が外部の API を呼びに行くときの連携認証(outbound)です。本記事が扱うのは後者、外向き(アウトバウンド)コネクタの認証プロファイル(Authentication Profile)における OAuth 2.0 設計です。

結論を先に述べます。

特定ユーザーの文脈を持たないシステム間連携(バックエンド呼び出し)は Client Credentials を既定にする。特定ユーザーの代理でアクセスする必要があるときだけ Authorization Code / Refresh Token を検討する。そしてどのグラントを選んでも、トークンのキャッシュと期限切れ時のリフレッシュ・401 リトライ、シークレットの Keystore 管理、環境依存値の外出しをセットで設計する。

「とりあえず OAuth」で付与方式(グラント)を曖昧に選ぶと、サーバー間連携なのにブラウザリダイレクトを前提としたフローを選んで詰まる、トークン期限切れで断続的に失敗する、移送のたびにシークレットを手で書き換える、といった典型的な事故につながります。本記事では、この判断を具体的な分岐として整理します。

アウトバウンド連携の OAuth 2.0 グラント選択 Pega が外部APIを呼ぶアウトバウンド連携で、特定ユーザーの文脈が不要ならシステム間の Client Credentials、特定ユーザーの代理でアクセスするなら Authorization Code / Refresh Token を選ぶ判断フロー図。 Pega が外部APIを呼ぶ認証設計 (アウトバウンド=認証プロファイル) その呼び出しに、特定ユーザーの 文脈(本人性・個別権限)が要る? いいえ(システム間) Client Credentials システム間連携(バックエンド)の既定 ・特定ユーザーの文脈を持たない呼び出し ・client secret か private_key_jwt(秘密鍵で署名した JWT) ・秘密は Keystore/認証プロファイルで管理 はい(ユーザー代理) Authorization Code / Refresh Token 特定ユーザーの代理 でアクセスする時 ※サーバー側は リダイレクト無し → 取得・保管を別設計 対応グラント・Provider 設定・UI は版により異なる ― 対象バージョンの製品ドキュメントで確認
図:特定ユーザーの文脈が要らないシステム間連携は Client Credentials が既定。特定ユーザーの代理でアクセスするときだけ Authorization Code / Refresh Token を検討し、サーバー側はリダイレクトが無いためトークンの取得・保管を別途設計する。

まず切り分ける:inbound の SSO と outbound の連携認証は別問題

設計を誤る最大の原因は、この 2 つを同じ「OAuth 設定」として扱ってしまうことです。

  • inbound(ユーザーが Pega にログインする) — 業務ユーザーが SSO / OpenID Connect で Pega にサインインする話。Authentication Service 側で設定し、認証されたユーザーは Pega のオペレーターにマッピングされます。ブラウザとエンドユーザーが介在します。
  • outbound(Pega が外部 API を呼ぶ) — Pega が OAuth 2.0 クライアントとして外部サービスのトークンエンドポイントからアクセストークンを取得し、API を叩く話。**コネクタが参照する認証プロファイル(Authentication Profile)**で設定します。多くの場合、ブラウザもエンドユーザーも介在しません。

この 2 つは設定場所も、登場人物も、選ぶべきグラントも違います。inbound の SSO 設定をそのままコネクタに流用しようとして行き詰まるのは、切り分けができていない典型です。inbound 側の設計は別記事(Pega の SSO / OAuth 認証設計)で扱っているので、本記事は outbound に絞ります。

アウトバウンド連携の認証は「認証プロファイル」で設計する

外向きコネクタ(REST など)の認証は、コネクタ自体ではなく、コネクタが参照する認証プロファイルに設計を集約します。認証タイプに OAuth 2.0 を選ぶと、そこで付与方式(グラント)を選択し、トークンエンドポイント・クライアント ID / シークレット・スコープといった接続情報を構成します。

ポイントは、認証の関心事をコネクタから切り離して認証プロファイルに寄せることです。同じ外部システムを複数のコネクタから呼ぶなら、認証プロファイルを共有すればトークン取得ロジックも一元化できます。コネクタ側はビジネスロジックとリクエスト/レスポンスのマッピングに集中し、「どう認証するか」は認証プロファイルの責務、という役割分担が保守性の土台になります。

グラント選択の起点:「特定ユーザーの文脈が要るか」

グラント選択で最初に問うべきは、機能比較ではなく「その API 呼び出しに、特定ユーザーの本人性や個別の権限が必要か」です。

システム間連携 → Client Credentials

バックエンド同士の連携、すなわち「Pega というシステムが、相手システムに対してアプリケーション(あるいはサービスアカウント)として認証する」ケースは、Client Credentials グラントが基本です。特定のエンドユーザーの文脈を持たず、Pega 自身の資格情報でトークンを取得します。B2B のシステム連携や基幹システムとのバックエンド連携の大半はこれに該当します。

クライアント認証の方式は主に 2 通りあります。共有シークレット(client secret)を Basic 認証ヘッダーまたは POST ボディで送る方式と、秘密鍵で署名した JWT アサーションを使う方式(private_key_jwt、Pega の認証プロファイルでは「Private Key JWT」)です。後者は秘密鍵を Pega の外に出さずに署名だけを送るため、シークレットを直接やり取りするより堅牢です。いずれの場合も、秘密情報そのものは後述のとおり Keystore / 認証プロファイル側で管理します。(なお、Pega は付与方式として「JWT Bearer」グラントも別に持ちます。これは JWT を認可グラントそのものとして提示する方式で、ここで言うクライアント認証の private_key_jwt とは別物です。)

特定ユーザーの代理でアクセス → Authorization Code / Refresh Token

一方、「そのエンドユーザー本人として、本人の権限・データにアクセスする」必要がある場合は、**Authorization Code グラント(+ Refresh Token)**を検討します。ユーザー個別の権限で相手 API を呼ばなければならないときに限られます。

ただし注意が必要です。Authorization Code は本来、ブラウザでのユーザー同意とリダイレクトを伴うフローですが、サーバーサイドで動くコネクタにはブラウザリダイレクトが存在しません。したがって、トークンをどこで取得し、どう安全に保管し、コネクタからどう使わせるか——という設計を別途組む必要があります。Client Credentials に比べて格段に重くなるため、「本当に特定ユーザーの代理でなければ成立しないのか」を先に見極めてください。多くの連携は、サービスアカウント+ Client Credentials で足ります。

判断ポイントClient CredentialsAuthorization Code / Refresh Token
呼び出しの文脈システム間・バックエンド(特定ユーザー無し)特定ユーザーの代理
本人同意・ブラウザ不要本来必要(サーバーコネクタには無い)
資格情報client secret / private_key_jwt認可コード → アクセス+リフレッシュトークン
トークンが表すものPega(アプリ/サービス自身)認可したエンドユーザー
設計の重さ軽い(既定)重い(取得・保管の別設計が要る)
主な用途大半の B2B / システム連携ユーザー個別の権限・データが必須のとき

トークンのライフサイクルを設計に織り込む

グラントを選んで終わり、ではありません。トークンには寿命があり、その扱いを連携設計に組み込むことが実務では同じくらい重要です。

Pega は取得したアクセストークンを(ランタイムに)キャッシュして有効期限内は再利用し、期限が切れれば新しいトークンを取得します。認証プロファイルで「Use refresh token if available(利用可能ならリフレッシュトークンを使う)」を有効にしていれば、リフレッシュトークンで新しいアクセストークンを自動取得できます。ここで設計者が織り込むべきは、トークン失効時の挙動です。相手 API がトークン失効時に 401 を返した場合、トークンを更新して同じリクエストを再試行する——この挙動をコネクタのエラー処理・リトライ設計と一体で組みます(失効時の自動再取得・自動リトライがどこまで効くかはバージョンや設定により差があるため、対象バージョンで挙動を確認してください)。

つまり、トークン管理は「認証の話」であると同時に「エラーハンドリングの話」でもあります。401 を単なる失敗として握りつぶすと、トークン期限切れのたびに連携が断続的に落ちる、原因の分かりにくい不具合になります。なお、失効時に自動再試行する以上、その API 呼び出しはべき等に設計しておくのが安全です(同じリクエストが 2 回飛んでも副作用が重複しないこと)。リトライとべき等性はセットで考えます。

秘密情報・スコープ・環境依存値の扱い

秘密は Keystore / 認証プロファイルで管理する

Client Credentials の client secret や、private_key_jwt で使う秘密鍵は、ルールセットに平文で持たないのが鉄則です。これらは Keystore(および認証プロファイル)側で管理し、ルールとしてエクスポートされる領域に生の秘密情報が残らないようにします。ルールセットに直書きすると、移送物やバージョン管理に秘密が乗ってしまい、取り返しがつきません。

環境依存値は外出しする(GRS / Application Settings / DSS)

トークンエンドポイントの URL、クライアント ID / シークレット、スコープは、環境(dev / stg / prod)ごとに異なるのが普通です。これらを移送物にハードコードすると、移送のたびに手で書き換えることになり、書き換え漏れや prod の値を dev に持ち込む事故を招きます。

環境で変わる値は、Pega の Global Resource Settings(GRS)/ Application Settings や Dynamic System Settings(DSS) に外出しし、コネクタ側はそれを参照する形にするのが定石です(GRS はコネクタのエンドポイント URL を環境ごとに切り替えるための公式の仕組みで、ロックされたルールセットを開けずに値を更新できます)。また、認証プロファイル自体はルールではなくデータインスタンスで、アプリケーションのルールセットには含まれません。したがって、クライアント ID/シークレットやトークンエンドポイントは各環境の認証プロファイルとして持たせ、アプリケーションのルール(移送物)には焼き込まない——これが移送で崩れない連携設計の要です。

対応範囲はバージョンで必ず確認する

サポートされるグラント種別、OAuth 2.0 Provider(認可サーバー側の定義)の設定方法、認証プロファイルの UI は、Pega のバージョンによって差があります。本記事の判断軸(inbound / outbound の切り分け、グラント選択、トークン・秘密・環境依存値の扱い)はバージョンに依存しない普遍的な設計原則ですが、具体的な設定手順や対応グラントの範囲は、必ず対象バージョンの公式ドキュメントで確認してください。

よくある失敗

外部連携の OAuth 設計でつまずくパターンは、経験上ほぼ決まっています。

  • inbound と outbound を混同する — ユーザーログインの SSO 設定を、そのままコネクタの認証に流用しようとする。設定場所も登場人物も違うので、最初に必ず切り分ける。
  • システム間連携なのに Authorization Code を選ぶ — 「ユーザーがログインするんだから」と反射的に選び、サーバー側にリダイレクトが無くて行き詰まる。バックエンド連携は Client Credentials が既定。
  • トークン期限切れを設計しない — 401 時のリフレッシュ&リトライを組んでおらず、トークンが切れるたびに連携が断続的に落ちる。原因究明が難しい不具合の温床。
  • シークレットをルールセットに平文で持つ — 移送物やバージョン管理に秘密が乗る。秘密鍵は Keystore、client secret は認証プロファイル(データインスタンス)で管理し、環境依存値は GRS / Application Settings / DSS に外出しする。
  • スコープを過剰に付与する — 必要最小限のスコープに絞らず、広い権限のトークンを取ってしまう。最小権限の原則は連携でも同じ。

まとめ

  • Pega の OAuth は inbound(ユーザーログイン)と outbound(外部 API 呼び出し)を最初に切り分ける。本記事は outbound、認証プロファイルの設計。
  • グラント選択の起点は「特定ユーザーの文脈が要るか」。システム間連携は Client Credentials が既定、特定ユーザーの代理のときだけ Authorization Code / Refresh Token を検討する(サーバー側はリダイレクトが無く重い)。
  • トークンのキャッシュ・リフレッシュ・401 リトライをコネクタのエラー処理と一体で設計し、再試行に備えてべき等にする。
  • 秘密は Keystore/認証プロファイル、環境依存値は GRS / Application Settings / DSS に外出しして、移送で崩れないようにする。
  • 対応グラントや設定 UI はバージョンで異なるため、対象バージョンの公式ドキュメントで確認する。

外部連携の認証は「動けばいい」で組むと、期限切れ・移送・セキュリティのすべてで後から代償を払います。設計の初期に inbound/outbound を切り分け、グラントとトークン管理を一体で決めておくことが、安定した連携の土台になります。


Pega の外部連携・認証設計でお困りの際は、Pega Platform 開発支援 や 無料相談 をご利用ください。Pega 認定資格の最高位 LSA(Lead System Architect)を保有するコンサルタントが、グラント選択からトークン管理・移送設計までご支援します。

関連リンク

このテーマの記事をまとめて読む: Pega の外部連携と非同期処理 用語は Pega 用語集 で引けます

関連記事

Pega バリデーション設計|クライアント検証とサーバー検証の使い分けとUX

「必須チェックはどこに書くべきか」「フォーマットはクライアント、業務ルールはサーバーでいいのか」——Pega のバリデーションは複数の仕組みが重なり、置き場所を誤ると UX 低下とセキュリティホールを同時に招きます。本記事では各検証ルールの適用範囲と、即時性・再利用性・堅牢性のトレードオフから最適な配置を導きます。

記事を読む

Pega Savable Data Page 設計|外部システムへの書き戻しとコネクタ直呼びの使い分け

「データページは読み取り専用」という前提は、Savable Data Page を使うと変わる。読み書きを同じデータ仮想化レイヤに集約できる一方、保存は自動では走らず、コミット境界やエラー処理を誤ると『保存したつもり』の未反映や部分保存を招く。どこまでを Savable Data Page に任せ、どこからをフロー内のコネクタ直呼びにするかを整理する。

記事を読む

Pega 連携の冪等性設計|リトライで二重処理を起こさないための判断

「リトライしたら二重に登録された」——連携で最も痛い事故のひとつです。キュープロセッサやネットワークのリトライは基本 at-least-once で、重複実行は前提として設計すべきものです。本記事では、冪等キー・重複検知・副作用の分離といった手法で、何度呼ばれても安全な連携をどう組むかを整理します。

記事を読む

設計標準と設計レビューのご相談

判断の理由と適用範囲まで書いた設計標準をもとに、設計レビューと内製化を支援しています。