ハウツーガイド - OAuth 2.0認可コードバリアント

OAuth 2.0認可コードフローは、WorkatoがAPIへの認証時に特定のユーザーになりすますための方法です。これは、ユーザーが初めて接続を試みるときに、ブラウザーポップアップを通じてユーザーの同意を得ることで行われます。

サンプルコネクター - Podio

ruby

{
  title: 'My Podio connector',

  connection: {
    fields: [
      {
        name: 'client_id',
        optional: false
      },
      {
        name: 'client_secret',
        optional: false,
        control_type: 'password'
      }
    ],

    authorization: {
      type: "oauth2",

      authorization_url: lambda do
        "https://percolate.com/auth/oauth2"
      end,

      token_url: lambda do
        "https://podio.com/oauth/token"
      end,

      client_id: lambda do |connection|
        connection['client_id']
      end,

      client_secret: lambda do |connection|
        connection['client_secret']
      end,

      apply: lambda do |connection, access_token|
        headers("Authorization": "OAuth2 #{access_token}")
      end,

      refresh_on: [401, 403],

      refresh: lambda do |connection, refresh_token|
        response = post("https://podio.com/oauth/token").
                      payload(
                        grant_type: "refresh_token",
                        client_id: connection["client_id"],
                        client_secret: connection["client_secret"],
                        refresh_token: refresh_token
                      )
        [
          { # This hash is for your tokens
            access_token: response["access_token"],
            refresh_token: response["refresh_token"]
          }
        ]
      end,
    }
  },

  test: lambda do |connection|
    get('/oauth/scope')
  end,

  #More connector code here
}

Podio APIを確認してください

ステップ1 - コネクションフィールドの定義

このコンポーネントは、コネクションを確立しようとしているユーザーに表示するフィールドをWorkatoに指示します。認可コード認証の場合、ユーザーがPodioで生成したClient IDとClient Secretが必要です。

必要な情報	説明
Client ID	これは、この特定のカスタムコネクターがAPIに登録した"username"です。これは、アプリケーションでWorkatoを検証済みアプリケーションとして登録することを意味する場合があります。
クライアントシークレット	これは、この特定のカスタムコネクターがAPIに登録した"password"です。これは、アプリケーションでWorkatoを検証済みアプリケーションとして登録することを意味する場合があります。 client secretを他の人と共有しないでください

これは、ハッシュの配列を受け入れるfieldsキーで実行されます。この配列内の各ハッシュは、個別の入力フィールドに対応します。

ruby

    fields: [
      {
        name: 'client_id',
        optional: false
      },
      {
        name: 'client_secret',
        optional: false,
        control_type: 'password'
      }
    ],

設定済みのPodioコネクションフィールド

TIP

フィールドを定義するときは、少なくともnameキーを指定する必要があります。 optional、hint、control_typeなどの追加属性を使用すると、これらのフィールドの他の側面をカスタマイズできます。 Client Secretなどの機密情報には、control_typeとしてpasswordを使用してください。

Workatoでの入力フィールドの定義の詳細については、コネクションフィールドを参照してください。

Environment propertiesを使用して組織の静的なクライアントIDとシークレットを保存

組織全体向けのコネクターを構築する場合、コネクションの作成時に各個人がクライアントIDとシークレットを提供するのは非効率的であることがよくあります。 Workatoでは、まさにこの目的のためにEnvironment propertiesを使用し、これらの認証情報を安全に保存できます。

コネクションコードからclient_idまたはclient_secretのフィールドを削除し、代わりにaccount_propertyメソッドを使用して、適切な値を指すプロパティを参照できます。

HubSpotの例

ruby

authorization_url: lambda do |connection|
  client_id = account_property('hubspot_webhook_client_id')
  "https://app.hubspot.com/oauth/authorize?client_id=#{client_id}&response_type=code&scope=crm.objects.companies.read crm.objects.contacts.read crm.objects.deals.read"
end,

