Product UpdatesStatus PageWorkato Academy
English
日本語
Get a trial
Connector SDK
ハウツーガイド
API認可

ハウツーガイド - OAuth 2.0クライアント認証情報による認証 ​

このページは機械翻訳により提供されています。翻訳内容と英語版に相違がある場合は、英語版が優先されます。

OAuth 2.0クライアント認証情報フローは、従来、サーバー間認証の方法です。 これにより、ターゲットAPIサーバーと通信するWorkatoサーバーとして認証できるコネクターを構築できます。

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

ruby
{
  title: 'My Percolate connector',

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

    authorization: {
      type: 'custom_auth', #Set to custom_auth

      acquire: lambda do |connection|
        hash = ("#{connection['client_id']}:#{connection['client_secret']}").base64.gsub("\n", '')
          # Token URL
        response = post('https://percolate.com/auth/v5/token/').
                      payload(grant_type: 'client_credentials').
                      headers(Authorization: "Basic " + hash).
                      request_format_www_form_urlencoded

        {
          access_token: response["access_token"],
          refresh_token: response["refresh_token"]
        }
      end,

      detect_on: [401, 403],

      refresh_on: [401, 403],

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

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

  },

  test: lambda do |connection|
    get('/api/v5/me')
  end,

  #More connector code here
}

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

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

必要な情報説明
Client IDこれは、Workatoに関連付ける必要があるOAuthアプリの公開IDです。 これは、アプリケーションでWorkatoを検証済みアプリケーションとして登録することを意味する場合があります
クライアントシークレットこれは、APIがClient IDとともに検証する対応する秘密鍵です。 これは、アプリケーションでWorkatoを検証済みアプリケーションとして登録することを意味する場合があります。 client secretを他の人と共有しないでください

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

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

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

TIP

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

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

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

このコンポーネントは、このコネクションで使用する認証タイプをWorkatoに伝えます。 これは、authorizationオブジェクト内のtypeキーを通じて処理されます。 Client Credentials認証には、custom_authを使用する必要があります。

ruby
      type: 'custom_auth'

ステップ3 - アクセストークンの取得 ​

次のステップでは、このコネクターがアクセストークンを取得するために何を行うかを定義します。 これはacquireラムダ関数で行います。

ruby
      acquire: lambda do |connection|
        hash = ("client:#{connection['client_id']}:#{connection['client_secret']}").base64.gsub("\n", '')
        response = post('https://percolate.com/auth/v5/token/'). # Token URL
                      payload(grant_type: 'client_credentials').
                      headers(Authorization: "Basic " + hash).
                      request_format_www_form_urlencoded

        {
          access_token: response["access_token"]
        }
      end,

acquireキーで、fieldsキーに定義された入力フィールドであるclient_idとclient_secretを渡します。 これらの値は、ラムダ関数の引数connectionを介して使用できます。 これらをヘッダーとして、BASE-64文字列エンコーディングで渡します。 リクエストの本文は、Percolateの要件に従ってrequest_format_www_form_urlencodedで送信する必要があることに注意してください。 このリクエストはその後、PercolateのトークンURLに送信されます。

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

json
{
  "access_token": "my-authentication-token",
  "token_type": "bearer",
  "expires_in": "seconds-until-expiration",
  "error": "optional-error-message"
}

acquireラムダ関数の出力は、元のコネクションオブジェクトにマージされるオブジェクトであることが期待されます。 例:

ruby
# Original Connection hash
{
  client_id: "abcd1234",
  client_secret: "secretClientSecret"
}

# After acquire key is executed
{
  client_id: "abcd1234",
  client_secret: "secretClientSecret",
  access_token: "my-authentication-token"
}

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

次に、Percolateから取得したアクセストークンを利用する方法をWorkatoに指示する必要があります。 これはapplyキーで行い、現在connection引数に保存されているアクセストークンを参照できます。 applyキーに指定した指示は、コネクションが確立された後、このコネクターが送信するすべてのHTTPリクエストに適用されます。

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

この例では、任意のリクエストのヘッダーに追加されるアクセストークン（connection['access_token']）を定義しています。 送信される各HTTPリクエストのヘッダーには、XXXがconnectionハッシュに保存されたアクセストークンであるAuthorization: Bearer XXXが含まれます。

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

APIが所定の時間後にアクセストークンを期限切れにする状況があります。 このような場合、OAuthサーバーから新しいaccess_tokenをいつ取得するかをWorkatoに知らせるために、refresh_onシグナルを定義する必要があります。 refresh_onは、HTTPレスポンスコードまたは正規表現文字列を含む配列を受け入れます。

コネクター内のHTTPリクエストがHTTPレスポンスコードのいずれかを受信すると、新しいアクセストークンの取得を試みます。 同様に、本文ペイロードの内容が定義済みの正規表現文字列のいずれかに一致すると、新しいアクセストークンを取得します。

type: custom_authを使用する例では、acquireキーのコードを実行します。

ruby
    refresh_on: [401, 403],

acquireラムダが再度実行されると、これはPercolateから期待されるレスポンスです。

json
{
  "access_token": "my-NEW-authentication-token",
  "token_type": "bearer",
  "expires_in": "seconds-until-expiration",
  "error": "optional-error-message"
}

acquire lambda関数の想定される出力は、元のコネクションハッシュにマージされるハッシュです。 例:

ruby
# Original Connection hash
{
  client_id: "abcd1234",
  client_secret: "secretClientSecret",
  access_token: "my-authentication-token"
}

# After acquire lambda is executed
{
  client_id: "abcd1234",
  client_secret: "secretClientSecret",
  access_token: "my-NEW-authentication-token"
}

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

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

ruby
    base_uri: lambda do |connection|
      'https://percolate.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('/api/v5/me')
    end,

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

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

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

Last updated: