HTTP統合の作成
APIを特定したので、HTTP統合をマイクロアプリサービスに追加します。
- ［マイクロアプリ統合］ ページから、［統合の追加］ を選択します。
-
［HTTP Webサービスに新しい統合を作成］ を選択して、構成の詳細を追加します。
-
統合に ［名前］ を付けて、収集した ［ベースURL］ を入力します。ベースURLは、この統合に使用するWebアドレスの一貫した部分です。たとえば、
https://app.asana.com/api/1.0/workspaces/${YOUR_WORKSPACE_ID}です。${YOUR_WORKSPACE_ID}をお使いのワークスペースID（例：419224638481718）と置き換えます。統合ごとにベースURLを1つだけ追加できます。さらにベースURLが必要な場合は、別の統合を作成する必要があります。
注：
HTTPとHTTPSはどちらもSaaS統合のベースURLとして許可されていますが、HTTPは安全性の低い接続方法と見なされており、ターゲット統合アプリケーションに使用することはほとんどありません。オンプレミス統合では、HTTPのベースURLは許可されません。
- 統合で表示するアイコン を選択します。事前定義されたアイコンのセットから1つを選択するか、カスタムアイコンを追加します。カスタムアイコンの追加について詳しくは、「カスタムアイコンの追加」を参照してください。
- （オプション）オンプレミスのレコードシステム（SoR）に接続するには、［オンプレミスのインスタンス］ をオンにします。詳しくは、「オンプレミスインスタンス」を参照してください。
- 必要に応じて、［サービス認証］ 方法と ［サービスアクション認証］ を選択します。詳しくは、「サービス認証のセットアップ」を参照してください。
- （オプション）統合のレート制限を有効にするには、［要求レート制限］ を選択します。詳しくは、「要求レート制限」を参照してください。
- これらの統合の構成を保存するには、右上の ［追加］ を選択します。統合の構成を続行します。詳しくは、「統合の構成」を参照してください。
カスタムアイコンの追加
カスタムアイコンを追加して、統合をより適切に識別することができます。HTTP統合をより多くのユーザーに公開すると、アイコンファイルがAzure CDNストレージにアップロードされ、一般公開されます。
アイコンファイルは、次のパラメーターに準拠している必要があります：
- ファイルはPNG形式で、背景は透明です。
- ファイルの解像度は正確に128x128ピクセルである必要があります。
- 最大ファイルサイズは80KBです。
注
カスタムアイコンは、統合の概要用のみです。それらをWorkspace通知に伝達することはできません。
アイコンを追加するには、［Add an icon］ を選択し、アップロードするファイルを選択します。
統合をエクスポートしてから別のインスタンスにインポートすると、そのアイコンがターゲットインスタンスのカスタムアイコン一覧に追加されます。
アイコンを削除するには、アイコンポップアップからアイコンを選択し、［Remove icon］ をクリックします。アイコンは一覧から削除されるだけで、完全に削除されるわけではありません。統合にはアイコンへのリンクが含まれていますが、アイコンを再度選択することはできません。
オンプレミスインスタンス
マイクロアプリサービスを使用すると、オンプレミスのレコードシステム（SoR）に接続できます。オンプレミス統合では、HTTPのベースURLは許可されません。オンプレミス接続を作成するには、最初にコネクタアプライアンスを使用して接続し、その後以下の手順に従ってリソース識別子IDを収集して追加します。詳しくは、「Citrix Cloud Connectorアプライアンス」を参照してください。
- Citrix Cloudに移動し、資格情報を使用してサインインします。
- Citrix Cloudにサインインした後、左上のメニューから ［リソースの場所］ を選択します。
- 使用するリソースの場所を見つけ、リソース名の下にあるIDアイコンを選択して、リソースの場所のIDを表示します。
- リソースの場所のIDをコピーします。
- リソースの場所のIDを ［HTTP統合の追加］ 画面に表示されるオンプレミスインスタンスの ［リソースの場所］ フィールドに貼り付けます。
- （オプション）統合において未署名の証明書を受け入れる必要がある場合は、［SSL証明書の検証］をオフにします。
オンプレミス統合が構成されました。
サービス認証のセットアップ
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は、統合が、構成済みのマイクロアプリとの最大限のセキュリティコンプライアンスを満たすことを保証します。
次の手順を実行します：
- 統合の ［サービス認証］ パラメーターを入力します。
- （オプション）許可の種類が「認証コード」の場合は、［サービスアカウントでログインする］ を選択し、ログインが完了するのを待ちます。
-
（オプション）［サービスアクション認証］をクリックし、サービスアクションレベルで認証パラメーターを入力します。
重要：
委任権限を使用している場合、フルアクセスではない可能性があります。この場合は、［サービスアクション認証］を使用してサービスアクションレベルで認証します。この状況では、サービスレベルで基本認証を使用できますが、セキュリティ上の理由から、サービスアクションレベルでOAuth 2.0を使用する必要があります。
- ［追加］ を選択します。
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統合では、4つの許可の種類から選択できます。OAuth 2.0をセットアップするときに、メニューから許可の種類を選択します。OAuth 2.0を構成するときには、認証コードを使用することをお勧めします。これが最も安全な許可フローであるからです。追加のサービスアクション認証方法が必要な場合は、「クライアント資格情報」および「リソース所有者のパスワード」の許可の種類を使用します：
- 認証コード - クライアントが交換するアクセストークン用の一時コードを付与します。コードは認証サーバーから取得され、そこでクライアントが要求している情報を確認できます。この許可の種類のみが、安全なユーザーの偽装を有効にします。
- クライアント資格情報 - 許可の種類は、ユーザーのコンテキスト以外でアクセストークンを取得するために使用されます。これは、クライアントがユーザーのリソースにアクセスするのではなく、クライアントのリソースにアクセスするために使用されます。
- リソース所有者のパスワード - リソースサーバーによるアクセストークンのプロビジョニングを承認するために、正しい資格情報を提供します。
- 暗黙的なフロー - 暗黙的な許可の種類は、サービスアクション認証と開発者モードにのみ存在します。応答の種類は、tokenまたはid_tokenのいずれかに設定できます。アクセストークンの自動更新は提供されていません。アクセストークンの有効期限が切れたら、再度同意する必要があります。
許可の種類の入力
上記で定義した許可の種類に応じて以下のオプションが提供されるので、これらを完了してOAuth 2.0認証を有効にします：
- スコープ - アクセス要求のスコープを定義します。これは、ターゲット統合アプリケーションをセットアップするときに、承認サーバーによって定義される文字列です。
- クライアントID - 承認サーバーに固有のクライアント登録情報を表す文字列を定義します。
- クライアントシークレット - ターゲットアプリケーション統合のセットアップ時に発行される一意の文字列を定義します。
- ユーザー名 - ターゲットアプリケーションのアカウントのユーザー名を定義します。
- パスワード - ターゲットアプリケーションのアカウントのパスワードを定義します。
- 認証URL - ターゲットアプリケーション統合をセットアップするときに提供される承認サーバーのURLを定義します。
- トークンURL - アクセス承認トークンのURLを定義します。
- 更新トークンURL - （オプション）アクセス承認トークンの更新トークンURLを定義します。設定されていない場合、トークンURLが使用されます。
- アクセストークンパラメーター - 必要に応じて、ターゲットアプリケーション承認サーバーによる要求に従ってアクセストークンパラメーターを定義します。
- サービスアカウントでのログイン - ターゲットアプリケーションの承認サーバーのサービスアカウントにログインします。
- ヘッダープレフィックス - （オプション）ベアラープレフィックスがデフォルトのヘッダーと異なる場合、ヘッダープレフィックスを入力します。
- リレー状態 - 認証を構成すると、ユーザーが資格情報を再入力する必要なく特定のマイクロアプリにアクセスできるようにすることができます。
OAuth 2.0に関する追加リソースは、OAuth 2.0の質問募集ページにあります。
リレー状態
リレー状態は、次の条件が満たされた場合にのみ使用できます：
- OktaをIDプロバイダーとして使用している。
- ターゲットのSoRで、IDプロバイダーとしてOktaがサポートされている。
- リレー状態が有効になっており、正しいOkta URLを使用して適切に構成されている。
Oktaのセットアップが完了したら、リレー状態の［Okta URL］フィールドに、Oktaで提供された統合用のSingleSignOnService URLを入力します。例：https://{your Okta}.okta.com/app/{SoR ID}/{ID}/sso/saml。
リレー状態は完全同期や増分同期では機能せず、ユーザーの操作でのみ機能し、エンドユーザーの資格情報のみを渡します。一部のSoRでは、エンドユーザーによる同意ページの確認が必要です。リレー状態を構成してもこの要件が不要になることはありません。
Oktaの構成に関するその他の情報については、Oktaの公式ドキュメントを参照してください。たとえば、「How to Configure SAML 2.0 for Salesforce」では、SalesforceでOktaを構成する方法を確認できます。
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は両方とも一意であるため、正しく入力したかどうかを確認します。また、スコープなどのその他の入力が正しいことを再確認します。問題が解決しない場合は、統合アプリケーションサーバー側の設定を確認します。
要求レート制限（オプション）
統合のレート制限を有効にするには、［要求レート制限］ を選択します。オンにすると、ターゲットアプリケーションから抽出される要求の数と時間間隔（1秒または1分）を定義できます。ターゲットアプリケーションのドキュメントで定義されている、ベストプラクティスのレート制限をベースにしてレート制限を構成します。
次のステップ
HTTP統合を作成したので、この統合を構成します：