マイクロアプリ

HTTP統合の作成

APIを特定したので、HTTP統合をマイクロアプリサービスに追加します。

  1. [マイクロアプリ統合] ページから、[統合の追加] を選択します。
  2. [HTTP Webサービスに新しい統合を作成] を選択して、構成の詳細を追加します。

    HTTPタイル

  3. 統合に [名前] を付けて、収集した [ベースURL] を入力します。ベースURLは、この統合に使用するWebアドレスの一貫した部分です。

    統合ごとにベースURLを1つだけ追加できます。さらにベースURLが必要な場合は、別の統合を作成する必要があります。

注:

HTTPとHTTPSはどちらもベースURLとして許可されていますが、HTTPは安全性の低い接続方法と見なされており、ターゲット統合アプリケーションに使用することはほとんどありません。

次に例を示します:

名前: Asana integration

ベースURL: https://app.asana.com/api/1.0/workspaces/${YOUR_WORKSPACE_ID}

注:

この例では、${YOUR_WORKSPACE_ID}をお使いのワークスペースID(例:419224638481718)と置き換えます。

オンプレミスインスタンス

マイクロアプリサービスを使用すると、オンプレミスのレコードシステム(SoR)に接続できます。オンプレミス接続を作成するには、最初にコネクタアプライアンスを使用して接続し、その後以下の手順に従ってリソース識別子IDを収集して追加します。詳しくは、「Citrix Cloud Connectorアプライアンス」を参照してください。

  1. Citrix Cloudに移動し、資格情報を使用してサインインします。
  2. Citrix Cloudにサインインした後、メニューから [リソースの場所] を選択します。
  3. 追加アイコン [+] を選択して、リストからマイクロアプリリソースを見つけます。
  4. [ID] を選択し、リソース識別子IDを [HTTP統合の追加] 画面の [オンプレミスインスタンスのリソースの場所] フィールドにコピーします。

オンプレミス統合が構成されました。

サービス認証のセットアップ

HTTP統合サービス認証を構成するときに、ターゲットアプリケーションでサービスアカウントをセットアップし、ターゲットアプリケーションの要件に従って必要な資格情報を所有します。ターゲットアプリケーションで必要なすべての情報(ログイン、パスワード、セキュリティ資格情報など)を収集したら、サービス統合プロセスを開始できます。

認証方法を次から選択します:

  • なし - セキュリティ資格情報は必要ありません。
  • Basic - 認証用のターゲットアプリケーションのユーザー名とパスワードを使用します。
  • NTLM - HTTP統合を構成し、一連のMicrosoftプロトコルを使用してNTLM(NT(New Technology)LAN Manager)認証サーバー経由で接続し、Microsoft Windows資格情報を介してNTLMユーザーを認証します。
  • Bearer - ターゲット統合の認証スキームを構成して、ログイン要求への応答としてサーバーが生成したベアラートークンを使用します。
  • OAuth 2.0 - OAuth 2.0セキュリティプロトコルを使用して、委任されたアクセスに関する要求/認証トークンを生成します。OAuth 2.0の実装はシステムによって異なりますが、OAuth 2.0の一般的なワークフローは次のように機能します:
  • APIキー - APIキーの方法を使用して、APIに対してユーザー、開発者、または呼び出し元プログラムを認証します。

注:

利用可能な場合は、サービス認証方法として常にOAuth 2.0を使用することをお勧めします。OAuth 2.0は、統合が、構成済みのマイクロアプリとの最大限のセキュリティコンプライアンスを満たすことを保証します。

次の手順を実行します:

  1. 統合の [サービス認証] パラメーターを入力します。
  2. (オプション)許可の種類が「認証コード」の場合は、[サービスアカウントでログインする] を選択し、ログインが完了するのを待ちます。
  3. (オプション)[サービスアクション認証]をクリックし、サービスアクションレベルで認証パラメーターを入力します。

    重要:

    委任権限を使用している場合、フルアクセスではない可能性があります。この場合は、[サービスアクション認証]を使用してサービスアクションレベルで認証します。この状況では、サービスレベルで基本認証を使用できますが、セキュリティ上の理由から、サービスアクションレベルでOAuth 2.0を使用する必要があります。

  4. [追加] を選択します。

