はじめてのOkta Workflowsシリーズ 第6回 アクションリストにないAPIコマンドの実行

今回のブログでは、Oktaに対してAPIコマンドを実行したいが、まだOktaコネクターのアクションカードにリストされていない(プレビルドされていない)コマンドを利用するためのフローを解説します。

Oktaコネクターにリストされている便利なアクションは、こちらに記載のCore Okta API “Manage Okta Objects” (いわゆるOkta管理用のAPI)を利用しています。Oktaの管理コンソールで行う操作をAPIで実行できるというものです。よく使用されるコマンドは、随時こちらのアクションカードとしてプレビルドのコマンドテンプレートが追加されるため、少ない入力項目だけで簡単にコマンド実行することが可能です。

ただし、全てのコマンドがアクションカードとしてプレビルドされているわけではないので、そういったカード化されていないコマンドを実行する場合にはAPIコマンドの仕様を確認して自ら組み立てる必要があります。

本ブログでは、プレビルドされていないOktaのAPIコマンド”Reactivate User”を、リファレンスの情報をもとにOkta Workflows上で組み立て実行するフローの実装概要を解説します。

Reactivate Userは、ユーザーを新規登録した際にActivationメール送信後7日過ぎても有効化しなかった者に対してメール再送信などで再度有効化を促すといったケースで用いられます。実利用の際はエラーハンドリングなどが必要になりますが、ここでは本質的な処理に絞って実装を解説します。

フローの実装概要

APIリファレンスをもとにURLやHeaderを定義してReactivateコマンドを作成し、処理対象のユーザーのIDを使って実際に実行する流れとなります。

フロー全体

(1) APIリファレンスの確認

まず、該当コマンド”Reactivate User”を探します。左右に表示されるペインを頼りに、

Core Okta API → Manage Okta Objects → Users → Lifecycle operations → Reactivate Userと移動します。

https://developer.okta.com/docs/reference/api/users/#reactivate-user

こちらにはコマンドの概要や動作条件、必須パラメータの情報の記載があります。

Request parameters (必須パラメータ)の情報より、このコマンド実行には対象ユーザーのIDとメール送信の有無を入力する必要があることがわかります。

Response parameters (戻り値)の情報より、メール送信をfalseとした場合にはActivation用のリンクが返ってくることがわかります。こちらは手動で対象ユーザーに伝える形となります。

更に、実際のRequestのサンプルも掲載されているため、こちらをもとにHeaderとURLを作成することとなります。

-HがHeader部分であり、AcceptとContent-Typeを次のステップで実際に作成します。

AuthorizationにあるSSWSは、API tokensを用いたAPI実行手順ですのでPostmanなどを使った検証などにはこちらを利用します。今回のようにOkta Workflowsで既に接続済みのOktaコネクターを使う場合には考慮不要です。

(Okta WorkflowsのOktaコネクターは、第3回や第4回で述べられている通り、Bearer - OpenID Connect/OAuth2.0を利用しています。)

(2) コマンド作成

(1)で把握した情報をもとにAPIコマンドを作成します。

Step 1：URLの作成

(1)のRequest exampleをもとに、コマンドURLを記載します。このURLは後のStep3にて使用しますが、そのOktaコネクターでは既に接続済みのコネクションを使用するため、httpsやOktaDomainの入力は不要となります。

対象ユーザーを識別するuserId部分は後ほどまた編集します。

この例ではメール送付をする(true)オプションとしています。

利用カード： TextのCompose

Step 2：ヘッダーの作成

(1)のRequest exampleをもとに、AcceptとContent-Typeを作成し、それぞれにapplication/jsonを入力します。

利用カード： ObjectのConstruct

Step 3: 実コマンドのカード作成

OktaコネクターのCustom API Actionを選択し、OptionにPOSTを指定します。

こちらがOktaに対するカスタムのAPIコマンド実行カードとなります。

Relative URL部分にStep1のoutputを、Headers部分にStep2のoutputをドラッグ&ドロップします。

利用カード： OktaのCustom API Action

(3) ユーザー情報の取得と連携

対象のユーザー名を入力すると、そのUserIdを抽出して先のコマンドURLへ連携します。

あくまで今回はサンプルのためこのように対象ユーザーを直接入力していますが、実際のユースケースとしては、この部分は第5回で紹介したような特定の条件に合致したユーザーリストを使用する形が多いかと思います。

Step 1：ユーザー名の入力

簡単に試験対象ユーザーを切り替えられるように、Textにてユーザー名を入力する項目を別途用意します。userIdを最初から把握している状況であればこのStepは省略できます。

利用カード： TextのCompose

Step 2：userIdの取得

ユーザー名から対象ユーザーの詳細情報を取得し、userIdを次のカードへ渡せるようにOutputとします。

利用カード： OktaのRead User

Step 3：コマンドURLのuserIdを補完

先の(2)で使用したコマンドURLの変数であるuserIdを、取得したuserIdに置き換えるため、Read UserカードのOutput: userIdをドラッグ&ドロップします。

利用カード： (2)で作成したTextのCompose

(4) フローの実行と結果の確認

作成したフローを実行し、成功すると200 responseが返ってきます。

ユーザーのメールアドレスに対しては、以下の様なActivationのメールが送られてきています。

サンプル・フローのダウンロード

今回解説したフローは、こちらからFlow Packファイルとしてダウンロードし、Okta Workflowsにインポートすることで試すことができます。ただし、あくまでサンプルですので、動作の保証をするものではなく、フロー全体としての動作やロジックはサポート対象にはなりませんのでご了承ください。

最後に

Okta Workflowsを使うことで、アクションカード化されていないOktaのAPIコマンドでも簡単に実装できることを実感いただけたでしょうか。今回の実装例では、出来るだけ分かりやすくお伝えするためにユーザー名は手打ちとしていますが、前回ご紹介したユーザリスト化するフローと組み合わせれば、Activateしていないユーザーだけを抽出して彼らにReactivateを実行することもできます。

また、まだOktaがコネクター化していないアプリも、同様にアプリ側のAPIリファレンスを参考にOkta Workflowsから容易にコマンド実行することが可能なため、是非お試しください。