acquire: lambda do |connection, auth_code, redirect_uri|
  client_id = account_property('hubspot_webhook_client_id')
  client_secret = account_property('hubspot_webhook_client_secret')
  response = post("https://api.hubapi.com/oauth/v1/token").
    payload(client_id: client_id,
      client_secret: client_secret,
      grant_type: 'authorization_code',
      code: auth_code,
      redirect_uri: redirect_uri).
    request_format_www_form_urlencoded
  [
    {
      access_token: response['access_token'],
      refresh_token: response['refresh_token']
    },
    nil,
    nil
  ]
end,

ステップ2 - 認可タイプの定義

このコンポーネントは、コネクションを確立するために、入力フィールドから受け取った値をどのように処理するかをWorkatoに指示します。これはauthorizationキーで処理されます。このキーでは、まず認可のtypeを定義します。この場合は、oauth2を使用する必要があります。

ruby

      type: "oauth2",

ステップ3 - クライアントID、クライアントシークレット、認可URL、トークンURLの定義

VIRTUAL PRIVATE WORKATO (VPW)のお客様

この機能を使用するには、お使いのVirtual Private Workato（VPW）インスタンスに固有の設定手順が必要です。 VPWをご利用のお客様は、インスタンスの設定詳細について、VPWのプライベートドキュメントを参照してください。

OAuth 2の認可コードグラントバリアントでは、コネクターに4つの主要属性を指定します。

認可URL - ユーザーが認可を行うために、ブラウザーポップアップ経由でリダイレクトされる場所。
トークンURL - このコネクターが認可URLから認可コードを受け取った後、アクセストークンを受け取るためにリクエストを送信する場所。
クライアントID - このコネクションに割り当てられたOAuthアプリの公開ID。
クライアントシークレット - このコネクションに割り当てられたOAuthアプリの秘密キー。

ruby

    authorization_url: lambda do |connection|
      "https://podio.com/oauth/authorize"
    end,

    token_url: lambda do |connection|
      "https://podio.com/oauth/token"
    end,

    client_id: lambda do |connection|
      connection['client_id']
    end,

    client_secret: lambda do |connection|
      connection['client_secret']
    end,

authorization_urlラムダ関数を定義するときに、クライアントID、リダイレクトURI、またはstateを明示的に渡す必要はありません。 Workatoが代わりに処理します。場合によっては、URLにスコープを追加する必要があります。

ただし、アプリケーションでリダイレクトURIを事前に登録する必要がある場合は、次のコールバックURLを使用します。

url

https://www.workato.com/oauth/callback

この統一されたコールバックURLは、すべてのWorkatoデータセンターで機能します。

token_urlラムダ関数を定義するときに、クライアントID、クライアントシークレット、およびgrant_typeを明示的に渡す必要はありません。 Workatoが代わりに処理します。 token_urlリクエストでは、RFC標準に従い、関連情報をペイロード本文に含めたPOSTリクエストを使用します。

client_idとclient_secretを定義するときは、以前にfields部分から収集したエンドユーザーからの入力を使用できます。 Workatoは、これらの入力をコードに直接記述することを推奨していません。

Workatoが有効期間の短い認可コードを有効期間の長いアクセストークンと交換する場合、token_urlエンドポイントからのレスポンスに2つの主な値、access_tokenとrefresh_tokenが含まれていることを想定しています。レスポンスのサンプルを次に示します。

json

{
  "access_token": "my-authentication-token",
  "token_type": "bearer",
  "expires_in": "seconds-until-expiration",
  "refresh_token": "my-refresh-token",
  "error": "optional-error-message",
  "ref":
  {
    "type": "user",
    "id": USER_ID
  }
}

認証では、access_tokenおよびrefresh_tokenに関連付けられた値が保存されます。

ステップ4 - 後続のHTTPリクエストへのアクセストークンの適用

applyキーでは、取得したアクセストークンをヘッダー入力として適用します。

applyキーにパラメーターとしてaccess_tokenを渡すだけで、access_tokenを取得できます。この引数access_tokenは、token_urlラムダ関数の出力から自動的に割り当てられます。

ruby

    apply: lambda do |connection, access_token|
      headers("Authorization": "OAuth2 #{access_token}")
    end,

コネクションオブジェクトで使用可能なパラメーターとキーの詳細については、SDKリファレンス - コネクションを参照してください。

ステップ5 - トークン更新動作の定義

ほとんどの場合、OAuth 2.0認証には、有効期間の短いアクセストークンと有効期間の長いリフレッシュトークンの両方があります。リフレッシュトークンには有効期限がない場合もあります。

WARNING

すべてのAPIがリフレッシュトークン認証情報を発行するわけではありません。この要件については、APIに確認してください。

アクセストークンの有効期限が切れた場合に、リフレッシュトークンを使用してアクセストークンを更新するためにコネクターが実行する動作を定義できます。

ruby

    refresh_on: [401, 403],

    refresh: lambda do |connection, refresh_token|
      response = post("https://podio.com/oauth/token").
                    payload(
                      grant_type: "refresh_token",
                      client_id: connection["client_id"],
                      client_secret: connection["client_secret"],
                      refresh_token: refresh_token,
                      redirect_uri: 'https://www.workato.com/oauth/callback'
                    )
      [
        {
          access_token: response["access_token"],
          refresh_token: response["refresh_token"]
        }
      ]
    end,

アクセストークンを更新するには、authorizationキーでrefresh_onとrefreshの2つのキーを使用する必要があります。 refresh_onは、HTTPレスポンスコードまたは正規表現文字列を含めることができる配列を受け入れます。コネクター内のHTTPリクエストがいずれかのHTTPレスポンスコードを受け取った場合、またはペイロードの本文が正規表現文字列に一致した場合、refreshキー内のコードが実行され、新しいアクセストークンの取得を試みます。

refreshキーでは、最初のトークンリクエストから受け取ったrefresh_tokenを表す引数にアクセスできます。このラムダ関数の想定される出力は配列であり、最初のインデックスは新しいaccess_tokenと、該当する場合は新しいrefresh_tokenを示すハッシュです。これらは、長期間持続するコネクションの初期値を更新するために使用されます。

refreshラムダの詳細については、SDKリファレンス - authorizationを参照してください。

ステップ6 - APIのベースURIの設定

このコンポーネントは、APIのベースURLをWorkatoに指示します。このキーは任意ですが、HTTPリクエストを定義する際に、コネクターの残りの部分で相対パスのみを指定できるようになります。 base_uriの設定の詳細については、ベースURI設定を参照してください。

ruby

    base_uri: lambda do |connection|
      'https://podio.com'
    end

TIP

このラムダ関数はconnection引数にもアクセスできます。これは、ユーザーのインスタンスに基づいてAPIのベースURIが変わる可能性がある場合に特に便利です。 connection引数には次の形式でアクセスできます。

ruby

    base_uri: lambda do |connection|
      "https://#{connection['domain'].com/api}"
    end

ステップ7 - コネクションのテスト

エンドユーザーから収集する必要があるフィールドと、それらのフィールドからの入力をどう処理するかを定義したので、次にこのコネクションをテストする方法が必要です。これはtestキーで処理されます。

ruby

    test: lambda do
      get('/oauth/scope')
    end,

このブロックでは、受け取ったばかりの新しい認証情報を使用してサンプルリクエストを送信できるエンドポイントを指定する必要があります。 200 OK HTTPレスポンスを受信すると、コネクションをSuccessfulとして表示します。上記の例では、/oauth/scopeエンドポイントにGETリクエストを送信し、APIキーが有効な場合に200レスポンスが返されることを想定しています。

認可コードグラントのバリエーション

通常の標準認証フローから逸脱する場合は、acquireブロックを使用します。このブロックでは、認証プロセス中に発生するHTTP呼び出しを定義できます。たとえば、一部のAPIでは、ベーシック認証を使用したPOSTリクエストによって認可トークンを取得する必要があります。

TIP

より高い制御性が必要なユーザーには、token_urlブロックではなくacquireブロックの使用が推奨されることがよくあります。 acquireブロックを使用すると、アクセストークンを取得するためのAPIリクエストのすべての側面を制御できます。また、refresh_token_expires_inキーを介した自動トークン更新のスケジュール設定や、OAuthスコープなどの他のメタデータをコネクションハッシュに保存する点で、より高い柔軟性が得られます。

`acquire`キーの使用

