APIコネクターカードを使った認証

概要

サードパーティサービスへの認証済みの接続を作成するには、APIコネクター関数カードを使用します。

背景

構築済みのコネクターを利用できないときは、APIコネクター（API Connector）カードを使用してサードパーティサービスへのリクエストを作成し、応答をフローで解析できます。資格情報はセキュアに保存され、ヘッダーは、提供されるいずれかの認証タイプを使って自動的に作成されます。

HTTPメソッド

APIコネクター関数では、下記のHTTPメソッドのいずれかを使用して認証済みの接続を作成できます。以下のメソッドは、指定されたタイプのリクエストを実行し、リクエストの結果とレスポンスヘッダーを返します。

  • 削除（Delete）
  • Get
  • Patch
  • Post
  • Put

CloseメソッドとRaw Requestメソッドは、以下で説明するように上記のメソッドとはやや異なります。

  • Close：呼び出し元にレスポンスを返してからHTTP接続を閉じます。この関数は、呼び出し元がフロー完了まで待つ必要がない場合、または接続タイムアウトを回避する必要がある場合に使用します。
  • Raw Request：未加工のHTTPリクエストを実行し、リクエストとレスポンスを完全に制御します。これは、XMLサービスの呼び出しやその他の高度なHTTPユースケースで役立ちます。

認証タイプ

以下のステップに従って認証を設定します。

  1. フロービルダーで、関数（Function） > APIコネクター（API Connector）を選択します。

  2. APIコネクターカードを選択します。

  3. + 新規接続（+ New Connection）ボタンをクリックし、新規接続（New Connection）ダイアログを開きます。

  4. 接続のニックネームを入力します。

    APIコネクターカードは複数のコネクターで利用できるため、個々の接続を区別できるように詳細な名前を付けてください。

    この名前では、呼び出されるサービス、認証タイプ、使用アカウントへの参照を記述します。例：JIRA Service Management - OAuth - service_account。

  5. ドロップダウンリストから認証タイプを選択します。APIコネクターカードでは、基本（Basic）、カスタムヘッダー（Custom Header）、OAuth、クライアント資格情報（Client Credentials）、なし（None）の各認証タイプがサポートされます。認証タイプを参照してください。

  6. 認証タイプに必要な、リクエストされた値を入力します。

  7. 作成（Create）をクリックします。

認証タイプのオプション

基本（Basic）

HTTPプロトコルに組み込まれているシンプルな認証スキーマです。必要な値は、呼び出されるサードパーティアプリケーションのユーザー名（Username）とパスワード（Password）です。

Okta Workflowsは、Basicという単語、スペース、base64エンコードされた<username>:<password>という形式の文字列が含まれる認証ヘッダーを持つHTTPリクエストを送信します。

OAuth

OAuth 2.0は、サードパーティサイトのリソースへのスコープ付きアクセスを付与できるようにするプロトコルで、資格情報を公開しません。OAuthプロセスを開始する前に、新しいアプリ（アプリケーション名やウェブサイトのURLなどの情報を含む）をサービスに登録する必要があります。

さらに、認証をWorkflowsに戻すためのリダイレクトURIも登録しなければなりません。Okta Workflowsのプレビューorgと本番orgに接続するには、リダイレクトURIとしてそれぞれhttps://oauth.workflows.oktapreview.com/oauth/httpfunctions/cbとhttps://oauth.workflows.okta.com/oauth/httpfunctions/cbを使用します。

  • 承認パス（Authorize Path）：サービスの承認パス。例：https://example.com/oauth2/v1/authorize。

    OAuth実装に他のクエリパラメーターが必要な場合は、ここで追加できます。?文字を含む承認パスに従い、パラメーターをkey=valueのペアとして&文字で区切って追加します。

  • アクセストークンパス（Access Token Path）：アクセスおよびリフレッシュトークンの承認コードをWorkflowsが交換するためのURI。

  • スコープ（Scope）：Workflowsに提供されるアクセスのレベルを指定します。複数のスコープをスペースまたはカンマで区切って入力できます。ただし、これはサービスによって異なります。リフレッシュトークンを取得するために特別なスコープ（refresh_tokenやoffline_accessなど）が必要かどうかについては、ご利用のサービスのAPIドキュメントを参照してください。

  • クライアントID（Client ID）：サービスによって提供される公開文字列で、OAuthアプリケーションを識別し、承認URLを構築するため使用されます。

  • クライアントシークレット（Client Secret）：サービスによって提供される非公開の値で、アプリケーションのIDをサービスに対して認証します。

クライアント資格情報（Client Credentials）

クライアント資格情報は、OAuth 2.0の付与タイプです。これを使用すると、完全なユーザー固有でないアクセスをサードパーティリソースに付与できます。OAuthオプションと同様に、最初に新しいアプリ（アプリケーション名やウェブサイトのURLなどの情報を含む）をサービスに登録する必要があります。

  • アクセストークンパス（Access Token Path）：アクセスおよびリフレッシュトークンの承認コードをWorkflowsが交換するためのURI。例：https://example.com/oauth2/v1/token。

  • クライアントID（Client ID）：サービスによって提供される公開文字列で、OAuthアプリケーションを識別し、承認URLを構築するため使用されます。

  • クライアントシークレット（Client Secret）：サービスによって提供される非公開の値で、アプリケーションのIDをサービスに対して認証します。

カスタム（Custom）

このオプションを利用することで、カスタムヘッダー名と値を作成できます。

  • ヘッダー名（Header Name）：サービスに渡されるカスタム名。たとえば、サービスによっては、ヘッダー名としてapi_key、値としてキー自体が求められる場合があります。

  • ヘッダー値（Header Value）：ヘッダー名とともにサービスに渡される値。

なし（None）

他のどのオプションも適用されない場合に接続を手動で作成するには、このオプションを使用します。未認証エンドポイントへのアクセスにも利用できます。