Soracom

SAM ユーザーに権限を設定するときの書式のことを「パーミッション構文」と呼びます。

例: Sim:listSims API および Group:* API のすべてが、2021 年 2 月 1 日以降、IP アドレスレンジ 10.0.0.0/24 のクライアントから利用可能になる設定

{
  "statements": [
    {
      "effect": "allow",
      "api": [
        "Sim:listSims",
        "Group:*"
      ],
      "condition": "currentDate >= date(2021, 02, 01) and ipAddress('10.0.0.0/24')"
    }
  ]
}

パーミッション構文は、JSON フォーマットに従っています。ここでは、各プロパティの意味や、設定する内容を説明します。

API を指定する

ひとつの api プロパティの中に、複数の API を指定できます。

例:

"api": [
  "Sim:listSims",
  "Group:*"
]

: の前の部分を「サービス名」、: の後の部分を「オペレーション名」と呼びます。

「サービス名」および「オペレーション名」は、SORAOCM API リファレンス で確認できます。

特定の API を指定する

特定の API を指定する場合は、api にサービス名とオペレーション名を配列で指定します。

例: Sim:listSims API および Sim:getSim API を対象とする

"api": [
  "Sim:listSims",
  "Sim:getSim"
]

ワイルドカード (*) で複数の API をまとめて指定する

api に指定するサービス名とオペレーション名には、ワイルドカード (*) を指定できます。サービス単位などでまとめて API を指定したり、似たような機能を持つ API をまとめて指定するときに便利です。

• 例 1: サービス名が Sim:* API の API のうち、オペレーション名が list で始まる下記の API をすべて対象にする

  • Sim:listSims API
  • Sim:listSessionEvents API

  "api": [
    "Sim:list*"
  ]
  

• 例 2: サービス名が Subscriber:* API の API のうち、オペレーション名が SubscriberTransferToken で終わる下記の API をすべて対象にする

  • Subscriber:deleteSubscriberTransferToken API
  • Subscriber:issueSubscriberTransferToken API
  • Subscriber:verifySubscriberTransferToken API

  "api": [
    "Subscriber:*SubscriberTransferToken"
  ]
  

• 例 3: すべての API を対象にする

  "api": [
    "*"
  ]
  

"api": "*"

条件を指定する

condition には、IPv4 アドレスや API を呼び出した時刻などを使用して、ステートメントブロックが有効になる条件を指定できます。

演算子、変数、関数の 3 つを組み合わせて、条件を指定できます。

• 例 1: 2021 年 1 月 27 日 15:00:00 以降に、ステートメントブロックを有効にする

  "condition": "currentDate >= dateTime(2021, 01, 27, 15, 00, 00);"
  

• 例 2: クライアントの IPv4 アドレスが「10.0.0.0/24」に一致する場合に、ステートメントブロックを有効にする

  "condition": "ipAddress('10.0.0.0/24')"
  

• 例 3: HTTP メソッドが GET の場合に、ステートメントブロックを有効にする

  "condition": "httpMethod('GET')"
  

  したがって、以下のように指定すると、HTTP メソッドが GET のすべての API が許可されます。

  {
    "statements": [
      {
        "effect": "allow",
        "api": [
          "*"
        ],
        "condition": "httpMethod('GET')"
      }
    ]
  }
  

演算子

比較演算子、論理演算子を利用できます。

"condition": "not (samUserName eq 'example-user-name')"

比較演算子

文字列や数値を比較できます。

例:

"condition": "samUserName eq 'example-user-name'"

論理演算子

and、or、not を利用すると、複雑な条件を指定できます。

例:

"condition": "(samUserName eq 'example-user-name') and (currentDate eq date(2021,11,11))"

変数

ステートメントブロックを有効にする条件として、以下の変数を利用できます。

関数

ステートメントブロックを有効にする条件として、以下の関数を利用できます。

date(yyyy, MM, dd)

日付 (UTC) を表すオブジェクトを取得します。

引数:

戻り値:

日付 (UTC) を表すオブジェクトを返します。

例:

date(2021, 01, 27)

dateTime(yyyy, MM, dd, HH, mm, ss)

日時 (UTC) を表すオブジェクトを取得します。

引数:

戻り値:

日時 (UTC) を表すオブジェクトを返します。

例:

dateTime(2021, 01, 27, 15, 00, 00)

ipAddress(CIDR...)

API クライアントの IPv4 アドレスが、CIDR に指定した範囲に含まれているかどうかを判定します。

引数:

戻り値:

以下のいずれかの値を返します。

• true : API クライアントの IPv4 アドレスが、CIDR に指定した範囲のいずれかに含まれています。
• false : API クライアントの IPv4 アドレスが、CIDR に指定したどの範囲にも含まれていません。

