JSON Web Token（JWT）
JSON Web Token（JWT）を使用して、API platformを通じて公開されたレシピを呼び出すAPIクライアントを認証できます。 JWTは、静的な認証情報に代わる安全で柔軟な方法を提供し、内部ツールやサードパーティサービスなどのシステムが署名付きトークンで認証できるようにします。
Workatoは、RSA（公開/秘密鍵）とHMAC（共有シークレット）の両方の署名方法をサポートしています。認証するには、クライアントがWorkato APIキーでトークンに署名します。プラットフォームはトークンを検証して、エンドポイントへのアクセスを承認します。
JWTはRFC 7519仕様で定義されています。
サポートされている署名方法
Workatoは2つの署名方法をサポートしています:
| 署名方法 | 説明 |
|---|---|
| RSA（公開鍵） | 推奨。非対称キーペアを使用します。クライアントは秘密鍵でトークンに署名し、公開鍵をWorkatoに登録します。 |
| HMAC（非推奨） | 対称共有シークレットを使用します。クライアントとWorkatoは同じ256ビットのシークレット文字列を使用します。 |
APIクライアントのJWT認証を設定
JWT認証を設定して安全なAPIアクセスを有効にするには、次の手順を実行します:
APIクライアントを作成
新しいクライアントを追加して設定するには、次の手順を実行します:
APIクライアントの追加
プラットフォーム＞API platformに移動します。
クライアントタブを選択します。
+ Add new clientをクリックします。
新規クライアントを追加
クライアント詳細の設定
クライアントの名前を入力します。クライアントの会社名や部門名など、わかりやすい識別子を使用します。
クライアント詳細のセットアップ
クライアントの説明を入力します。
クライアントロゴをアップロードします。 JPG/PNG画像をドラッグアンドドロップするか、Upload from deviceをクリックしてファイルを選択します。このロゴは、ポータル内でクライアントを視覚的に識別します。
ポータルアクセスを有効にするには、クライアントにポータルへのアクセスを許可トグルを有効にします。これにより、公開済みのAPIコレクションを参照し、APIキーを管理する権限がクライアントに付与されます。クライアントがテストまたは社内目的でAPIトークンのみを必要とする場合は、トグルを無効のままにできます。
ポータルの認証方法に基づいて、クライアントの識別情報を入力します:
次へをクリックしてアクセス設定を定義画面に進み、クライアントのAPIアクセスを設定します。
アクセス設定を定義
認証方法としてJSON Web Tokenを選択します。
任意です。相互TLS（mTLS）を適用をオンにして、SSLハンドシェイク中にクライアントが有効な証明書を提示することを必須にします。これにより、双方向認証が強制されます。詳細については、mTLS認証ガイドを参照してください。
注：この設定は、ワークスペースにカスタムドメインを設定している場合にのみ表示されます。
API collections to includeドロップダウンメニューを使用して、1つ以上のAPIコレクションを選択します。これにより、クライアントがポータルでアクセスおよび呼び出しできるAPIが定義されます。 APIアクセスを付与する前にディスカバリーを許可するため、コレクションなしでクライアントを作成することもできます。
任意です。クライアントのAPI利用状況を制御するために、ポリシーを割り当てます。ポリシーでは、レート制限や利用状況クォータなどのルールを定義します。
次へをクリックします。
認証を設定
トークン検証に必要なセキュリティ認証情報を設定するには、次の手順を実行します:
署名方法を選択します:
- RSA (公開鍵)（推奨）
- HMAC (非推奨)
署名方法を選択
選択した署名方法に基づいて、以下の該当する設定手順に従います:
公開鍵をRSA公開鍵フィールドに貼り付け
HMACシークレットを生成
シークレットをHMACシークレットフィールドに貼り付け次へをクリックしてクライアントを作成します。
ポータルアクセスが有効になっている場合、Workatoはクライアントのメールアドレスに招待メールを送信します。 APIコレクションや認証方法へのアクセスなどの権限は、クライアントレベルで設定されます。
アプリケーションの作成
次の手順を完了して、アプリケーションを作成し、API keyを生成します。クライアントは、このキーをJWTのkid（キーID）クレームとして含める必要があります。プラットフォームはこの値を使用して、クライアントとその署名方法を特定し検証します。
認証情報タイプとしてAPI keyを選択
この手順では、kidクレームとして埋め込むAPI keyが必要です。 Credential typeの入力を求められたら、API keyを選択します。カスタム検証ではキーが生成されないため、残りの手順で使用できるものは生成されません。
API Platform > Clientsに移動し、クライアントを選択して、Applicationsタブに移動します。
+ Create applicationをクリックします。
Create application（アプリケーションの作成）
アプリケーションを識別するために、Application name（アプリケーション名）を入力します。
Configure new application（新規アプリケーションの設定）
Credential type（認証情報タイプ）でAPI key（APIキー）を選択します。
CUSTOM VALIDATION（カスタム検証）
Workatoが発行したキーではなく、クレームとスコープのルールを使用してJWTトークンを検証するには、代わりにCustom validation（カスタム検証）を選択します。 Custom validation（カスタム検証）は、JWTまたはOpenID Connect認証方式を使用するクライアントでのみ利用できます。完全な設定手順については、APIアプリケーションのカスタム検証を参照してください。
次へをクリックします。
任意です。リクエストを特定のIPアドレスに制限するには、Allowed IPsを追加します。複数のIPを許可するには、カンマで区切るか、範囲を定義します。
IPアクセスルールの設定
任意です。特定のIPアドレスからのリクエストを防ぐには、Blocked IPsを追加します。ブロックされたIPは許可されたIPより優先されます。たとえば、IPアドレス123.456.123.456を許可リストに追加していてもブロックした場合、このIPアドレスからポータルにアクセスしようとするユーザーはアクセスを拒否されます。
Create applicationをクリックします。 Workatoに認証トークンが表示されます。このトークンは再度表示されないため、安全に保存してください。紛失した場合は、トークンを更新するか、新しいアプリケーションを作成する必要があります。
JSON Web Tokenを生成
JWTヘッダーにAPIキーをkid（キーID）クレームとして含めるJWTを作成し、署名します:
{
"alg": "RS256",
"typ": "JWT",
"kid": "<YOUR-API-KEY>"
}APIリクエストを開始するクライアントには、JWTに正しく署名する責任があります。プラットフォームは、認証とアクセスのためにこのトークンを検証します。
代替クレーム
この例では、Workato APIキーがkidクレームとしてヘッダーに含まれています。一部のIDプロバイダーでは、kidクレームが制限される場合があります。この場合、トークンのペイロードセクションで、次のいずれかのクレームの下にAPIキーを含めることができます: https://www.workato.com/sub、workato_sub、またはsub。
ユースケースでこれらのclaimが他の目的に使用されている場合、カスタムclaimを使用してAPI keyを保持できます。代替claimsについて詳しく見る.
APIキーを含むJWTを生成して署名するには、次の手順を実行します:
RS256を使用してJWTを生成
HS256を使用してJWTを生成IDプロバイダーを使用して、サポートされているクレームのいずれかにAPIキーが埋め込まれたJWTを発行することもできます。詳細については、JWT Workatoクレームを参照してください。
最終更新日: