JWTダイレクトリンク ​

JSON Web Token（JWT）は、2者間で情報をJSONオブジェクトとして安全に送信するためのコンパクトで自己完結型の方法を定義するオープン標準です。 JWTは秘密鍵/公開鍵ペアで署名され、トークンの整合性を検証し、セキュリティレイヤーを追加します。

JSON Web Tokenはユーザーを認証し、アプリケーションおよびリソースへの検証済みアクセスを提供します。 Workato Embeddingモデルを実装する前に、JWTを生成します。

JWTダイレクトリンクは、次の手順で構成されます。

1. 公開鍵/秘密鍵ペアを生成する
2. ダイレクトリンクURLマイクロサービスをインストールする
3. JWTを生成する

前提条件 ​

JWTダイレクトリンクを実装するには、次の情報が必要です。

• 秘密鍵と公開鍵のペア

• 必須。 JWTトークンは、RS256アルゴリズムで生成された秘密鍵を使用して署名する必要があります。 鍵はPEMとしてフォーマットする必要があり、RS256が使用されている限り、PKCS#1標準またはPKCS#8標準のいずれにも従うことができます。 PKCS#1はRSA秘密鍵にのみ使用され、モジュラス、公開指数、秘密指数など、RSA秘密鍵マテリアルのみを含みます。 PKCS#1は一般にopenssl genrsaで使用されます。 PKCS#8は、RSA、EC、DSAなど、任意のアルゴリズムの秘密鍵用です。 PKCS#8は、アルゴリズム識別情報を含む汎用の標準化された形式で鍵をラップし、一般にopenssl genpkeyで使用されます。 Workatoは公開鍵を使用して、生成されたJWTトークンを検証します。 公開鍵を設定するにはUpdate JWT signing key APIを使用するか、公開鍵をWorkato Success Representativeに提供します。

• EmbeddedベンダーID

• 必須。 JWTを生成するには、EmbeddedベンダーIDが必要です。 JWT署名キー更新APIによって返されるベンダーIDを使用するか、公開鍵を提供した後にWorkato Success Representativeから取得します。

• 顧客ワークスペースID

• 必須。 顧客ワークスペースIDは、Embedded顧客を一意に識別します。 UIで管理コンソールに移動し、特定の顧客を選択して、顧客ワークスペースIDを取得します。 選択すると、顧客ワークスペースIDがURLに表示されます。 または、get customer APIを呼び出して顧客ワークスペースIDを取得します。 Workato IDの代わりに外部IDを使用する場合、セグメントはプレフィックスEで始まる必要があります。

• 顧客ユーザーID

• オプション。 顧客ユーザーIDは、顧客ワークスペース内の個々のワークスペースメンバーを一意に識別します。 作成されるWorkatoセッションにユーザー固有のロールを適用する必要がある場合は、顧客ユーザーIDを含めます。 顧客ワークスペースメンバー取得APIを呼び出すことで、顧客ユーザーIDを取得できます。 各ユーザーが顧客チームごとに顧客ワークスペースへのメンバー追加APIを使用して作成されていることを確認します。 Workato IDの代わりに外部IDを使用する場合、セグメントはプレフィックスEで始まる必要があります。

• オリジンURL

• 必須。 オリジンURLは、Workato iframeを埋め込むデフォルトドメインです。 Workato iframeがパートナーのアプリケーション内に完全に埋め込まれる場合は、JWTペイロードにオリジンURLを含めます。 さらに、OEM Configで複数のオリジンURLが許可リストに登録されたAuth Widgetを使用する場合も含めます。 origin URLをWorkato Success Representativeに提供してください。

ステップ1: 秘密鍵と公開鍵のペアを生成する ​

秘密鍵を生成する ​

秘密鍵を最初から生成するには、次を使用します。

$ openssl genrsa -out private.key 2048
$ cat private.key
-----BEGIN RSA PRIVATE KEY-----

...

-----END RSA PRIVATE KEY-----

公開鍵を生成する ​

次に、次を使用して公開鍵を抽出します。

$ openssl rsa -in private.key -pubout -out public.key
$ cat public.key
-----BEGIN PUBLIC KEY-----

...

-----END PUBLIC KEY-----

鍵をPEM形式に変換する ​

別の方法を使用して公開鍵/秘密鍵ペアを生成した場合は、Workatoに送信する前に鍵をPEM形式に変換します。

SSH公開鍵から変換するには:

$ ssh-keygen -f key.pkcs -e -m pem > key.pem

ステップ2: ダイレクトリンクURL生成マイクロサービスをインストールする ​

ダイレクトリンクURLマイクロサービスの目的は、安全なリソースへのアクセスを容易にするために、必要なときにJWTを自動的に生成することです。 ダイレクトリンクURLマイクロサービスをサーバーにインストールします。

マイクロサービスは次の仕様を満たす必要があります。

• エンドポイントではベンダー認証が必要です。
• マイクロサービスは、Workatoアセットへのパスを受け入れる必要があります。
• マイクロサービスは、次の構造のURLを生成する必要があります。

https://app.workato.com/direct_link/<resource_path>?<query_params>#<fragment>

マイクロサービスの例: ​

import nanoid from 'nanoid';
import {sign} from 'jsonwebtoken';

function getToken(WorkatoEmbeddedVendorId, customerAccountId, privateKey) {
  return sign({
    sub: `${WorkatoEmbeddedVendorId}:${customerAccountId}`,
    jti: nanoid()
  },
  privateKey,
  {
    algorithm: 'RS256'
  });
}

ステップ3: JWTダイレクトリンク ​

JWT構造 ​

JWTはヘッダー、ペイロード、署名で構成されます。 コンパクト形式では、JWTの各セクションは.で区切られます。

header.payload.signature

ヘッダー

トークンの最初の部分はヘッダーです。 ヘッダーは通常、トークンのタイプと、署名の生成に使用されるアルゴリズムのタイプの2つの部分で構成されます。

ペイロード

トークンの2番目の部分はペイロードで、クレームが含まれます。 クレームは、ユーザーに関するステートメントと追加データです。

署名

トークンの最後の部分は署名です。 署名はクレームの整合性を検証します。

ダイレクトリンクURL ​

サーバーでJWTトークンを生成し、ダイレクトリンクURLを構築する必要があります。 ダイレクトリンクURLの形式は、実装する予定のCXオプションによって異なります。

https://app.workato.com/direct_link/embedded/connections/<connection_id>?workato_dl_token=<jwt_token>

https://app.eu.workato.com/direct_link/embedded/connections/<connection_id>?workato_dl_token=<jwt_token>

https://app.sg.workato.com/direct_link/embedded/connections/<connection_id>?workato_dl_token=<jwt_token>

https://app.jp.workato.com/direct_link/embedded/connections/<connection_id>?workato_dl_token=<jwt_token>

https://app.au.workato.com/direct_link/embedded/connections/<connection_id>?workato_dl_token=<jwt_token>

https://app.il.workato.com/direct_link/embedded/connections/<connection_id>?workato_dl_token=<jwt_token>

https://app.workatoapp.cn/direct_link/embedded/connections/<connection_id>?workato_dl_token=<jwt_token>

https://app.kr.workato.com/direct_link/embedded/connections/<connection_id>?workato_dl_token=<jwt_token>

https://app.workato.com/direct_link?workato_dl_path=<workato_path>&workato_
dl_token=<jwt_token>

https://app.eu.workato.com/direct_link?workato_dl_path=<workato_path>&workat
o_dl_token=<jwt_token>

https://app.sg.workato.com/direct_link?workato_dl_path=<workato_path>&workat
o_dl_token=<jwt_token>

https://app.jp.workato.com/direct_link?workato_dl_path=<workato_path>&workat
o_dl_token=<jwt_token>

https://app.au.workato.com/direct_link?workato_dl_path=<workato_path>&workat
o_dl_token=<jwt_token>

https://app.il.workato.com/direct_link?workato_dl_path=<workato_path>&workat
o_dl_token=<jwt_token>

https://app.workatoapp.cn/direct_link?workato_dl_path=<workato_path>&workat
o_dl_token=<jwt_token>

https://app.kr.workato.com/direct_link?workato_dl_path=<workato_path>&workat
o_dl_token=<jwt_token>

https://app.workato.com/direct_link/recipes?workato_dl_token=<jwt_token>

https://app.eu.workato.com/direct_link/recipes?workato_dl_token=<jwt_token>

https://app.sg.workato.com/direct_link/recipes?workato_dl_token=<jwt_token>

https://app.jp.workato.com/direct_link/recipes?workato_dl_token=<jwt_token>

https://app.au.workato.com/direct_link/recipes?workato_dl_token=<jwt_token>

https://app.il.workato.com/direct_link/recipes?workato_dl_token=<jwt_token>

https://app.workatoapp.cn/direct_link/recipes?workato_dl_token=<jwt_token>

https://app.kr.workato.com/direct_link/recipes?workato_dl_token=<jwt_token>

JWTを生成する ​

JWTの生成は、次の手順で構成されます。

1. ヘッダーを設定する
2. ペイロードを設定する
3. トークンに署名する

{
  "alg": "RS256",
  "typ": "JWT"
}

<workato_embedded_vendor_id>:<customer_team_id>:<customer_user_id>

{
  "sub": "911672h4203fae7ffbe2eca1bbcaa79cc8c47af5377a6c6240:303363:313646",
  "iat":"1624043461",
  "jti": "3oay2t2kntGbxr1yhSINn",
  "origin": "http://www.acme.com"
}