はじめてのOkta Workforce Identity Cloud (WIC) [第6回] APIってどうやって使うの？ (トークン編)
目次
本ブログ記事では、Okta Workforce Identity Cloud (以降、Okta WIC) でのAPIの使い方について解説します。
APIとは、Application Programming Interfaceの略称です。
APIを使うことで、外部のアプリケーションからOkta WICを設定したり削除したり、Okta WICの情報を参照したりすることができます。
「Okta Admin Consoleでできる」ことが、「APIでもできる」ということです。
厳密には、Okta Admin ConsoleとAPIで「どちらかではできないけど、どちらかではできる」という多少の機能差はありますが、だいたい同じことができます。
PostmanというAPIクライアントソフトを使うことで、APIを利用するアプリケーションを作らずとも、APIの動作確認を行うことができますので、本ブログ記事では、このPostmanを利用したいと思います。
APIの利用方法は大きく2つあります。
(1) Okta WICから発行したトークンを使う。
(2) OAuth 2.0 を使う。
本ブログ記事では、比較的簡単な(1)のトークンを使ったAPIの利用方法について、解説します。
以降の解説は、以下のブログ記事の内容を実施済み (理解済み) の前提で進めていきます。
・はじめてのOkta Workforce Identity Cloud (WIC) トライアル環境の構築
・はじめてのOkta Workforce Identity Cloud (WIC) [第1回] ユーザーと認証器の関係を紐解く
・はじめてのOkta Workforce Identity Cloud (WIC) [第2回] 多要素認証を紐解く
APIトークンの設定
APIトークン発行までの設定の流れを解説します。
送信元IPアドレスを制限する
APIはOkta WICの管理者の操作ができるので、攻撃の対象になりやすいです。
APIトークンを使ったAPI操作には、主に攻撃から防御する目的で、送信元IPアドレスを制限する機能がありますので、是非とも設定しておくことを推奨します。
(2024年8月に、この機能が全てのOrgで使えるようになりました。ちなみに左記のURLに「SSWS API Tokens」との記載がありますが、SSWSは「Single Sign-On Web System」の略です。)
「セキュリティ」→「ネットワーク」→「ゾーンを追加」で「IPゾーン」を選択します。
本ブログ記事では、「現在Okta WICのAdmin Consoleを操作しているパソコンからのみ、APIを発行する」という前提で、「自身のパソコンのIPアドレスだけ許可する」という設定にしようと思います。
表示された画面で、「ゾーン名」を指定し、「ゲートウェイIP」では「現在のIPアドレスを追加」の横に表示されたご自身の端末のグローバルIPアドレスをクリックし、「保存」をクリックします。
APIトークンを生成する
では、APIトークンを生成してみましょう。
「セキュリティ」→「API」→「トークン」タブで、「トークンの作成」をクリックします。
表示された画面の上段のフォームには、任意のトークン名 (ここでは「API_Token_001」としました) を設定し、下段では「次のゾーン内:」を選んで、先ほど作成したIPゾーンを選択して、「トークンの作成」をクリックします。
トークン値が表示されますので、右端のアイコンをクリックしてトークンをコピーし、安全な場所に一時的に保存しておいてください。
※この画面を閉じると、このトークン値は二度と表示されません。
コピーし損ねた場合には、このトークンは一旦削除して、もう一度上記の手順を繰り返してください。
「OK, got it」をクリックします。
APIトークンの作成は以上です。簡単ですね。
Postmanを設定する
Okta WICのAPI動作を確認するために、APIクライアントとなるPostmanを設定しましょう。
まずは下記LinkからPostmanをダウンロードしてインストールしてください。
https://www.postman.com/downloads/
以降、Windowsの場合を例に取ります。
インストールしたPostmanアプリの左上にある3本線のアイコンをクリック→「File」→「Import」を選択します。
現れた画面で、下記Linkをそのままコピーし、フォームにペーストしてください。
https://developer.okta.com/docs/api/postman/example.oktapreview.com.environment
右上の「No Environment」と書かれた部分をドロップダウンして表示された「{yourOktaDomain}」を選択します。
(先ほどのImportによって、この「{yourOktaDomain}」が追加されたのです。)
右上の四角いアイコンをクリックして表示された画面で、「Edit」をクリックします。
下記3箇所の「Initial value」と「Current value」の両方に同じ値を入れて、「Save」をクリックしてください。
(1)url ←Okta WICのURLです。「-admin」は削除した状態のURLを設定してください。
(2)apikey ←Okta WICで生成したAPIトークンです。
(3)userId ←すでに存在するユーザー名を一つ指定してください(必須ではありません)。
(1)と(2)は必須ですが、(3)は後の動作確認に使うだけなので、必須ではありません。
本ブログ記事のOkta WIC環境では「[email protected]」が登録済みですので、(3)にはそのユーザーを指定しました。
次にChrome等のWebブラウザを開いて、下記Linkにアクセスしてください。
Import a Postman Collectionhttps://developer.okta.com/docs/reference/postman-collections/
このサイトから、PostmanでテストしてみたいOkta WICのAPI群を一括でインポートできます。
本ブログ記事では、「Groups」と「Users」だけインポートしようと思います。
Web画面をスクロールダウンして、「Groups」を見つけて「Run in Postman」をクリックします。
「Postman for Windows」をクリックします。
「Users」も見つけて、「Groups」と同様の操作を行ってください。
Postmanを操作する
では、実際にAPIを使って、Okta WICから情報を取得してみましょう。
Postmanアプリの左側にある「Collections」をクリックすると、「Groups (Okta API)」と「Users (Okta API)」というメニューが表示されるはずです。
まずは「Users (Okta API)」の下の「Get User」を選択して、右上の「Send」をクリックしてみましょう。
本ブログ記事のOkta WIC環境/Postmanの設定では「[email protected]」に関わる情報がAPIによって取得できていることが分かります。
上段の「GET」の右に書かれた文字列の「{{url}}」や「{{userId}}」には、先ほどPostmanのInitial value/Current valueに指定した値が自動的に入るようになっています。
次に「Groups (Okta API)」の下の「List Groups」を選択して、右上の「Send」をクリックしてみましょう。
少なくとも、Okta WIC上にデフォルトで存在する「Everyone」グループは取得できるはずです。
その他のAPI操作を行いたい場合には、Import a Postman Collectionのサイトから必要なものを選んでPostmanに追加し、同様の操作をするだけです。
APIの基本的な設定及び操作は以上です。
API操作権限の絞り込み
ここまででご紹介したAPIの設定では、スーパー管理者がOkta Admin Consoleから実施できることは、APIからでもほぼ同じことができる、という状態です。
それはそれで便利ではあるのですが、ほぼなんでもできてしまう状態は危険とも言えますので、API操作可能な範囲は、必要最低限に留めるべきです。
よって、以降、APIで操作できる権限を絞り込む方法をお伝えします。
(以降の内容はこちら↓のLinkにも記載されています。)
https://support.okta.com/help/s/article/How-To-Create-an-API-Token-With-Custom-Permissions
絞り込まれた権限の設定
まずは管理者が実施できる範囲を限定する設定を行います。
本ブログ記事では、「ユーザー情報が参照できるだけ」というような権限に設定してみようと思います。
「セキュリティ」→「管理者」→「ロール」タブで「新しいロールを作成」をクリックします。
任意のロール名 (ここでは「view_users」としました) を指定し、「ユーザーとその詳細情報を表示」だけを選択して、「ロールを保存」をクリックします。
「リソース」タブで「新しいリソースセットを作成」をクリックします。
任意の名前 (ここでは「user_resource」としました) を指定し、「リソース」の下の「＋リソースを追加」をクリックします。
リソースタイプには「ユーザー」を選択し、次の画面で「すべてのユーザー」を選択して「選択を保存」をクリックします。
「作成」をクリックします。
絞り込まれた権限をユーザーに割り当て
API操作の絞り込みを行うためには、ユーザーが最低1つ必要です。
本ブログ記事では「[email protected]」というユーザーを新たに生成して、そのユーザーに対して絞り込んだAPI権限を割り当てることにします。
「ディレクトリ」→「ユーザー」で「[email protected]」を選択し、「管理者ロール」タブで「個人の管理者権限を追加」をクリックします。
ロールには、先ほど設定した「view_users」を、リソースセットには、先ほど設定した「users_resource」を選択します。
更に、「割り当てを追加」をクリックして、ロールには「スーパー管理者」を割り当てます。
※この「スーパー管理者」ロールは一時的な割り当てであり、APIトークンを発行した後に削除します。
そして「変更を保存」をクリックします。
管理者設定を変更したので、このあと、Okta Admin Concoleの現在のスーパー管理者 (＝zsaku.zkawaではないスーパー管理者) での再認証が強制的に行われます。
一時的なスーパー管理者ユーザーでAPIトークンを発行
現在のスーパー管理者は、一旦ログアウトしてください。
そして、一時的なスーパー管理者である「[email protected]」でログインし直してください。
「セキュリティ」→「API」→「トークン」タブで、「トークンの生成」をクリックします。
表示された画面の上段のフォームには、任意のトークンの名前 (ここでは「API_Token_ZZ」としました) を設定し、下段では「次のゾーン内:」を選んで、先ほど作成したIPゾーンを選択して、「トークンの作成」をクリックします。
トークン値が表示されますので、右端のアイコンをクリックしてトークンをコピーし、安全な場所に一時的に保存しておいてください。
「OK, got it」をクリックします。
以下は、新しいAPIトークンが生成された状態です。
一時的なスーパー管理者の権限を削除
トークンが発行できたら、一時的なスーパー管理者の権限は用済みなので削除します。
「[email protected]」はログアウトしてください。
そして、もう一度、元のスーパー管理者でログインし直してください。
ロールで「Super Administrator」が選択されている行の右端のゴミ箱のアイコンをクリックします。
「変更を保存」をクリックします。
「削除」をクリックします。
管理者設定を変更したので、このあと、Okta Admin Concoleの現在のスーパー管理者 (＝zsaku.zkawaではないスーパー管理者) での再認証が強制的に行われます。
これで、「[email protected]」は、以下のようにスーパー管理者の権限が削除された状態になります。
絞り込まれた権限のAPIトークンでの動作確認
では、API操作の権限が絞り込まれているか確認しましょう。
「[email protected]」で発行したAPIトークンを、Postmanの「apikey」変数に設定して「Save」します。
まずは、左側にある「Collections」をクリックして表示された「Users (Okta API)」の下の「Get User」を選択して、右上の「Send」をクリックしてみましょう。
このAPI操作はユーザー情報の参照なので、権限が付与されてますから、以前に確認した内容と同じ結果が得られるはずです。
今度は「Groups (Okta API)」の下の「List Groups」を選択して、右上の「Send」をクリックしてみましょう。
現在のAPIトークンにはグループを参照する権限を付与していないので、このAPI操作では情報を得ることができないはずです。
API権限の絞り込み設定及び操作は以上です。
まとめ
本ブログ記事では、APIトークンを使った場合のOkta WIC APIの使い方についてご紹介しました。
APIを使うことで、管理GUIを操作することなく、プログラムから自動的にOkta WICの設定や情報の参照が可能になりますので、もしルーチンワークのような手作業のユーザー登録や参照の業務が存在するようなら、皆様のプログラムからこのAPI操作を行うことで、その業務を自動化することが可能になります。
APIでは様々な操作ができて便利な反面、広く公開してしまうと攻撃の対象となってしまうため、送信元IPアドレスの絞り込みはもちろんのこと、API操作の権限は、必要最低限なものだけに絞り込むように設定することを推奨します。
また、Okta WICでは、認証の強化だけでなく、管理者が行うユーザーの登録/変更/削除に関わる業務の自動化や、人事管理システムや既設ディレクトリなどとの柔軟な連携も可能です。
Oktaでは、これらの機能を体感頂くことができる「Okta Essentials」トレーニングをご用意しています。(日本語でのトレーニングもご用意しています。)
このトレーニングは全体像を体系的にご理解頂ける内容となっていますので、是非ともご活用ください。
Follow 岸本 卓也
