HTTP統合の作成

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

HTTP統合を作成するには、次の手順を実行します:

  1. マイクロアプリの概要ページから、[開始] または [管理] を選択します。

    マイクロアプリの[統合]ページが開きます。

  2. [統合を追加] を選択します。
  3. [HTTP Webサービスに新しい統合を作成] を選択して、構成の詳細を追加します。

    HTTPタイル

  4. 統合に [名前] を付けて、収集した [ベース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)と置き換えます。

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

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分)を定義できます。ターゲットアプリケーションのドキュメントで定義されている、ベストプラクティスのレート制限をベースにしてレート制限を構成します。

オンプレミスインスタンス(Tech Preview)

マイクロアプリを使用すると、オンプレミスのレコードシステム(SoR)にも接続できます。

オンプレミス接続を作成する場合は、最初に Citrix Cloud Connectorアプライアンスを使用して接続します。

まず、Citrix Cloudにログオンします。

  1. [リソースの場所] タブから [編集または新規追加] を選択します。
  2. 一覧からマイクロアプリリソースを見つけます。
  3. [ID] をクリックします。
  4. リソース識別子IDをマイクロアプリのオンプレミスのリソースの場所にコピーします。 オンプレミス統合が構成されます。

注:

オンプレミス機能の有効化は、現在Technical Previewとしてのみ提供されています。 オンプレミス機能はデフォルトで非表示になっているため、Citrix Cloudの[操作]ダッシュボードで機能名「コネクタアプライアンス」を有効にする必要があります。 この機能を有効にすると、変更は1時間以内に反映されます(Citrix側で有効な機能のキャッシュ)。 オンプレミスでは現在、HTTP統合とJira統合のみがサポートされ、レコードシステム(SoR)との通信ではHTTPSプロトコルのみがサポートされています。

次のステップ

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