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

ハウツーガイド - JSON Web Token認証 ​

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

JSON Web Token（JWT）は、ペイロードにいくつかのクレームを表明するJSONを含む、任意の署名および任意の暗号化を使用したデータを作成するためのインターネット標準です。

認証では、JWTは秘密鍵または公開鍵のいずれかを使用して署名されます。 たとえば、サーバーは"logged in as admin"というクレームを持つトークンを生成し、それをクライアントに提供できます。 その後、クライアントはそのトークンを使用して、自分がadminとしてログインしていることを証明できます。 承認済みのクライアントは、その後、管理者にアクセスが許可されている情報を取得できます。

JWTは、コンパクトでURLセーフであり、特にWebブラウザーのシングルサインオン（SSO）コンテキストで使用できるように設計されています。

JSON Web Tokenの詳細については、JWT Introductionを参照してください。

サンプルコネクター - Google Calendarコネクター ​

ruby
{
  title: 'My Google calendar connector',

  connection: {
    fields: [
      {
        name: 'iss',
        label: 'Issuer',
        optional: false,
        hint: 'The email address of the service account'
      },
      {
        name: 'sub',
        label: 'Email address',
        optional: false,
        hint: 'Email address of the user that you are impersonating'
      },
      {
        name: 'private_key',
        optional: false,
        hint: 'Copy and paste the private key that came from the downloaded json.<br>' \
          "Click <a href='https://developers.google.com/identity/protocols/oauth2/service-account/' " \
          "target='_blank'>here</a> to learn more about Google Service Accounts.",
        control_type: 'password',
        multiline: true
      }
    ],

    authorization: {
      type: 'custom_auth',

      acquire: lambda do |connection|
        jwt_body_claim = {
          "iat": now.to_i,
          "exp": 1.hour.from_now.to_i,
          "aud": 'https://oauth2.googleapis.com/token',
          "iss": connection['iss'],
          "sub": connection['sub'],
          "scope": 'https://www.googleapis.com/auth/calendar'
        }
        private_key = connection['private_key'].gsub(/\\n/, "\n")
        jwt_token = workato.jwt_encode(
          jwt_body_claim,
          private_key,
          "RS256"
        )

        post('https://oauth2.googleapis.com/token').
          payload(grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
            assertion: jwt_token).
          request_format_www_form_urlencoded
      end,

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

      refresh_on: [401, 403]
    },

    base_uri: lambda do |connection|
      'https://www.googleapis.com/calendar/v3'
    end
  },

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

  # More connector code here
}

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

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

必要な情報説明
発行者"iss"（発行者）クレームは、JWTを発行したプリンシパルを識別します。
件名"sub"（サブジェクト）クレームは、JWTの対象であるプリンシパルを識別します。 JWT内のクレームは通常、サブジェクトに関するステートメントです。 この場合、これはなりすましているユーザーのメールアドレスです。
秘密鍵/公開鍵これは、ダウンロードしたJSONから取得される"password"です。

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

ruby
    fields: [
      {
        name: 'iss',
        label: 'Issuer',
        optional: false,
        hint: 'The email address of the service account'
      },
      {
        name: 'sub',
        label: 'Email address',
        optional: false,
        hint: 'Email address of the user that you are impersonating'
      },
      {
        name: 'private_key',
        optional: false,
        hint: 'Copy and paste the private key that came from the downloaded json.<br>' \
          "Click <a href='https://developers.google.com/identity/protocols/oauth2/service-account/' " \
          "target='_blank'>here</a> to learn more about Google Service Accounts.",
        control_type: 'password',
        multiline: true
      }
    ],

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

TIP

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

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

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

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

ruby
    type: 'custom_auth'

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

acquireキーでは、まずJWT本文クレームを作成し、ユーザーが指定した秘密鍵で署名してJWTトークンを生成します。 これは、jwt_body_claimとprivate_keyをWorkatoに渡すことで行います。これは、RS256署名アルゴリズムの下でjwt_encodeを使用して送信する必要がある点に注意してください。 次に、生成されたトークンをペイロードとしてGoogle APIのトークンURLに渡します。 ここでは、grant_typeとassertionを、それぞれurn:ietf:params:oauth:grant-type:jwt-bearerと生成されたJWTトークンとして割り当てます。 リクエストのペイロードはrequest_format_www_form_urlencodedで送信する必要がある点に注意してください。

ruby
    acquire: lambda do |connection|
      jwt_body_claim = {
        "iat": now.to_i,
        "exp": 1.hour.from_now.to_i,
        "aud": 'https://oauth2.googleapis.com/token',
        "iss": connection['iss'],
        "sub": connection['sub'],
        "scope": 'https://www.googleapis.com/auth/calendar'
      }
      private_key = connection['private_key'].gsub(/\\n/, "\n")
      jwt_token = workato.jwt_encode(jwt_body_claim, private_key, "RS256")

      post('https://oauth2.googleapis.com/token').
        payload(grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
          assertion: jwt_token)
        .request_format_www_form_urlencoded
    end,

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

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

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

次に、Google Calendarから取得したアクセストークンの使用方法を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 - トークン更新動作の定義 ​

JWTトークンは短時間のみ有効であるため、期限切れ時にJWTトークンを更新するようにこのコネクターに指示する必要があります。 これは、HTTPレスポンスコードまたは正規表現関数のリストを含むrefresh_onキーを使用して簡単に実行できます。 このリストはHTTPリクエストへの任意のレスポンスと照合され、一致が見つかった場合にacquireキーをトリガーします。

ruby
    refresh_on: [401, 403],

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

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

ruby
    base_uri: lambda do
      'https://www.googleapis.com/calendar/v3'
    end

TIP

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

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

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

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

ruby
    test: lambda do |connection|
      get("/colors")
    end

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

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

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

Last updated: