はじめてのOkta Workflowsシリーズ 第9回 API ConnectorのOAuth認可による連携
目次
- OAuth2.0認可を提供するアプリケーションとAPI Connector
- API Connector コネクションにおけるOAuthの設定
- アプリケーションOAuth2.0設定 -Box編
- アプリケーションOAuth2.0設定 -Google Workspace編
- 最後に
- Okta Workflowsシリーズ
このシリーズの前回の記事では、Okta WorklowsのAPI Connectorについて、実例(ChatGPT APIとの連携)をもとに紹介しました。API Connectorを通じてOkta Workflowsはクラウド／オンプレミス問わずRESTful APIをもつどのようなアプリケーションとも連携ができます。さらに、既存でコネクタが用意されている各アプリケーションとのOkta Workflowsを介した相互連携の相乗効果により、IT運用自動化全体の効率性が飛躍的に高まります。
今回は、前回では深く触れられなかった、API ConnectorコネクションのOAuth認可による方式についてご紹介いたします。OAuth認可は多くのアプリケーションが対応しており、セキュリティ面でもより適した選択肢となります。
OAuth2.0認可を提供するアプリケーションとAPI Connector
API Connectorコネクションについては、OAuth2.0を用いた「OAuth」のオプションと、HTTPヘッダに特定の静的なクレデンシャル情報（APIキー等）を挿入する「Custom」のふたつが主要な認証・認可方法です。前回は「Custom」の設定例を紹介いたしましたが、実際は「OAuth」を用いるアプリケーション、あるいは両方とも可能なアプリケーションが多く、両方可能であれば「OAuth」を用いることがセキュリティ上、推奨されます。
本稿では、まずAPI Connectorコネクションの設定の一般的な留意点について説明します。次に、実際のアプリケーションの例として、ある程度固定されたOAuthの設定のアプリケーションであるBox、スイート系アプリケーションとして多様なAPIのセットを有しカスタマイズが可能なアプリケーションであるGoogle Workspaceをとりあげます。OAuth2.0の標準やシーケンスをある程度見据えながら、情報収集とスムーズな設定の完了を目標とします。
※Box、Google WorkspaceはいずれもOkta Workflows上でアプリケーションコネクタでコネクションがすでに提供されています。その範囲内でアクションやイベントの定義が可能である限り、これらのアプリケーションコネクタを利用することをお勧めいたします。
API Connector コネクションにおけるOAuthの設定
Okta Workflowsからアプリケーションに対して行うアクションにおいてCustom API Actionでも対応できない操作・既存コネクターの対応範囲を超える操作を行う場合に、API Connectorを用いることになります。この点は前回のはじめてのOkta Workflowsシリーズでも述べた通りです。今回実例で取り上げるBoxおよびGoogleドライブ（Google Workspace）は、Okta Workflowsから接続、操作する上でのAPI Connectorコネクションによる認可設定においてOAuth2.0を用いることになります。ここではまず一般的な設定手順を説明します。
対応するOkta Workflowsドキュメントウェブページは以下です。
API Connector コネクションを新規に作成する場合は、上のメニュー[Connections] -> [+New Connection] -> [New Connection]の一覧から[API Connector]を選択します。
[Auth Type]で[OAuth]を選択します。次の5つのパラメータが必要です。
[Access Token Path]、[Authorize Path] 、[Client ID]、[Client Secret]、[Scope]
OAuthのコンテキストでOkta WorkflowsにおけるAPI Connectorコネクションは以下のように整理されます。
- クライアント：Okta Workflows
- リソースサーバー：連携対象アプリケーション（Box、Googleドライブ）
- 認可サーバー：多くの場合、連携対象アプリケーション側で用意される。認可エンドポイントおよびトークンエンドポイントを通じてクライアントからのリクエストを受信する
- リソースオーナー：連携対象アプリケーション上の管理者ユーザーまたはサービスアカウント。OAuthでの認可に先だって認証される。この認証はとくにOkta Workforce Identity Cloud (以下、Okta WIC)のSSOである必要はない
API ConnectorコネクションのOAuth認可の大まかな設定手順は以下です。
まず認可サーバー上でクライアント（Okta Workflows）を登録します。多くの場合、連携アプリケーションのAPI関連の設定項目で「アプリケーションを登録」のような形で設定します。この際に必要となるのがリダイレクトURI（コールバックURL）の情報で、認可プロセスにおけるクライアント（Okta Workflows）側の認可コードの受信先です。上記ドキュメントページによると、以下のURLとなります。
- https://oauth.workflows.okta.com/oauth/httpfunctions/cb （本番Okta org）
- https://oauth.workflows.oktapreview.com/oauth/httpfunctions/cb （プレビュー/Sandbox Okta org）
登録が済むとクライアントIDとクライアントシークレットが発行されるので、クライアント（Okta Workflows）側にコピーします。これらが上記コネクション設定パラメータのうちの[Client ID]、[Client Secret]になります。認可サーバーはこの値を提出してきたクライアントを登録済みのクライアントとみなします。クライアントは認可サーバーに対し、これらをHTTPS上でBasic認証またはボディに含める形（認可サーバーの仕様に従います）で認可エンドポイントに提出することで認可コードの発行を受けます。
クライアント（Okta Workflows）からみた通信先、すなわち各リクエストの送信先である認可サーバー上のURLである認可エンドポイント、トークンエンドポイントの情報は、認可サーバーの情報としてアプリケーションの設定画面上かドキュメントで提供されます。これらは上記コネクション設定パラメータの[Authorize Path]、[Access Token Path]に相当します。
[Scope]に入るパラメータは文字通りOAuth認可スコープです。目的のAPI Connectorアクションにて使用するAPIに応じて必要となる認可のスコープが決まります。どのスコープが必要かを調べるには、アプリケーションのAPIリファレンスや開発者ドキュメント上で、「OAuth Scopes」などとまとめてあるか、それぞれのAPIの説明に付してあります。複数のOAuth認可スコープについてはスペースまたはカンマで区切って列挙する形で設定します。
APIで必要なOAuth認可スコープについて、Okta WICを対象アプリケーションとした例をとりあげます。2024年8月現在、APIリファレンスにあたる開発者ドキュメントは旧版と新版（ベータ版として提供中）にわかれてしまっていますが、基本的には新版を用います。
まとまったOAuth認可スコープの情報は以下から参照できます。こちらの中でOkta WICを対象アプリケーションとしてAPI操作する場合には主に「Okta Admin Management」のスコープを用います。
また、個別のAPIの説明ページでも、それに必要なスコープが示されています。前回でも例として取り上げた「ある特定のデバイスをアクティブ化したい」にあたるActivate a DeviceのAPIの説明は以下です。
このAPI「https://{yourOktaDomain}/api/v1/devices/{deviceId}/lifecycle/activate」に必要なスコープは「okta.devices.manage」であることが示されています。
アプリケーションOAuth2.0設定 -Box編
ここでは、Boxを連携対象アプリケーションとした例のAPI Connectorコネクションの設定を行います。
認可サーバーの設定は、Boxの開発者コンソール上で「マイアプリ」上にアプリケーションを作成することで行います。Boxが提供する設定手順のドキュメントはこちらです。
管理者または共同管理者であるユーザーとしてBoxにログインし、左下の「開発者コンソール」から開発者コンソールに移動します。
「マイアプリ」上に登録がない場合にはひとつめのアプリケーションの登録が開始されます。そうでない場合は「アプリの新規作成」をクリックします。アプリタイプの選択においては、ここでは「カスタムアプリ」を選択します。
認証方法の選択肢では、「ユーザー認証(Oauth 2.0)」を選択し[アプリの作成]をクリックします。
OAuthにおけるクライアント登録（Boxアプリ「Okta Workflows API Connector」）の設定画面になりますので、「構成」タブに移ります。
「リダイレクトURI」に以下を入力し追加します。これは先述の、クライアント（Okta Workflows）の認可コードの受信先であり、認可サーバーはここに登録されたリダイレクトURI（コールバックURL）と一致した先にリダイレクトされることをもって、認可を行います。
- https://oauth.workflows.okta.com/oauth/httpfunctions/cb （本番 Okta org）
- https://oauth.workflows.oktapreview.com/oauth/httpfunctions/cb （プレビュー/Sandbox Okta org）
また、「アプリケーションスコープ」において、「Boxに格納されているすべてのファイルとフォルダへの書き込み」「ユーザーを管理する」「グループを管理する」に追加でチェックを入れます。
右上の[変更を保存]をクリックし、変更内容を保存します。
これで、認可サーバーの設定が完了しました。同画面上の「クライアントID」「クライアントシークレット」の値をコピーして、Okta Workflowsコンソールに移ります。
Okta WorkflowsコンソールでAPI Connectorのコネクションの設定をします。「Connections」タブ上で[+New Connection]をクリック、表示されたダイアログ上で行います。これはOAuthクライアントの設定にあたります。
[Name]には任意の名前、[Auth Type]で「OAuth」を選択します。
認可サーバー情報として認可エンドポイントおよびトークンエンドポイントのURLを[Authorize Path]、[Access Token Path]に入力します。
- [Authorize Path] https://account.box.com/api/oauth2/authorize
- [Access Token Path] https://api.box.com/oauth2/token
これらの情報は、以下のBoxの開発者ドキュメントから特定できます。
- https://ja.developer.box.com/guides/authentication/oauth2/without-sdk/
- https://ja.developer.box.com/reference/get-authorize/
- https://ja.developer.box.com/reference/post-oauth2-token/
[Client ID]、[Client Secret]には、先ほどのBox開発コンソール上で得たものを入力します。
[Scope]では、「root_readwrite manage_managed_users manage_groups」とスペースをはさんで列挙します。これらについては以下の開発者ドキュメントのOAuth認可スコープを参照します。
- https://developer.box.com/guides/api-calls/permissions-and-errors/scopes/
[Create]をクリックすると、Boxに対する認証が開始されますので、管理者ユーザーで認証を行います。この認証はOkta WICでのSSOである必要はありません。また、すでに同じブラウザで認証済みであれば認証行為は発生しません。
以下のような画面が表示されますので、[Boxへのアクセスを許可]をクリックします。
これで正しくBoxへのAPI Connectorコネクションが追加されました。このコネクションを実際のフロー作成にてAPI Connectorアクションカードで指定することで、目的のAPI操作をBoxに対して行うことができるようになりました。
アプリケーションOAuth2.0設定 -Google Workspace編
ここでは、Google Workspaceを連携対象アプリケーションとした例のAPI Connectorコネクションの設定を行います。
Google Workspaceを含む、Googleのサービス全般に関するAPIの認証や承認、APIキーやOAuth 2.0クライアントIDの管理は、Google Cloudコンソールに統合されています。このため、認可サーバーの設定は、いったんGoogle Workspaceの管理コンソールから離れて、Google Cloudコンソール（https://console.cloud.google.com）上で行います。Googleが提供する詳細な設定手順のドキュメントはこちらです。
Google Cloudコンソールに、Google Workspace管理者ユーザーのアカウントでログインします。
ログインしたら以下の画面になります。Google WorkspaceのAPIの制御に関する設定、認可サーバーの設定はクイックアクセスの[APIとサービス]から開始します。
Google WorkspaceのAPIの設定は、「組織」の下の「プロジェクト」という枠の中で定義する形となります。「組織」は、Google Workspaceのテナントに相当します。 「プロジェクト」がまだ作成されていない場合は以下の画面になりますので、[プロジェクトを作成]をクリックします。
プロジェクト作成のための「新しいプロジェクト」の画面で、プロジェクト名、対応する組織の指定をします（プロジェクト名から自動的にプロジェクトIDが生成されますが、これはGoogle Cloudコンソール上でユニークであるので、よくある名前をプロジェクト名につけた場合には勝手に生成された番号が付加されます）。組織は必ず、Google Workspaceのテナントのものを選択します。[作成]をクリックするとプロジェクトがつくられます。
[APIとサービス]の設定画面に移ります。以下の順序で設定していきます。
- Google Workspaceの対象ツールのAPIのセットをAPIライブラリから選択し、有効にする（有効化されたAPIリストに加える）
- 上記を必要な分だけ繰り返す
- 同意画面を構成する／用いるOAuthスコープを明示的に指定する
- 認証情報の設定（認可サーバーの設定）を行う
- OAuth認可に必要な情報を取得する
まず、[+ APIとサービスを有効にする]や[APIライブラリ]をクリックしAPIライブラリに移動します。
ここでは、このプロジェクトで有効とする、Google内のAPIのセットを指定します。フィルタで「Google Workspace」と入力するなどしてGoogle Workspace関連のAPIのセットを表示させます。
表示されたAPIのセットの中から目的のものをクリックします。例としてここではGoogle Drive APIを選択します。Google Drive APIの個別のページが開きますので、[有効にする]をクリックします。
APIのセットはこのプロジェクトで有効化されました。また異なるAPIのセットも加えて有効化する場合には、APIライブラリに戻って同じ作業を繰り返します。 後ほど、同意画面の構成の作業にて、実際に用いるOAuthスコープを明示的に指定することになり、そのために必要な情報もこのページからドキュメントにアクセスします。 一通り終わったら、左のメニューの[OAuth 同意画面]をクリックし、同意画面の構成作業を開始します。実際に用いるAPIのスコープはこの同意画面の構成の一連で指定します。同意画面の構成が完了がしていない状態で[認証情報]を先に選択しても、先に進めません。
OAuth 同意画面の作成では、まずUser Typeを「内部」で選択します。Okta Workflows API Connectorコネクションにおいては、Google Workspace管理者がリソースオーナーである認可を行うことを想定し、Google Workspace管理者ユーザーで認証するため、ここでは「内部」を選択します。[作成]をクリックします。
同意画面での表示内容の設定です。「アプリ名」は任意のもの、「ユーザーサポートメール」は一覧から選択し、[保存して次へ]をクリックします。
ここでは、先ほどの有効化されたAPIセットの中から、実際に用いるスコープの指定をします。[スコープを追加または削除]をクリックするとポップアップが表示されます。
目的のアクションを想定し、必要なスコープを選択して有効化しますが、その情報についてはAPIリファレンスを参照します。今一度APIライブラリにて、有効化したAPIのセットを表
ページ下部「チュートリアルとドキュメント」の[API Reference]のリンクをたどります。
（日本語訳がまだこなれていないため、ここでは英語表示に切り替えています）
2024年8月時点でAPIのバージョンはVersion 3、Version 2が利用できますが、まずはVersion 3を優先して使用することにします。例えば「ファイルを削除する」というアクションを作る想定である場合に、v3 - files - deleteとたどります。 必要なメソッドは「DELETE」、APIエンドポイントは「https://www.googleapis.com/drive/v3/files/{fileId}」であると確認できます。ここで少なく ともファイルのGoogle Drive上でのユニークIDである「fileId」をまた別途特定しておく必要があることもわかります。 ページ下部にはこのAPI操作に必要なOAuthスコープの情報がまとまっています。
ここでは、表示されている3つのOAuthスコープのうちどれかひとつが必要である、とありますので、スコープ指定画面に戻ってこれに応じたOAuthスコープを選択します。
一通りスコープを選択したら、[更新]をクリックします。
OAuthスコープはGoogle APIでの機密性の設定に応じて分類された形で表示されます。Okta WorkflowsからのAPI Connectorコネクションにおいては、Google Workspace管理者アカウントによる認証の元で行う想定であり、ここでの分類はとくに影響しません。 [保存して次へ]をクリックし次に進みます。
OAuth 同意画面の構成がひととおり完了しました。API Connectionコネクタの生成にはとくに見栄えは関係ないので、このまま[ダッシュボードに戻る]で完了します。 認証情報の設定／認可サーバーの設定を行います。メニューの[認証情報]をクリック、[+認証情報を作成]から[OAuthクライアントID]を選択します。
[アプリケーションの種類]は「ウェブ アプリケーション」を選択、[名前]は任意の文字列、[承認済みのリダイレクトURI]には、Okta WorkflowsのリダイレクトURI（コールバックURL）である以下を入力します。このURLが認可サーバーから発行される認可コードのクライアント（Okta Workflows）側の受信先であり、ここで登録したものと実際の認可プロセスにおけるリダイレクト先とが一致している必要があります。 https://oauth.workflows.okta.com/oauth/httpfunctions/cb （本番Okta org） https://oauth.workflows.oktapreview.com/oauth/httpfunctions/cb （プレビュー/Sandbox Okta org） [作成]をクリックして認証情報の設定を完了します。
完了すると以下のようなポップアップにより、クライアントIDとクライアントシークレットが得られます。また[JSONをダウンロード]からメタデータのファイルがダウンロードできます。
ダウンロードしたメタデータのファイルを開くと、以下のようになります。クライアントID、クライアントシークレットに加えて、クライアント（Okta Workflows）側設定で必要な認可エンドポイント、トークンエンドポイントの情報が格納されています。 では、OAuthクライアントであるOkta Workflowsコンソールに移って、API Connectorのコネクションの設定をします。Connections」タブ上で「+New Connection」をクリック、表示されたダイアログ上で行います。
Name]には任意の名前、[Auth Type]で「OAuth」を選択します。 ダウンロードしたメタデータのファイルをテキストエディタなどで開いて、認可サーバーに関する認可エンドポイントおよびトークンエンドポイントの情報を特定します。それぞれコネクション設定上の「Authorize Patu」「Access Token Path」に相当します。
- [Access Token Path] https://oauth2.googleapis.com/token
- [Authorize Path] https://accounts.google.com/o/oauth2/auth
[Client ID]、[Client Secret]には、先ほどの設定で得たものを入力します。またはメタデータファイルから参照します。
[Scope]では、すでに指定したものをスペースをはさんで列挙します。Google Workspaceにおいては、スコープはそれぞれ完全なURLの形式であることに留意してください。
[Create]をクリックすると、Google Workspaceに対する認証が開始されますので、管理者ユーザーで認証を行います。この認証はOkta WICでのSSOである必要はありません。また、すでに同じブラウザで認証済みであれば認証行為は発生しません。
実際にOAuth 同意画面で指定したスコープに相当する項目の記述があることを確認し、[許可]をクリックします。 これで正しくGoogle Workspace（ここでの例はGoogle Drive API）へのAPI Connectorコネクションが追加されました。このコネクションを実際のフロー作成にてAPI Connectorアクションカードで用い、Google WorkspaceへのAPI操作ができるようになりました。
最後に
前回のAPI Connector全般についての説明に加えて、今回は多くのアプリケーションとの連携に際しての認可の方法であるOAuthによるAPI Connectorコネクションの接続の手順を紹介いたしました。OAuthの設定はアプリケーションによって多様ですが、決まった情報を交換して設定すること、そしてそもそも認可サーバーにあたる設定項目、設定ツールを調べることができれば、とくに問題なくコネクションの設定が完了し、アプリケーションに対するAPI操作をOkta Workflowsを通じて自在にすすめていただけます。
Okta Workflowsシリーズ
- はじめてのOkta Workflowsシリーズ 第１回 Okta Workflowsとは
- はじめてのOkta Workflowsシリーズ 第２回 Hello Workflows編
- はじめてのOkta Workflowsシリーズ 第３回 長期間利用されていないアカウントの洗い出し
- はじめてのOkta Workflowsシリーズ 第４回 日付を指定したユーザーの自動作成と削除
- はじめてのOkta Workflowsシリーズ 第５回 特定の条件に該当するユーザリストの作成とエクスポート
- はじめてのOkta Workflowsシリーズ 第６回 アクションリストにないAPIコマンドの実行
- はじめてのOkta Workflowsシリーズ 第７回 不審なプッシュチャレンジを検出する
- はじめてのOkta Workflowsシリーズ 第8回 アプリケーション連携を広く深く - API Connectorの活用
Follow Hiroki Oikawa 及川大樹
