カスタムアプリケーションの統合
REST API/SOAP API対応のアプリケーションをご利用の場合、ADManager Plusと統合してアプリケーション内のIDを管理できます。ADManager Plusには各種アプリケーションとの接続がデフォルトで実装されています。統合したいアプリケーションが実装リストに含まれていない場合は、以下の手順に沿って対象のアプリケーションとADManager Plusを統合してください。
ADManage PlusでのAPIエンドポイントの設定には以下の２種類があります。
- Inbound Webhook
- Outbound Webhook
各ユーザーの企業の目的に応じて、どちらか一方あるいは両方を設定することができます。
認証設定が完了した後、APIエンドポイントを設定します。
- 認証設定
- Inbound webhookの設定
- Outbound webhookの設定
認証設定
- ［自動化］に移動し、［設定］→［アプリケーション統合］をクリックします。
- 「エンタープライズアプリケーション」セクションで、［カスタムアプリケーション］タイルをクリックします。
- ポップアップ表示された「カスタムアプリケーション構成」ウィンドウで、適当な「名前」と「説明」を入力し、アプリケーションのロゴをアップロードします。
- ［保存］をクリックします。
- 「承認」セクションで「認証の種類」ドロップダウンから適切なオプションを選択し、API認証方法の設定を行います。
- ［認証がありません］
使用するリクエストに認証が不要な場合は［認証がありません］を選択します。このオプションを選択した場合、認証情報はAPIクライアントに共有されません。 - ［APIキー］
選択した場合は、「鍵」と「値」のフィールドにAPIキーの名前と値をそれぞれ入力します。［ヘッダー］または［クエリパラメーター］を選択してAPIキーと関連付け、［設定する］をクリックします。詳細については、対象アプリケーションのAPIドキュメントを参照してください。 - ［基本認証］
選択した場合は、「ユーザー名」と「パスワード」を指定して、［設定する］をクリックします。 - ［保有者］
選択した場合は、対象アプリケーションのAPIキーを「トークン」フィールドに入力して、［設定する］をクリックします。APIキーは、対象アプリケーションのAPIドキュメントに記載されている手順に従って取得してください。 - ［OAuth 2.0］
選択した場合は、以下の項目を指定します。- 「ヘッダプレフィックス」
認証ヘッダーのプレフィックス値を指定します。 - 「付与の種類」
デフォルトは［認証コード］です。対象アプリケーションに応じて［クライアント認証情報］も選択できます。 - 「コールバックURL」
コールバックURLは認証後のリダイレクト先です。。リストにあるアプリケーションに対しては、ADManager Plusの URLが事前入力されていますが、新規アプリケーションを統合する場合は、APIプロバイダーのOAuthを設定する際に指定してください。 - 「認証URL」
OAuth設定時に、統合するアプリケーションから取得した認証エンドポイントを入力します。 - 「アクセストークンURL」
対象アプリケーションがアクセストークン用に認証コードを交換できるOAuthサーバーのURLを入力します。 - 「クライアントID」
対象アプリケーションから取得した有効なIDを入力します。 - 「クライアントシークレット」
対象アプリケーションから取得した秘密鍵を入力します。 - 「スコープ」
スコープの定義により、クライアントアクセスを特定のエンドポイントに限定し、クライアントがそのエンドポイントに対して読み込みのみ可能か、または書き込みも可能かを定めます。APIドキュメント上でスコープ値を参照してからADManager Plusのスコープ値を指定します。 - 「クライアント認証」
クライアント認証情報をリクエスト本文またはヘッダーのどちらに包含するかを選択できます。デフォルトでは、［リクエスト本文でクライアント認証情報を送信する］が選択されています。 - ［アドレスオプション］
クリックすると、「追加」ドロップダウンから［ヘッダー］か［クエリパラメーター］を選択できます。
- 「ヘッダプレフィックス」
- ［認証がありません］
ADManager Plusは上記で指定した認証URLに対して、クライアントID/クライアントシークレット付の認証リクエストを送信します。応答として認証サーバーが発行した認証コードを、リフレッシュトークンおよびアクセストークンと交換します。 次にアクセストークンを使用してAPIコール（POSTリクエスト）が行われ、ユーザーは指定したコールバックURLにリダイレクトされます。
Inbound Webhookの設定（内部アプリでのユーザー変更の構成）
本設定によりカスタムアプリケーションからADManager Plusへのデータ転送が可能になります。
設定手順
- ［（アプリケーション名）エンドポイント構成］→［＋APIエンドポイントを追加］をクリックします。［APIエンドポイント構成１］をクリックして展開します。必要に応じて、さらに［＋APIエンドポイントを追加］をクリックして、複数のエンドポイントを設定することもできます。入力する各フィールドの内容は以下のとおりです。
- 「エンドポイントURL」
エンドポイントのURLを入力します。エンドポイントURLは、実行したい操作や、アプリケーションから取得したいデータタイプに応じて異なります。- 例：ユーザーデータを取得するためのエンドポイントURLは、グループデータを取得するためのURLと異なります（詳細は、対象アプリケーションのAPIドキュメントを参照してください）。
- 「方法」
HTTPリクエストメソッドとして「取得」または「送信」のどちらかを選択します。 - 「ヘッダー」
［ここをクリック］をクリックして各HTTPヘッダーを設定します。 - 「パラメーター」
［ここをクリック］をクリックしてクエリパラメーターを設定します。 - 「メッセージタイプ」
メッセージ本文のデータタイプを、表示されているオプションからAPIタイプに基づいて選択します。- JSON ー REST API
- XMLー SOAP API
- なし ーデフォルト
- 「エンドポイントURL」
- ［Settings］タブに移動して、「このエンドポイントの呼出を繰り返す」ボタンを有効にすると、必要なデータをすべて取得するまでAPIは繰り返し呼び出されます。
- 「呼出構成を繰り返す」の項目で、一番目のドロップダウンリストからアクションのタイプを選択します。
- 二番目のドロップダウンに、ページネーションのパラメーターを指定します。この設定により、すべてのデータを取得するまで指定した順番通りにデータが収集されます。
- ページネーションのパラメーター値を「value」のボックスに入力します。
- 「呼出基準を繰り返す」の項目で、APIを呼び出し続ける時間の長さを指定することもできます。
- 設定完了後、［テストと保存］をクリックします。 表示される「応答」ウィンドウに要求したすべてのエレメントが記載されています。
- ［データソース - LDAP 属性のマッピング］をクリックし、以下の手順でカスタムアプリケーションの各属性にActive Directory LDAP属性をマッピングします。
- 「設定名」と「説明」を入力し、「自動化のカテゴリー」をドロップダウンから選択します。
- 「エンドポイントを選択」フィールドで、カスタムアプリケーションのエンドポイントボックスにチェックを入れ、「Primary Key」のドロップダウンからユーザーに対して一意の属性（employeeIdenifier、 usernameなど）を選択し、かつ、すべてのエンドポイントが同じ値を保持するように設定します。
- 「属性マッピング」のフィールドで、「LDAP属性名」ドロップダウンから属性を選択し、カスタムアプリケーションの各属性にマッピングします。
- ［保存］をクリックします。
Inbound Webhookの使い方
「内部アプリでのユーザー変更（Inbound Webhook）」セクションを設定した後、［自動化］タブ→［自動化］→［＋新しい自動化を作成する］→「オブジェクトの選択」→「オプションを表示する」から、設定したInbound Webhookを新しいデータソースとして選択し、ADManager PlusからID管理アクションを実行することができます。この設定により、Inbound Webhook経由でインポートされたオブジェクトに対して実行したいアクションが自動化されます。実行回数については、一回限りを指定、または、定期的な実行スケジュールを指定できます。
Inbound Webhookにネストしているエンドポイントの高度な設定
API設定では、依存関係にある複数のエンドポイントを設定する場合があります。例えば、最初のエンドポイントが組織内のすべての従業員IDを取得した後、取得した各従業員IDに対して別のAPIを叩き、従業員の詳細を取得する場合があります。このようなケースでは、「高度」オプションを使用して、1番目のAPIをベースエンドポイント（デフォルトタイプ）、2番目のエンドポイントを依存エンドポイントとして設定します。
依存エンドポイントを設定する手順
「APIエンドポイント構成」配下の「高度」ボタンを有効にしてから、対象エンドポイントが前のAPIエンドポイントに依存する際に必要となる情報を入力していきます。
- 「構成タイプ」のドロップダウンメニューから、エンドポイントタイプを選択します。デフォルトでは［ベースエンドポイント］が選択されているため、［依存エンドポイント］に変更してください。
- 「Depends On」のドロップダウンメニューで表示されているオプションから、現在のエンドポイントが依存しているベースエンドポイントを選択します。その結果、現在のエンドポイントは、ベースポイントからから受信した各オブジェクトに対して呼び出されます。
- ベースエンドポイントのレスポンスからフィールドを利用するには、%記号を入力するか、［%］ををクリックしてリスト表示されたベースエンドポイントのマクロを使用するかします。
SOAP APIエンドポイントを設定する手順
「Inbound Webhookの設定」セクションで説明したすべての手順を実行します。メッセージタイプがXMLに設定されている場合、ADManager PlusではレスポンスパーサーCSVファイルを使用して、エンドポイントのXMLレスポンスから必要なデータのみをフィルタリングします。フィルタリングされた属性は、Active Directry LDAP属性に連携できます。CSVには以下の3つのカラムが必要です。
- columnNam：XMLレスポンスからフィルタリングされるデータの名前です
- xPath：データを取得する場所です。
- isParameter：1に設定すると、繰り返し呼び出される際に反復属性になります。
メッセージ本文内のPageという名前のノードを、呼び出しのたびに1ずつ増加させる必要がある場合、PageのisParameterを1に設定します。以下の画像に示すように、サンプルのCSVファイルでハイライトされた列名Worker IDの値は、サンプルのXMLレスポンスファイルでハイライトされている属性Worker_ID(value:100001)から抽出されます。この値は、後でActive Directry LDAP属性の従業員IDにマッピングすることができます。
サンプルCSVファイル
サンプルXMLレスポンス
Outbound Webhookの設定
本設定により、AD上で変更があった場合に、ADManager Plusからカスタムアプリケーションへのデータ送信が可能になります。Outbound Webhookの設定手順は以下の通りです。
- 「Outbound Webhook」配下で、［（アプリケーション名）Webhook構成］をクリックします。
- ［+Webhookを追加］をクリックします。
- 作成するWebhookのタイトルと［説明］を入力します。
- カスタムアプリケーションのAPIリファレンスを参照して、実行するアクション、ヘッダー、パラメーターおよび必要となる他の要件を決定します。
- エンドポイントで実行したいアクションに適したHTTPメソッドをドロップダウンから選択します。
- エンドポイントURLを入力します。このURLは、アプリケーションに転送するデータによって異なります。 例えば、ユーザー属性を更新するためのエンドポイントURLは、最近変更されたユーザーパスワードの更新に使用されるエンドポイントURLとは異なります。 ADManager Plusと統合するアプリケーションのAPIドキュメントを参照してください。
- 「ヘッダー」「パラメーター」「メッセージタイプ」を、実行したいAPIコールに基づいて適切なフォーマットで設定します。
- ［テストと保存］をクリックします。ポップアップウィンドウにユーザーとグループのリストが表示されます。
- このAPIリクエストをテストするユーザーとグループを選択して［OK］をクリックします。エンドポイントURLがリアルタイムで呼び出され、選択したオブジェクトの値が更新されます。
- ポップアップウィンドウにWebhookレスポンスとリクエストの内容が表示されます。
マクロ対応属性の使い方
- エンドポイント「URL」「ヘッダー」「パラメーター」フィールドに%記号をタイプするか、［%］をクリックして使用したいマクロを追加するかします。
- メッセージ本文にマクロを追加する必要がある場合は、「メッセージタイプ」フィールドの右下にある［マクロの選択］をクリックします。
Outbound webhookの使い方
要件に合わせてOutbound Webhookを設定した後、オーケストレーションテンプレートのブロックとして使用します。設定したオーケストレーションテンプレートは、イベントドリブンオートメーションを使用して実行できます。また、対象ユーザーに直接適用して、適用したユーザーに対して一連のアクションを実行することも可能です（［AD管理］ →［カスタム管理］→［オーケストレーション］）。