# JSON Web Token (JWT)

セキュリティを強化するために API 利用者は JSON Web Token (JWT) を使用できます。このトークンは、ウェブ認証のための規格 RFC 7159 (opens new window) に基づいています。JWT トークンは、アクセスプロファイルの管理者が選択したシークレットまたはキーを使用して署名されます。

JWT トークンは、ユーザーを認証してビジネスアプリケーションへの検証済みアクセス権を提供する ID プロバイダ (Okta、OneLogin、Auth0 など) によって使用されます。ID プロバイダは一元的な認証メカニズムを通じて、シングルサインオンとも呼ばれる効率的なアクセス制御を提供します。

また、JWT トークンは、トークンが正規のものであることを証明するために署名することもできます。この仕組みにより、受信者は内容が他の何者によっても変更されていないことを検証でき、セキュリティのレベルをさらに一段階強化できます。

このドキュメントでは、以下の項目について説明します。

Workato がサポートする JWT の署名方式
JWT トークンの生成方法
JWT による Workato API エンドポイントの呼び出し
JWT ペイロードクレームへのアクセス

# サポートされている署名方式

Workato は、次の2つの署名方式に対応しています。

署名方式	説明
HMAC	HMAC は対称型の共有シークレットを使用します (クライアントとサーバーが同じシークレットを持ちます)。これには256 bit のシークレット値が使用されます。
RSA	RSA は非対称の鍵のペアを使用します (クライアントが秘密鍵を持ち、サーバーと公開鍵を共有)。

# HMAC 署名方式

HMAC を選択した場合、アクセスプロファイルの画面に次のフィールドが表示されます。

JWT トークンの設定 (HMAC 認証の場合)

# HMAC シークレットの生成方法

共有シークレットには任意の値を選択できますが、最大限のセキュリティを確保するために、安全な乱数生成器で生成した長い値を使用してください。OpenSSL を使用できる場合は、そのようなシークレットを次のコマンドで生成できます。

openssl rand -base64 32

得られたシークレット値を [JWT HMAC secret] フィールドに貼り付けてください。

# RSA 署名方式

RSA を選択した場合、アクセスプロファイルの画面に次のフィールドが表示されます。

JWT トークンの設定 (RSA 認証の場合)

# RSA 公開 / 秘密鍵ペアの生成方法

RSA 認証を設定するには、RSA 公開鍵 / 証明書と、それに対応する RSA 秘密鍵が必要です。これを生成する方法の1つが、OpenSSH による次のコマンドです。

$ ssh-keygen -t rsa

これによって2つのファイルが生成されます。一方は秘密鍵 (拡張子なし)、もう一方は公開鍵 (.pub 拡張子) です。一般的な公開鍵ファイルは、次のようなものです。

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC4O6vRGXTkXWQ4yjj6baC7xAlrJPagWQ1WgI7RBUfk5PRPyD88Lp1vqe0CqshOIEeIVca3mD+W0YtJGlu4IaFh2gIC0W2lQY+3yXkzw2IQvnK1jjzxLJ6Dho7Vh3kLVqlmDB0ABdFhoU+vZf19AnLMqGhmu81xXoutK89MJAfvGFWbZ/zfM/yl9aqTOVrEJFpUxloL2IY/EAiUqblRTH5KWtimetEPF8VG3hu/YeU/5/CzPGZaLKUOcO3k0A6a6iIA2ruV180QN0FmgrCUsQ6oA6vWZsY1LuJm3bnLv7KJApR+WYqp7OCMlhk67N7zxkbZqNb2+eyUCx7E2SFCjFkR jdart@bear

公開鍵を抽出し、PEM でエンコードされた PKCS8 形式に変換します。

$ ssh-keygen -f id_rsa.pub -e -m pkcs8

-----BEGIN PUBLIC KEY-----
MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEA5Km1rCwq8kYq/hbw14Se
bc7Y+2/0DRt+GmCGOdqAZoYm0CknVwvTzzlDrAlMcSdb3kQNHf2eJc+tJ8+krhOI
jKVhr4+RXEJ2tL+dvlB+BwrhVV2MmmYY1YtHyJvb+lhWPvevq5PsJ2U0uNtLyvuv
wOucUzofi2N8iSelpNcYgga0TTXb41KxLUVRoFVEFUl10iUL8JWbK1WOiCAncUwi
T5gg6c+M+g65+DILnCN7cFJ50CFVLET4WQLN8gMkMR5/buXkA35YGKZLUtm299Ju
H1Hx+DrJ+U9tm+3lRsYX+208sn+9IFzdVqQLnNPP5GFzM8m3k5bVxn2d9I+Isq2C
7X5crDcGWAdjp0OE+iMISa9yMeEVj8WgEeC8hHe9LDzPd0D3+kHHtKV4ETCjI15C
kmYiDzGvxPuKGBSZdeMOC3xSx5cDtPc7KIJKohtOn7nbTh/5cXAtlyes4iYibX20
IF04bOOp+QaTUZUIfv/ZkBbQmgbd16nJLjHBR9X5wRudAgMBAAE=
-----END PUBLIC KEY-----

最後に、この PEM でエンコードされた公開鍵は [Access Profile] 画面の [JWT RSA public key] フィールドに貼り付ける必要があります。

# JWT トークンの生成方法

JWT トークンには、API リクエスト元がサーバーとやり取りする複数の情報をカプセル化できます。Workato で必須となるのは Workato のアクセスキーです。これを JWT のヘッダーに次のように配置する必要があります。

{
  "alg": "HS256",
  "kid": "d4aee74e131926682043395edecaf377765fae48e56e232cb295af475b314545"
}

代わりに使用できるクレーム

この例では Workato のアクセスキーが kid クレームとしてヘッダーに含まれています。一部の ID プロバイダでは、kid クレームを制限している場合があります。そのような場合は、トークンのペイロードセクション内で、アクセスキーを次のクレームのいずれかの下に含めることができます: https://www.workato.com/sub、workato_sub、または sub。

代わりに使用できるクレームの詳細は、こちらをご覧ください。

JWT トークンは JSON 構造の署名付き表現です。JWT トークンは JWT.IO (opens new window) のツールを使って生成できます。

JWT を使用する場合は、API リクエスト元の責任において、適切なフォーマットでトークンを生成し、パッケージ化する必要があります。JWT.IO (opens new window) では、この作業を容易にするオンラインツールを提供しています。上記の JSON フォーマットのテキストを、このツールの [Decoded] 側の [PAYLOAD] フィールドに貼り付けるか、入力してください。さらに、 [VERIFY SIGNATURE] セクションに秘密鍵 (RSA) またはシークレット文字列 (HMAC) を貼り付けます。入力が完了すると左側の [Encoded] セクションに、署名およびエンコードされたキーが表示されます。

Workato が対応する標準的アルゴリズムは HS256 (別名 HMAC) と RS256 (別名 RSA) の2つです。

たとえば、HMAC による JWT は次の図のように生成されます。

JWT の生成

同様に、ID プロバイダは、対応する JWT クレームに API キーを埋め込んだ JWT トークンを発行できます。JWT 内の Workato 関連クレームの詳細は、こちらをご覧ください。

# JWT による API エンドポイントの呼び出し

エンコードおよび署名済みのトークンはヘッダー内で Workato API に渡されます (「API の呼び出し」参照)。アクセストークンは Authorization ヘッダーで Bearer 認証スキームを用いて送信されます。

次の例は、Postman でのトークンの使われ方を示したものです。 Postman で使用される JWT トークンの例

次の例は、curl リクエストでのトークンの使われ方を示したものです。

curl -XGET \
-H 'Authorization: Bearer ayJhbGciOiJIUzI1NakIKjkJFVCJ9.eyJzdWIiOiI4OJSIFMLLdkZTY0ZWZkNDY1MTcyMjk2MDA2ZTlmNDEwNGEzOGJmMDAzZTk0YmYyYzRiMzhjYzg3ZDgwYjU0ODk1IiwibmFtZSI6os9fvaG4gRG9lIn0.D_ZHmYZkbRAFQeL' \
'https://apim.workato.com/api-endpoints-v1/call?email=john-doe%40acme.com'

# JWT ペイロードクレームの抽出

従業員 ID を管理する ID プロバイダは、多くの場合、 メールアドレス 、 従業員 ID 、割り当てられている 権限またはスコープ など、対象に関するいくつかの情報を読み込みます。それらは、ペイロードクレームとして JWT に書き込まれています。

下図は、デコードされた JWT ペイロードの例です。ここでは Workato のアクセスプロファイルを特定するために sub クレームを使用しており、その他のクレームは API 呼び出し元についての補足情報となっています。

{
    "sub": "588dec828cc4fc6f579e5252ca4a3acb3d24527efa588e0329a9490a0d1dc062",
    "name": "John Doe",
    "email": "[email protected]",
    "acme_id": "A0122152",
    "admin": true
}

Workato はこの JWT を解析し、すべてのペイロードクレームを読み取ります。優先されるのは、標準クレーム (opens new window)およびアクセスプロファイルの認証に必要なクレームです。JWT が文字数制限を超えた場合、ペイロードは切り詰められ、一部のペイロードクレームにはその後アクセスできなくなる可能性があります。

文字数制限

エンコードされた JWT ペイロードの文字数は最大で4096文字です。これよりペイロードが長い JWT トークンを含むリクエストは、次のエラーで失敗します。

{
  "error": "JWT payload size exceeded (5358, max 4096)"
}

# JWT ペイロードクレームの抽出方法

レシピの作成段階では、JWT ペイロードクレームは JWT claims データピル内に存在します。

手順	説明
1	Formula モードに切り換え、JWT claims データピルを JSON オブジェクトとして解析します。たとえば、`email` クレームを抽出するには、`[JWT Claims]["email"]` という構文を使用します。 JWT ペイロードクレームの抽出
2	ペイロードクレームは実行時に自動的に解析されます。実行時に解析された JWT ペイロードクレーム

Last updated: 2024/7/10 18:18:20