カスタム認可 ​

カスタム認可を使用すると、セキュリティを強化するためにAPIエンドポイントに追加の認可クレームセットを適用できます。 APIリクエストがエンドポイントに対して行われ、有効なトークンで認証された後、WorkatoのAPI Gatewayはカスタム認可式を評価します。 リクエストは、クレーム式がtrueと評価された場合にのみ認可されます。

この機能により、ロールベースのアクセス制御、ロケール制限、カスタムビジネスロジックなどのセキュリティ対策を適用できます。

カスタム認可の設定 ​

APIエンドポイントのカスタム認可を設定するには、次の手順を実行します。

APIリクエストデータピルの参照 ​

カスタム認可式を設定するときは、データピルを使用して、コンテキスト、リクエスト、JWTトークンなど、APIリクエストのさまざまなセグメントを参照できます。 対象とする正確な属性またはキーを指定し、Workato Formulaを使用してロジックを適用するか、受信データを検証します。

次のセクションでは、この構造を特定のシナリオに適用し、カスタム認可Formulaで主要なAPIリクエストデータピルにアクセスして検証する方法を示します。

検証FormulaのJWTクレーム ​

JWTクレームを検証するには、次の構造を使用できます。

JWTクレームの参照

このFormulaの例では、scopeクレームにUsers.readが含まれているかどうかを確認し、次のコンポーネントを使用します。

• JWTクレーム: トークン内のJWTクレームを参照するデータピル。
• scope: 特定のクレームを参照するフィールド。
• .include?('Users.read'): scopeクレームにUsers.read権限が含まれているかどうかを確認するメソッド。

検証Formulaのヘッダー ​

ヘッダー名は、正規のヘッダーキー命名規則に従います。 my-headerなどのリクエストヘッダーは、My-Headerのように適切な大文字小文字で参照する必要があります。 例:

ヘッダーの参照

このFormulaは次のコンポーネントを使用します。

• ヘッダー: リクエスト内のヘッダーを参照するデータピル。
• My-Header: 特定のヘッダーを参照するフィールド。
• .present?: リクエストにヘッダーが存在するかどうかを確認するメソッド。

検証Formulaのクエリパラメーター ​

クエリパラメーターは、配列内に複数の値を含めることができるキーと値のペアです。 Formulaでクエリパラメーターの値を参照するには、配列内での位置を指定する必要があります。 たとえば、クエリパラメーターの最初の値にアクセスするには、次のスクリーンショットに示すように.first Formulaを使用します。

クエリパラメーターの参照

このFormulaは次のコンポーネントを使用します。

• クエリ: リクエスト内のクエリパラメーターを参照するデータピル。
• param: クエリパラメーターを指定するフィールド。
• .first.starts_with?("value"): クエリパラメーター配列内の最初の値を取得し、それが文字列valueで始まるかどうかを確認するメソッド。

サポートされているFormula ​

カスタム認可式を設定する際は、限定されたWorkato Formulaのセットがサポートされています。 このリストはすべてを網羅しているわけではなく、ここで指定されているもの以外のRubyメソッドもサポートされる場合があります。 新しいFormulaをリクエストするには、Customer Success Managerにお問い合わせください。

式では次のものを使用できます。

• 演算子

• Formula内の値を比較するには、==、!=、>、>=、<、および<=を使用します。 これらの演算子を使用すると、Formula内の数値、文字列、またはブール値を評価できます。

• 数学演算子

• 式で基本的な算術演算を実行するには、+、-、*、/、%、および**を使用します。

• 論理式

• Formula内で複数の条件を組み合わせるには、&&（AND）および||（OR）を使用します。

• 時間単位

• 式で時間間隔を指定するには、seconds、minutes、hours、days、months、およびyearsを使用します。

• now

• nowを使用すると、ランタイム時の現在の日付と時刻を太平洋時間（PT）で返します。

• today

• todayを使用すると、ランタイム時の現在の日付を太平洋時間（PT）で返します。

• strftime

• strftimeを使用すると、日時入力をユーザー定義の文字列としてフォーマットします。

• ago

• agoを使用すると、指定した期間に基づいて過去のタイムスタンプを返します。

• to_i

• to_iを使用すると、日時値をエポック時刻（Unixエポックからの秒数）に変換します。

• present

• present?を使用すると、入力に値が存在するかどうかを確認します。 このメソッドは、入力に値が含まれている場合はtrueを返し、nil、false、空の文字列、または空のリストの場合はfalseを返します。 たとえば、present?を使用して、追加の検証を行う前にクレームが存在することを確認します。

• include?

• include?を使用すると、文字列に特定の部分文字列が含まれているかどうかを確認します。 たとえば、include?を使用して、ロールまたは権限がクレーム内に存在するかどうかを確認します。

• starts_with?

• starts_with?を使用すると、文字列が特定の部分文字列で始まるかどうかを確認します。 たとえば、starts_with?を使用して、メールクレームが特定のドメインで始まるかどうかを確認します。

• ends_with?

• ends_with?を使用すると、文字列が特定の部分文字列で終わるかどうかを確認します。 たとえば、ends_with?を使用して、クレームが既知のサフィックスで終わることを検証します。

• length

• lengthを使用すると、空白を含め、入力文字列内の文字数を返します。 たとえば、lengthを使用して、クレームが長さの要件を満たしているかどうかを確認します。

• upcaseまたはdowncase

• upcaseを使用するとテキストを大文字に変換し、downcaseを使用するとテキストを小文字に変換します。

• split

• splitを使用すると、指定した文字を基準に文字列を分割し、部分文字列の配列を返します。

• null

• Workato Formulaで空またはnil値を表すには、nullを使用します。 これにより、クレームまたはフィールドが存在しないかどうかを確認できます。これは文字列、数値、またはリストで一般的に使用されます。

• trueまたはfalse

• ブール値を検証するには、trueまたはfalseを使用します。 たとえば、trueを使用して、ユーザーに特定のロールが有効化されているかどうかを確認します。

Formulaの例 ​

次の例は、アクセスルールの適用やAPIリクエスト内の条件の検証など、さまざまな目的でカスタム認可を使用する方法を示しています。

ロールベースのアクセス ​

次のFormulaは、ユーザーがadminロールまたはuser:writeロールのいずれかを持っているかどうかを確認します。 システムは、rolesクレームが存在し、ユーザーがこれらのロールのいずれかを持っている場合にのみ続行します。

claims['roles'].present? && (claims['roles'].include?('admin') || claims['roles'].include?('user:write'))

エンドポイントアクセスをadminロールを持つユーザーに制限するには、次のFormulaを使用します。

claims['roles'].include?('admin')

ロケールの適用 ​

次のFormulaは、en-USロケールを持つユーザーのみがエンドポイントにアクセスできるようにします。 ロケールクレームが一致しない場合、システムはリクエストを拒否します。

claims['locale'] == 'en-US'

エラー処理 ​

クレームがfalseと評価されると、システムはリクエストを拒否し、401 Unauthorizedエラーコードを返します。 評価または解析できないクレーム式も401 Unauthorizedエラーを返し、エラーに関する具体的な詳細が含まれます。