OAuth 2.0認証

OAuth 2.0を使用すると、サードパーティ製アプリケーションでHTTPサービスユーザーアカウントへの特定のアクセス権をアプリケーションで取得できます。これは、ユーザーアカウントを含むサービスに認証を委任することで機能し、その後サードパーティ製アプリケーションにそのユーザーアカウントへのアクセスを許可します。

OAuthのコールバックURL

認証のためのコールバックURLは、次のパターンに従います。

https://{customer_id}.{customer_geo}.iws.cloud.com/admin/api/gwsc/auth/serverContext,
https://{customer_id}.{customer_geo}.iws.cloud.com/app/api/auth/serviceAction/callback

このURLの2行目は、ユーザーごとに認証されたアクションを定義した場合にのみ使用されます。顧客識別子と地理識別子は、各顧客に固有の変数です。

OAuth 2.0の許可の種類

HTTP統合で、3つの許可の種類から選択できます。OAuth 2.0をセットアップするときに、メニューから許可の種類を選択します。OAuth 2.0を構成するときには、認証コードを使用することをお勧めします。これが最も安全な許可フローであるからです。追加のサービスアクション認証方法が必要な場合は、「クライアント資格情報」および「リソース所有者のパスワード」の許可の種類を使用します:

  • 認証コード - クライアントが交換するアクセストークン用の一時コードを付与します。コードは認証サーバーから取得され、そこでクライアントが要求している情報を確認できます。この許可の種類のみが、安全なユーザーの偽装を有効にします。
  • クライアント資格情報 - 許可の種類は、ユーザーのコンテキスト以外でアクセストークンを取得するために使用されます。これは、クライアントがユーザーのリソースにアクセスするのではなく、クライアントのリソースにアクセスするために使用されます。
  • リソース所有者のパスワード - リソースサーバーによるアクセストークンのプロビジョニングを承認するために、正しい資格情報を提供します。

許可の種類の入力

上記で定義した許可の種類に応じて以下のオプションが提供されるので、これらを完了してOAuth 2.0認証を有効にします:

  • トークンURL - アクセス承認トークンのURLを定義します。
  • スコープ - アクセス要求のスコープを定義します。これは、ターゲット統合アプリケーションをセットアップするときに、承認サーバーによって定義される文字列です。
  • クライアントID - 承認サーバーに固有のクライアント登録情報を表す文字列を定義します。
  • クライアントシークレット - ターゲットアプリケーション統合のセットアップ時に発行される一意の文字列を定義します。
  • ユーザー名 - ターゲットアプリケーションのアカウントのユーザー名を定義します。
  • パスワード - ターゲットアプリケーションのアカウントのパスワードを定義します。
  • 認証URL - ターゲットアプリケーション統合をセットアップするときに提供される承認サーバーのURLを定義します。
  • アクセストークンパラメーター - 必要に応じて、ターゲットアプリケーション承認サーバーによる要求に従ってアクセストークンパラメーターを定義します。
  • サービスアカウントでのログイン - ターゲットアプリケーションの承認サーバーのサービスアカウントにログインします。
  • ヘッダープレフィックス - (オプション)ベアラープレフィックスがデフォルトのヘッダーと異なる場合、ヘッダープレフィックスを入力します。

OAuth 2.0に関する追加リソースは、OAuth 2.0の「質問をする」ページにあります。

OAuth 2.0のトラブルシューティング

