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

概要

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

背景

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

HTTPメソッド

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

  • Delete
  • Get
  • Patch
  • Post
  • Put

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

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

認証タイプ

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

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

  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ドキュメントを参照してください。

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

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

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

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

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

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

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

資格情報は、基本承認ヘッダーとしてではなく、リクエスト本文で送信されます。

Custom（カスタム）

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

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

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

None（なし）

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

構築済みのコネクターとは異なり、APIコネクターカードでは接続のテストが自動的に実行されません。接続をテストするには、フローの［Run this card（このカードを実行）］機能を使用します。