# How to ガイド - OAuth 2.0クライアント資格情報認証
OAuth 2.0クライアント資格情報フローは、サーバー間認証の手段として用いられることが通例です。これを利用して作成したコネクターは、対象の API サーバーと通信する Workato サーバーとして認証を行えます。
# サンプルコネクター - Percolate
{
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 = ("client:#{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
}
- このコネクターのコード全体はこちら (opens new window)で確認できます。
- Percolate API についてはこちら (opens new window)を参照してください。
# ステップ1 - コネクション項目の定義
この部分では、コネクションの確立を試みるユーザーに向けて表示すべき項目を Workato に指示します。クライアント資格情報認証を利用する場合は、ユーザーが Percolate で生成したクライアント ID とクライアントシークレットが必要となります。
| 必要な情報 | 説明 |
|---|---|
| クライアント ID | これは Workato と連携する必要のある OAuth アプリの公開 ID です。これを得るには、対象アプリケーション内の検証済みアプリケーションとして Workato を登録する必要があるかもしれません |
| クライアントシークレット | これは対応する秘密鍵です。API はこれをクライアント ID と合わせて検証します。これを得るには、対象アプリケーション内の検証済みアプリケーションとして Workato を登録する必要があるかもしれません。クライアントシークレットは決してほかの人たちと共有しないでください。 |
この指示は fields キーの中で行われます。このキーはハッシュの配列を受け入れ、その配列内の各ハッシュが、それぞれ個別の入力項目に対応しています。
fields: [
{
name: 'client_id',
optional: false,
},
{
name: 'client_secret',
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 の lambda 関数で行われます。
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 を渡しています。これらの値は lambda 関数への引数である connection を介して利用できます。これらはヘッダーとして、BASE-64 文字列エンコーディングで渡されています。リクエストの本文は、Percolate の要件に従って、request_format_www_form_urlencoded で送信する必要があります。その後、このリクエストは Percolate のトークン URL に送信されます。
リクエストを受信すると、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 key is executed
{
client_id: "abcd1234",
client_secret: "secretClientSecret",
access_token: "my-authentication-token"
}
# ステップ4 - 以降の HTTP リクエストに対するアクセストークンの適用
続いて、Percolate から取得したアクセストークンの使用方法を 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 がアクセストークンを失効させることがあります。このような場合は、OAuth サーバーから新しい access_token を取得すべきタイミングを Workato に知らせるために、refresh_on シグナルを定義する必要があります。refresh_on は、HTTP レスポンスコードまたは正規表現文字列を含む可能性のある配列を受け入れます。
これに該当する HTTP レスポンスコードがコネクター内の HTTP リクエストによって受信されると、新しいアクセストークンの取得が試みられます。同様に、定義された正規表現文字列とペイロード本文の内容が一致する場合にも、新しいアクセストークンが取得されます。
この type: custom_auth を使用している例では、acquire キー内のコードが実行されることになります。
refresh_on: [401, 403],
acquire の lambda 関数が再度実行されたとき、Percolate からは以下のようなレスポンスが返されることが想定されます。
{
"access_token": "my-NEW-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",
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 の設定方法については、こちらを参照してください。
base_uri: lambda do |connection|
'https://percolate.com'
end
TIP
この lambda 関数では引数 connection にもアクセスできます。これは、API のベース URI がユーザーのインスタンスに基づいて変化する場合に特に便利です。引数 connection には次の形式でアクセスできます。
base_uri: lambda do |connection|
"https://#{connection['domain'].com/api}"
end
# ステップ7 - コネクションのテスト
エンドユーザーから収集する必要のある項目と、それらの項目からの入力をどう利用するかを定義したので、次はこのコネクションをテストする手段が必要です。これは test キー内で扱われます。
test: lambda do
get('/api/v5/me')
end,
このブロックではエンドポイントを指定する必要があります。このエンドポイントは、直前に受け取った新しい資格情報を使ってサンプルリクエストを送信するために利用されます。HTTP レスポンスとして200 OK を受け取った場合、接続は成功となります。上記の例では、エンドポイント /api/v5/me に GET リクエストを送信し、入力された API キーが有効であればレスポンスとして200 OK を受け取ることが期待されています。
# コネクションの SDK リファレンス
connection キー内で使用可能なキーとそのパラメータについての詳細は、SDK リファレンスを確認してください。
Last updated: 2023/8/31 1:07:14