例:

API クライアントの IPv4 アドレスが 10.0.1.0 ～ 10.0.1.255 の範囲に含まれる場合に、true を返します。

ipAddress("10.0.1.0/24")

API クライアントの IPv4 アドレスが 10.0.1.0 ～ 10.0.1.255 または 10.0.2.0 ～ 10.0.2.255 の範囲に含まれる場合に、true を返します。

ipAddress("10.0.1.0/24", "10.0.2.0/24");

httpMethod(method...)

API の HTTP メソッドが、methods に指定した HTTP メソッドと一致するかどうかを判定します。

引数:

戻り値:

以下のいずれかの値を返します。

• true : API の HTTP メソッドが、methods に指定した HTTP メソッドのいずれかと一致します。
• false : API の HTTP メソッドが、methods に指定したどの HTTP メソッドとも一致しません。

例:

httpMethod('GET', 'POST');

すべての API のうち GET メソッドおよび POST メソッドを使用する API のみを許可する場合の JSON は以下のとおりです。

{
  "statements": [
    {
      "effect": "allow",
      "api": "*",
      "condition": "httpMethod('GET', 'POST')"
    }
  ]
}

{
  "statements": [
    {
      "effect": "allow",
      "api": "*",
      "condition": "not httpMethod('DELETE')"
    },
    {
      "effect": "allow",
      "api": "*",
      "condition": "httpMethod('GET', 'POST', 'PUT')"
    }
  ]
}

pathVariable(placeholder)

API のパス中のプレースホルダーに指定した値を取得します。

たとえば、User:hasUserPassword API のように、パス中にプレースホルダー ({operator_id}、{user_name} などのこと) が含まれる API を呼び出したとき、プレースホルダー ({operator_id} や {user_name}) に指定した値を取得できます。

{
  "statements": [
    {
      "effect": "allow",
      "api": [
        "User:hasUserPassword",
        "Billing:getBilling"
      ],
      "condition": "pathVariable('user_name') == 'EXAMPLE-USER'"
    }
  ]
}

{
  "statements": [
    {
      "effect": "allow",
      "api": [
        "User:hasUserPassword"
      ],
      "condition": "pathVariable('user_name') == 'EXAMPLE-USER'"
    },
    {
      "effect": "allow",
      "api": [
        "Billing:getBilling"
      ]
    }
  ]
}

引数:

戻り値:

指定したプレースホルダーの値が String 型で返されます。

パスにプレースホルダーが含まれなかった場合は、'null' が返されます。

例:

SAM ユーザー EXAMPLE-USER のパスワードの更新 (User:updateUserPassword API の呼び出し) を許可する場合の JSON は以下のとおりです。

{
  "statements": [
    {
      "effect": "allow",
      "api": "User:updateUserPassword",
      "condition": "pathVariable('user_name') == 'EXAMPLE-USER'"
    }
  ]
}

これを samUserName と組み合わせると、SAM ユーザーが自分自身のパスワードのみを変更することを許可できます。このとき、他の SAM ユーザーのパスワードは変更できません。

{
  "statements": [
    {
      "effect": "allow",
      "api": "User:updateUserPassword",
      "condition": "pathVariable('user_name') == samUserName"
    }
  ]
}

使用例

condition に変数と関数を組み合わせた場合の使用例は以下のとおりです。

• 例 1: 2021 年 1 月 27 日以降に、ステートメントブロックを有効にする

  "condition": "currentDate >= date(2021, 01, 27)"
  

  数字が 1 桁の場合は、以下のように先頭の 0 は省略できます。

  "condition": "currentDate >= date(2021, 1, 27)"
  

• 例 2: 2021 年 1 月 27 日 15:00:00 以降に、ステートメントブロックを有効にする

  "condition": "currentDateTime >= dateTime(2021,01,27,15,00,00)"
  

• 例 3: 特定の IPv4 アドレス (10.0.0.1) からアクセスされた場合に、ステートメントブロックを有効にする

  "condition": "sourceIp == '10.0.0.1'"
  

  "condition": "sourceIp matches '10\.0\.0\.1'"
  

• 例 4: GET メソッドの API を呼び出す場合に、ステートメントブロックを有効にする

  "condition": "httpMethod == 'GET'"
  

• 例 5: 特定のユーザーが発行した API キーと API トークンを利用して API を呼び出す場合に、ステートメントブロックを有効にする

  "condition": "samUserName == 'EXAMPLE-USER'"
  

• 例 6: 特定のユーザーの情報に対する API 呼び出しの場合 (API パスにプレースホルダー {user_name} を含み、その値が特定のユーザーの場合) に、ステートメントブロックを有効にする

  "condition": "pathVariable('user_name') == 'EXAMPLE-USER'"