以下の例では、token_urlブロックがデフォルトでヘッダー認証を使用するため、acquireキーを使用してベーシック認証付きのPOST HTTP呼び出しを送信しました。その後、POST呼び出しへのレスポンスからaccess_tokenとrefresh_tokenを取得できます。

ruby

    authorization: {
      type: "oauth2",

      authorization_url: lambda do |connection|
        params = {
          response_type: "code",
          client_id: connection["client_id"]
        }.to_param

        "https://login.mypurecloud.com/oauth/authorize?" + params
      end,

      acquire: lambda do |connection, auth_code|
        response = post("https://login.mypurecloud.com/oauth/token").
          payload(
            grant_type: "authorization_code",
            code: auth_code,
            redirect_uri: "https://www.workato.com/oauth/callback"
          ).
          user(connection["client_id"]).
          password(connection["client_secret"]).
          request_format_www_form_urlencoded

        # After defining the POST method, we now need to define the
        # output of the acquire key in a fashion that we can recognise
          [
            {
              access_token: response["access_token"],
              refresh_token: response["refresh_token"],
              refresh_token_expires_in: response["expires_in"] # Expiration time of the refresh token from now in seconds
            },
            nil,
            # Optional. Will be merged into connection hash
            { instance_id: nil }
          ]
        end,

        apply: lambda do |connection, access_token|
          headers("Authorization": "Bearer #{connection["access_token"]}")
        end
      }
    },

.userメソッドと.passwordメソッドは、POSTリクエストヘッダーでAuthorization: BASICおよび<user>:<password>をBASE-64文字列エンコードで追加することと同等です。リクエストはrequest_format_www_form_urlencodedで送信する必要があることに注意してください。

リクエストを受信すると、APIは次のようなJSONレスポンスを返します。

json

{
  "access_token": "token",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_token": "my-refresh-token",
  "error": "optional-error-message"
}

OAuth 2.0認証メソッドでacquireキーを使用する場合、想定される出力はハッシュの配列であることに注意してください。配列内の各インデックスには、次の値を順番に含める必要があります。

トークン - access_token、refresh_token、およびrefresh_token_expires_inの正確なキーを含むハッシュである必要があります。 refresh_tokenとrefresh_token_expires_inの値は任意ですが、推奨されます
所有者ID - クロバー検出に使用される任意の値です（使用しない場合はnilに置き換えます）
その他の値 - ここでは、元のコネクションハッシュにマージされる任意のハッシュを指定できます。

これは、次のコネクターコードと一致します。

ruby

  [
    {
      access_token: response["access_token"],
      refresh_token: response["refresh_token"],
      refresh_token_expires_in: response["expires_in"] # in seconds
    },
    nil,
    # Optional. Will be merged into connection hash
    { instance_id: nil }
  ]

コネクションSDKリファレンス

connectionキー内で使用可能なキーとそのパラメーターに慣れるには、SDKリファレンスを確認してください。

Last updated:

ハウツーガイド - OAuth 2.0認可コードバリアント ​

サンプルコネクター - Podio ​

ステップ1 - コネクションフィールドの定義 ​

ステップ2 - 認可タイプの定義 ​

ステップ3 - クライアントID、クライアントシークレット、認可URL、トークンURLの定義 ​

ステップ4 - 後続のHTTPリクエストへのアクセストークンの適用 ​

ステップ5 - トークン更新動作の定義 ​

ステップ6 - APIのベースURIの設定 ​

ステップ7 - コネクションのテスト ​

認可コードグラントのバリエーション ​

acquireキーの使用 ​

コネクションSDKリファレンス ​

ハウツーガイド - OAuth 2.0認可コードバリアント

サンプルコネクター - Podio

ステップ1 - コネクションフィールドの定義

ステップ2 - 認可タイプの定義

ステップ3 - クライアントID、クライアントシークレット、認可URL、トークンURLの定義

ステップ4 - 後続のHTTPリクエストへのアクセストークンの適用

ステップ5 - トークン更新動作の定義

ステップ6 - APIのベースURIの設定

ステップ7 - コネクションのテスト

認可コードグラントのバリエーション

`acquire`キーの使用

コネクションSDKリファレンス