ターゲットアプリケーションをマイクロアプリプラットフォームに接続する際に問題が発生した場合は、以下のような考えられる解決策エラーを自身の構成で確認してください:

  • invalid_request - 承認要求で、必須パラメーターが欠落している、サポートされていないパラメーター値(またはその他の許可の種類)が含まれる、パラメーターを繰り返す、複数の資格情報が含まれる、クライアントを認証するために複数のメカニズムを利用している、といった可能性があります。
  • invalid_client - クライアント認証が以下の理由で失敗しました:不明なクライアント、クライアント認証が含まれていない、またはサポートされていない認証方法。承認サーバーは、HTTP 401(Unauthorized)ステータスコードを返し、どのHTTP認証スキームがサポートされているかを示します。
  • invalid_grant - 承認の許可または更新トークンが無効、期限切れ、取り消し済み、別のクライアントに発行された承認要求で使用されたリダイレクトURIと一致しない、といった可能性があります。
  • unauthorized_client - 認証されたクライアントが、この承認の許可の種類の使用を承認されていません。
  • unsupported_grant_type - この承認の許可の種類は、承認サーバーがサポートしていません。
  • invalid_scope - 要求されたスコープが無効、不明、不正な形式であるか、リソース所有者によって許可されたスコープを超えています。

これらを確認してもまだOAuth 2.0の設定に問題がある場合、トークンのURLと認証URLは両方とも一意であるため、正しく入力したかどうかを確認します。また、スコープなどのその他の入力が正しいことを再確認します。問題が解決しない場合は、統合アプリケーションサーバー側の設定を確認します。

要求レート制限(オプション)

統合のレート制限を有効にするには、[Request rate limiting] を選択します。オンにすると、ターゲットアプリケーションから抽出される要求の数と時間間隔(1秒または1分)を定義できます。ターゲットアプリケーションのドキュメントで定義されている、ベストプラクティスのレート制限をベースにしてレート制限を構成します。

Webhookリスナー

マイクロアプリでほぼリアルタイムのデータをエンドユーザーに提供できるように、Webhookリスナー(HTTPプッシュAPIとも呼ばれる)を構成します。Webhookを構成して、マイクロアプリプラットフォーム側からの同期よりもはるかに速い速度で、アプリから他のアプリケーションにデータを配信できます。Webhookリスナーを追加するには、ターゲットアプリケーションのレコードシステムを熟知し、それらの場所でWebhookを構成するために必要なツールと管理者権限が設定されている必要があります。

データ読み込みにより統合を設定した後、Webhookを構成し、次の手順に従います:

  1. HTTP統合画面の左側のバーにある [Webhookリスナー] をクリックします:

    Webhookリスナー

  2. 必要なWebhook名を入力します。
  3. [コピー] を選択して、ターゲットのレコードシステム管理インターフェイスで使用するWebhook URLをコピーします。

承認方法

承認方法を構成する際、[トークン] 認証方法か [なし] のいずれかを選択できます。トークンの方法を構成するには、次の手順に従います:

  1. 認証方法のメニューで [トークン] を選択します。
  2. [トークンの生成] を選択してから [コピー] を選択し、ターゲットのレコードシステム管理インターフェイスで使用するためにトークンをクリップボードに追加します。
  3. [トークンの読み取り元] を選択して、次から選択します:
    • カスタムヘッダー
    • クエリパラメーター
    • 認証ヘッダー
  4. 選択した読み取り方法に応じて、[名前] または [プレフィックス] を定義します。

これでトークンが設定されました。

データ構造の定義

データ構造は、データ読み込み構成中のデータ構造の取得で説明したのと同様の方法で定義できます。詳しくは、統合の構成を参照してください。

Webhookデータ構造を定義するには、次の手順に従います:

  1. 必要なデータ保持期間を設定します。
  2. [テーブルの生成] を選択します。

    [テーブルの生成] 画面が開きます。

    ターゲットアプリケーションのレコードシステムからのJSONサンプルリクエストをここに貼り付けます。

  3. 作成したテーブルのベース名を設定します。
  4. (オプション)必要に応じてルートパスを設定します。
  5. [生成] を選択します。

このプロセスが、ターゲットアプリケーションのレコードシステム管理で入力した構成手段と共に完了したら、[追加] を選択します。

これでWebhookが構成されました。

次のステップ

HTTP統合を作成したので、この統合を構成します:

HTTP統合の作成