How to ガイド - OAuth 2.0リソース所有者のパスワード資格情報認証

OAuth 2.0リソース所有者のパスワード資格情報フローは、サーバー間認証の手段として用いられることが通例です。これを利用して作成したコネクターは、対象の API サーバーと通信する Workato サーバーとして認証を行えます。このフローでは、ユーザーのユーザー名とパスワードを、アクセストークン (および必要に応じて更新トークン) と交換できます。

サンプルコネクター - Microsoft Azure AD

{
  title: 'My Azure connector',

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

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

      acquire: lambda do |connection|
        token_url = "https://login.microsoftonline.com/#{connection['tenant_id']}/oauth2/v2.0/token"
        response = post(token_url). 
                    payload(client_id: "#{connection['client_id']}",
                      client_secret: "#{connection['client_secret']}",
                      username: "#{connection['username']}",
                      password: "#{connection['password']}",
                      grant_type: "password").
                    request_format_www_form_urlencoded
          

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

      refresh_on: 401,

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

  },

  test: lambda do |connection|
    get( #Some accessible endpoint )
  end,

  #More connector code here
}

ステップ1 - コネクション項目の定義

この部分では、コネクションの確立を試みるユーザーに向けて表示すべき項目を Workato に指示します。リソース所有者のパスワード資格情報認証を利用する場合は、ユーザーが Azure で生成したクライアント ID とクライアントシークレットが必要となります。また、コネクションの認証に使用するユーザーアカウントのユーザー名とパスワードも指定する必要があります。

必要な情報	説明
クライアント ID	これは Workato と連携する必要のある OAuth アプリの公開 ID です。これを得るには、対象アプリケーション内の検証済みアプリケーションとして Workato を登録する必要があるかもしれません
クライアントシークレット	これは対応する秘密鍵です。API はこれをクライアント ID と合わせて検証します。これを得るには、対象アプリケーション内の検証済みアプリケーションとして Workato を登録する必要があるかもしれません。クライアントシークレットは決してほかの人たちと共有しないでください。
ユーザー名	これは、クライアントの認証のための権限を提供しているユーザーアカウントのユーザー名です。
パスワード	これは、クライアントの認証のための権限を提供しているユーザーアカウントのパスワードです。

この指示は fields キーの中で行われます。このキーはハッシュの配列を受け入れ、その配列内の各ハッシュが、それぞれ個別の入力項目に対応しています。

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

TIP

項目を定義する際は、少なくとも name キーを指定する必要があります。optional、hint、control_type といった追加的な属性を指定すると、その項目のほかの要素をカスタマイズできます。クライアントシークレットのような機密情報に対しては、必ず control_type を password として使用してください。

Workato 内の入力項目を定義する方法について、詳しくはこちらを参照してください。

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

この部分では、このコネクションが使用するべき認証のタイプを Workato に指示します。これは、authorization オブジェクトの type キーを通じて処理されます。クライアント資格情報認証の場合は、custom_auth を使用します。

      type: 'custom_auth'

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

acquire キー内で、コネクターのユーザーから提供された client_id、client_secret、username、password をペイロードとして渡します。このリクエストのペイロードは request_format_www_form_urlencoded を用いて送信する必要があることに注意してください。また、付与タイプとして password を指定し、これも POST リクエストのペイロードとして渡します。その後、このリクエストは Microsoft のトークン URL に送信されます。

    acquire: lambda do |connection|
      response = post("https://login.microsoftonline.com/#{connection['tenant_id']}/oauth2/v2.0/token"). # Token URL
                    payload(client_id: "#{connection['client_id']}",
                      client_secret: "#{connection['client_secret']}",
                      username: "#{connection['username']}",
                      password: "#{connection['password']}",
                      grant_type: "password").
                    request_format_www_form_urlencoded

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

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

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

acquire の lambda 関数の出力となるハッシュは、元のコネクションハッシュに取り込まれることが想定されています。以下に例を示します。

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

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

ステップ4 - 以降の HTTP リクエストに対するアクセストークンの適用

続いて、Microsoft から取得したアクセストークンの使用方法を Workato に指示する必要があります。これは apply キー内で行われます。このキーでは、引数 connection に格納されたアクセストークンを参照できます。apply ブロック内に記述したすべての命令は、コネクションの確立後にこのコネクターが送信する HTTP リクエストすべてに適用されます。

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

この例では、受け取ったアクセストークン (connection['access_token']) を、あらゆるリクエストのヘッダーに追加するように定義しています。送信される HTTP リクエストすべてのヘッダーには、Authorization: Bearer XXX が含まれることになります (ここでの XXX は、ハッシュ connection に格納されたアクセストークンを表します)。

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

この部分では、API のベース URL を Workato に指示します。このキーは任意ですが、これを利用すると、コネクターのほかの部分で HTTP リクエストを定義する際に相対パスのみを入力できるようになります。base_uri の設定方法については、こちらを参照してください。

TIP

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

    base_uri: lambda do |connection|
      #some code here
    end

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

エンドユーザーから収集する必要のある項目と、それらの項目からの入力をどう利用するかを定義したので、次はこのコネクションをテストする手段が必要です。これは test キー内で扱われます。

    test: lambda do
      get(# Some accessible code)
    end,

このキー内ではエンドポイントを指定する必要があります。このエンドポイントは、直前に受け取った新しい資格情報を使ってサンプルリクエストを送信するために利用されます。HTTP レスポンスとして200 OK を受け取った場合、接続は成功となります。

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

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