# JWT直接リンク

JSON Web Token(JWT)は、2つの当事者間で情報をJSONオブジェクトとして安全に伝達するための、コンパクトで自己完結型の方法を定義するオープン標準です。JWTは公開鍵/秘密鍵ペアで署名されており、トークンの完全性を検証し、追加のセキュリティ層を提供します。

JSON Web Tokenはユーザーを認証し、アプリケーションやリソースへの検証済みアクセスを提供します。Workatoの埋め込みモデルを実装する前に、JWTを生成してください。

JWT直接リンクは、以下の手順で構成されます:

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

# 前提条件

JWT直接リンクを実装するには、以下の情報が必要です:

  • 秘密鍵と公開鍵のペア

  • Required. JWTトークンは、RS256アルゴリズムで生成された秘密鍵を使用して署名される必要があります。Workatoは公開鍵を使用して、生成されたJWTトークンを検証します。Update JWT signing key APIを使用して公開鍵を設定するか、公開鍵をWorkato Success Representativeに提供してください。

  • 埋め込みベンダーID

  • Required. JWTを生成するには、埋め込みベンダーIDが必要です。Update JWT signing key APIで返されるベンダーIDを使用するか、公開鍵を提供した後にWorkato Success Representativeから入手してください。

  • カスタマーのワークスペースID

  • Required. カスタマーのワークスペースIDは、埋め込みカスタマーを一意に識別します。Admin console に移動し、特定のカスタマーを選択することで、UIからカスタマーのワークスペースIDを取得します。選択すると、カスタマーのワークスペースIDがURLに表示されます。あるいは、get customer APIを呼び出して、カスタマーのワークスペースIDを取得します。WorkatoのIDではなく外部IDを使用する場合、そのセグメントはプレフィックス E で始まる必要があります。

  • カスタマーのユーザーID

  • Optional. カスタマーのユーザーIDは、カスタマーのワークスペース内の個々のワークスペースメンバーを一意に識別します。作成されるWorkatoセッションにユーザーの特定の役割を適用する必要がある場合、カスタマーのユーザーIDを含めてください。get customer workspace member APIを呼び出して、カスタマーのユーザーIDを取得できます。各ユーザーは、カスタマーチームごとにadd member to customer workspace APIを使用して作成されていることを確認してください。WorkatoのIDではなく外部IDを使用する場合、そのセグメントはプレフィックス E で始まる必要があります。

  • オリジンURL

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

# ステップ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オプションによって異なります。

Embedded connection widget

埋め込み接続ウィジェットの直接リンクURLの形式は、以下の例と一致する必要があります。他のウィジェットの直接リンクURLの詳細については、直接リンクURLの構築を参照してください。

Workato accounts hosted in the US Data Center

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

Workato accounts hosted in the Europe Data Center

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

Workato accounts hosted in the Singapore Data Center

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

Workato accounts hosted in the Japan Data Center

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

Workato accounts hosted in the Australia Data Center

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

Fully Embeddedの直接リンクURLの形式は、以下の例と一致する必要があります:

Workato accounts hosted in the US Data Center

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

Workato accounts hosted in the Europe Data Center

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

Workato accounts hosted in the Singapore Data Center

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

Workato accounts hosted in the Japan Data Center

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

Workato accounts hosted in the Australia Data Center

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

Branded access SSOの直接リンクURLの形式は、以下の例と一致する必要があります:

Workato accounts hosted in the US Data Center

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

Workato accounts hosted in the Europe Data Center

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

Workato accounts hosted in the Singapore Data Center

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

Workato accounts hosted in the Japan Data Center

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

Workato accounts hosted in the Australia Data Center

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

# JWTを生成する

JWTを生成するには、次の手順を実行します:

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

ステップ1: ヘッダーを設定する

alg
algクレームを署名の生成に使用するアルゴリズムであるRS256に設定します。
typ
typクレームを使用されるトークンのタイプであるJWTに設定します。

例:

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

ステップ2: ペイロードを設定する

sub
subクレームを以下に設定します:
<workato_embedded_vendor_id>:<customer_team_id>:<customer_user_id>

::: tip PREREQUISITES

埋め込みベンダーID、カスタマーのワークスペースID、およびカスタマーのユーザーIDを取得するための詳細な手順については、前提条件のセクションを参照してください。

:::

iat
iatクレームを現在のエポック時間に設定します。
jti
jtiクレームをグローバルに一意の値に設定します。10分間の期間内で1回のみ使用します。
origin
接続`iframe`が2つ以上のオリジンに埋め込まれている場合、オリジンクレームが必要です。

MULTIPLE ORIGINS

複数のドメインに接続ウィジェットを埋め込む場合、各カスタマーのワークスペースでオリジンURLを設定する必要があります。個々のアカウントでオリジンURLを上書きするには、Admin console > manage customers に移動し、関連するカスタマーのワークスペースにアクセスします。settingsメニューにアクセスし、オリジンURLを更新します。

例:

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

その他のJWTマイクロサービスの例 (opens new window)を参照してください。

3

ステップ3: JWTに署名する

ステップ1で生成したRS256アルゴリズムの秘密鍵でJWTに署名します。秘密鍵は以前にWorkatoに提供した公開鍵と一致している必要があります。


Last updated: 2025/3/11 7:18:42