ハウツーガイド - 複数の認証フローの構築
コネクタでサポートする予定のさまざまなユースケースに応じて、複数の認証（multi-auth）メソッドを構築する必要がある場合があります。 たとえば、API認証中に特定のユーザーのなりすましを必要とするOAuth2 Authorization Code Grantメソッドのサポートを選択できます。 コネクタでデータオーケストレーションのユースケースをサポートする予定がある場合は、安定したマシン間認証のためにAPIキーまたはクライアント認証情報を使用することもできます。 ただし、Workatoでは現在、multi-authコネクションのランタイムユーザーコネクションがサポートされていない点に注意することが重要です。
複数の認証フローを実現するために、WorkatoのConnector SDKでは、コネクタ内で分離および独立した認証フローを定義できます。
認証メソッド
このガイドでは、Workatoでサポートされている他の形式の認証に関する基本的な知識があることを前提としています。 このガイドで参照するため、OAuth2やAPIキーなど、Workatoにおけるその他の基本的な認証形式を理解していることを確認してください。
サンプルコネクタ - Stripe
このコネクタの詳細については、Stripe API Authenticationドキュメントを参照してください。
{
title: 'Stripe',
connection: {
fields: [
{
name: "auth_type",
control_type: "select",
pick_list: [["OAuth2", "stripe_oauth2"], ["API Key", "stripe_api_key"]],
extends_schema: true
}
],
authorization: {
type: "multi",
selected: lambda do |connection|
connection["auth_type"]
end,
options: {
stripe_oauth2: {
type: "oauth2",
fields: [
{ name: 'client_id' },
{ name: 'client_secret' },
],
authorization_url: lambda do |connection|
"https://connect.stripe.com/oauth/authorize?scope=read_write"
end,
token_url: lambda do
"https://connect.stripe.com/oauth/token"
end,
apply: lambda do |_, access_token|
headers("Authorization": "Bearer #{access_token}")
end,
},
stripe_api_key: {
type: "custom_auth",
fields: [
{
name: "api_key",
}
],
apply: lambda do |connection|
headers("Authorization": "Bearer #{connection['api_key']}")
end
}
},
},
base_uri: lambda do
"https://api.stripe.com/"
end
},
test: lambda do |connection|
get('/v1/customers', limit: 1)
end,
#More connector code here
}複数の認証フローを持つコネクタの構築
複数の認証フローを持つコネクタを構築するには、次の手順を実行します。
共通コネクションフィールドの定義
コネクタの複数の認証フローを計画する場合は、まず、すべての認証フローに共通するフィールドを決定します。 これは、APIベースURLまたはターゲットコネクタEnvironmentの場合があります。 少なくとも、各コネクションシナリオをサポートする認証タイプを選択するフィールドを専用に用意する必要があります。
この説明で使用する例であるStripeでは、共通コネクションフィールドは認証タイプのみです。
- 認証タイプ
- 定義済みpicklistからの認証タイプ。
次の重要な属性があります- スキーマ属性
extends_schema: trueは、このフィールドの値をユーザーが変更したときにコネクションスキーマを再評価するようWorkatoに指示します- Picklist値
stripe_oauth2およびstripe_api_keyは、後続のコネクタ定義で重要です。
これは、ハッシュの配列を受け入れるfieldsキーで実行されます。 この配列内の各ハッシュは、個別の入力フィールドに対応します。
fields: [
{
name: "auth_type",
label: "Authentication Type",
control_type: "select",
pick_list: [["OAuth2", "stripe_oauth2"], ["API Key", "stripe_api_key"]],
extends_schema: true
}
]選択した認証フローへのパスの定義
このコンポーネントは、入力フィールドから受け取った値をどう処理するか、および使用する認証フローをWorkatoに通知します。 これはauthorizationキーを通じて実装されます。 まず、認可のtypeを"multi"として定義します。
authorization: {
type: "multi",
selected: lambda do |connection|
connection["auth_type"]
end,
},さまざまな認証フローの定義
コネクタのすべてのフローを含むoptionsハッシュ内に複数の認証フローを定義します。 これは、connection引数を受け取るselected lambdaを通じて実装します。 これにより、fieldsで定義されたすべてのコネクション入力を参照でき、出力として文字列値が想定されます。
authorization: {
type: "multi",
selected: lambda do |connection|
connection["auth_type"]
end,
options: {
stripe_oauth2: {
type: "oauth2",
fields: [
{ name: 'client_id' },
{ name: 'client_secret' },
],
authorization_url: lambda do |connection|
"https://connect.stripe.com/oauth/authorize?scope=read_write"
end,
token_url: lambda do
"https://connect.stripe.com/oauth/token"
end,
apply: lambda do |_, access_token|
headers("Authorization": "Bearer #{access_token}")
end,
},
stripe_api_key: {
type: "custom_auth",
fields: [
{
name: "api_key",
}
],
apply: lambda do |connection|
headers("Authorization": "Bearer #{connection['api_key']}")
end
}
},
},optionハッシュ内の各キーは、selected lambdaの可能な出力値の1つに正確に対応している必要があります。 この場合、selectedの結果値はstripe_oauth2またはstripe_api_keyのいずれかになることがわかります。これは、auth_type入力フィールドで定義した可能なオプションがこの2つだけであるためです。 これは、optionsハッシュで定義したキーと正確に一致します。
各キー内で、type、apply、acquireなど、認証フローの追加属性を定義できます。 これにより、既存のユースケースに基づいて特定の認証フローを構築できます。 各オプション内にネストされたfields配列として追加キーを定義し、特定のフィールドの認証フローをサポートすることもできます。
この例では、OAuth2用にclient_idおよびclient_secretフィールドを定義し、APIキー認証用にapi_keyフィールドを定義します。 また、stripe_oauth2ハッシュ内にOAuth2フローに必要なすべてのキーを定義し、stripe_api_keyハッシュ内にAPIキー認証に必要なすべてのキーを定義します。
認証タイプ
Multi-authenticationは、複数の認証フローとタイプをサポートします。 認証タイプの完全な一覧については、SDK認証ガイドを参照してください。
既存のコネクタをmulti-authに変換
既存のコネクターに新しい認証メソッドを追加する際に、既存の認証メソッドをデフォルトとして指定するには、||演算子を使用します。
次の例では、||演算子の左側の値であるauth_typeが最初に評価されます。 値がnilまたはfalseの場合、右側の値であるapi_keyが評価されます。
selected: lambda do |connection|
connection["auth_type"] || 'api_key'
end,APIのベースURIの設定
APIのベースURIは、APIのベースURLをWorkatoに指示します。 このキーは任意です。ただし、コネクタ定義の残りの部分でHTTPリクエストを通じて相対パスのみを指定できるようになります。 ベースURIを設定する方法を確認してください。
base_uri: lambda do
"https://api.stripe.com/"
endURIコネクション引数
このlambda関数はconnection引数にアクセスできます。 これは、ユーザーのインスタンスに応じてAPIのベースURIが変わる場合に非常に便利です。 connection引数には次の形式でアクセスできます。
base_uri: lambda do |connection|
#some code here
endさらに、認証タイプによってベースURIが変わる場合は、次の例に示すように、IF-ELSE構造を実装して動的に変更できます。
base_uri: lambda do |connection|
if connection['auth_type'] == "stripe_oauth2"
"https://api.stripe.com/"
else
"https://www.stripe.com/api"
end
endコネクションのテスト
各認証オプションのフィールドとフローを定義したら、新しいコネクションをテストする必要があります。 testキーを使用します。
test: lambda do |connection|
get('/customers', limit: 1)
end,testキーは、ユーザーからの新しい認証情報を使用してサンプルリクエストを送信するためのエンドポイントを提供します。 成功したコネクションは200 OK HTTPレスポンスを受け取ります。 上記の前の例では、有効なAPIキーがある場合、/api/channelsエンドポイントへのGETリクエストは200レスポンスを返します。
コネクションSDKリファレンス
connectionキー内で使用可能なキーとそのパラメータの詳細については、SDKリファレンスを参照してください。
Last updated: