SORACOM Developers

Documents

アクセス権限設定のためのパーミッション構文

はじめに

SORACOM Access Management(SAM)を利用すると、SAMユーザーに対してコンソールおよびAPIのアクセス権限の制御を行うことが可能になります。

このアクセス権限制御を行うための書式のことを、「パーミッション構文」と呼びます。

パーミッション構文を使って記述した内容をSAMユーザーに直接権限設定するか、もしくはロールに設定することで、アクセス権限の制御を柔軟に行うことができます。

ここでは、以下の項目に沿ってパーミッション構文について解説します。


パーミッション構文の構成

パーミッション構文は、JSON形式で表されます。JSONは以下の様な構造をとります。

構文例

{
    "statements":[
        {
            "effect":"allow",
            "api":["Subscriber:list*","Group:*"],
            "condition":"currentDate >= date(2016, 02, 01) and ipAddress('10.0.0.1/24')"
        }
    ]
}

“statements"が、中に構文が入るルート要素です。statementsの中には、"api”,“effect”,“condition"の3つの要素が入ります。 この3つの要素が入ったオブジェクトをステートメントブロックと呼びます。

パーミッションは複数のステートメントブロックから構成されます。この例ではステートメントブロックが1つですが、要素としては配列になっていることに注意して下さい。

上記の例では、Subscriber APIのlistの名前のつくAPIとGroup APIのすべてが、2016年2月1日以降、IPアドレスレンジ 10.0.0.1/24 のクライアントから利用可能になる、という意味になります。

またこのAPIの制限はそのままユーザーコンソールに反映されるため、コンソールでもSubscriberのlist(SIMの一覧を取得する操作)とグループに対する操作が可能になり、それ以外の操作はできません。

以下に、ステートメントブロックの各要素について説明をしていきます。

effect(必須):API実行の許可または拒否

effect要素は、"allow"もしくは"deny"のいずれかの値がセットできます。この要素はステートメントブロックの中で必須となります。

この要素は、ステートメントブロックがAPI実行を許可(allow)を示すものか、拒否(deny)を示すものかをを設定する要素です。

api(必須):対象API

ステートメントブロックが対象とするAPIを指定します。この要素はステートメントブロックの中で必須となります。

apiに記述する値は、"Subscriber:listSubscribers"のように記述します。"Subscriber"の部分はサービス名を示し、"listSubscribers"の部分はオペレーション名を示します。

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

特定の API を指定する

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

    "api":["Subscriber:listSubscribers"]

ワイルドカードで API を指定する

サービス名、オペレーション名には以下のようにワイルドカードで指定することもできます。サービス単位などでまとめて API を指定するにはワイルドカードを使うと便利です。

    "api":["Subscriber:list*"]

またサービス名を省略して”*“とすることで、すべての操作を対象にすることができます。

    "api":"*"

なお、すべてのAPIを対象にした場合でも、オペレーターのパスワード変更やメールアドレス変更などのオペレーターに対するAPIは実行できません。

複数 API を指定する

API をリスト形式で記述すると、複数のAPIを同時に指定することができます。リスト指定の場合は、OR で条件マッチを行います。

    "api":["Subscriber:listSubscribers","Group:*"],

condition(オプション):条件

conditionは、IPアドレスや時刻などを使用して、ステートメントブロックがマッチする条件を指定できます。conditionはオプション要素となりますので、指定してもしなくても構いません。

例えば、以下のようなユースケースに適用できます。

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

このように記述すると、「2016年1月27日以降」という条件指定になります。

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

IPアドレスが 10.0.0.1/24 の範囲内にあるものだけ、という指定になります。

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

HTTP GETメソッドのAPI、という指定になります。

演算子

conditionには演算子を使用することができ、複雑な条件を記述することができます。下記の演算子を利用できます。

比較演算子
論理演算子
数値演算子
変数

condition中には、下記の変数を利用できます。

currentDate

現在日が代入されています。おもに後述するdate関数と組み合わせて利用します。

例)

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

現在日時が代入されています。主に、後述するdateTime関数と組み合わせて利用します。

例)

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

APIクライアントのIPアドレスが文字列として代入されています。IP制限を行いたい場合に、eq や match 演算子を利用して記述する利用法があります。

例)

"condition":"sourceIp == '10.0.0.1'"
"condition":"sourceIp matches '10\.0\.0.*'"

より柔軟に指定したい場合は、変数を使ったIPアドレス指定よりも、後述のipAddress()関数を使用することを推奨します。

httpMethod

APIのHTTPメソッドが文字列として代入されています。例えばGET操作のみ許可する、といったような利用方法があります。

例)

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

また、より柔軟に指定したい場合は、後述のhttpMethod()関数を指定することを推奨します。

関数

condition中には、下記の関数を利用できます。

date(yyyy,MM,dd)

例)

date(2016,01,27)

1桁の数字の引数は 011 の両方が記述できます。

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

例)

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

1桁の数字の引数は 011 の両方が記述できます。

なお、date(2016,01,27)dateTime(2016,01,27,00,00,00)は同義です。

ipAddress(CIDR…)

APIクライアントのIPアドレスが指定範囲内になっているかを判定します。

例)

ipAddress('10.0.0.1/24')

アドレスはCIDR記法で指定します。上記の例では、IPアドレスが 10.0.0.1 ~ 10.0.0.254 の範囲となります。引数は複数指定できます。

ipAddress('10.0.0.1/24', '10.0.0.2/24')

OR条件で評価されますので、この場合はIPアドレスが 10.0.0.1 ~ 10.0.0.254 と 10.0.1.1 ~ 10.0.1.254 の範囲、ということになります。

httpMethod(methods…)

APIのHTTPメソッドが引数のmethodsになっているかを判定します。

例)

httpMethod('GET')

例えば、すべてのAPIのうちGETメソッドのAPIのみを許可する、といった使い方ができます。その場合のパーミッション構文は以下のようになります。

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

引数は複数指定できます。

例)

httpMethod('GET', 'POST')

引数はOR条件で評価されますので、この場合はGETとPOSTメソッドのAPIのみ、という指定になります。

演算子 not と組み合わせることもできます。例えば、以下のようなstatementでは、DELETEメソッドのAPIは許可しない、という評価になり、結果的にDELETEメソッド以外すべてのAPI実行がallow(許可)と評価されます。

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

ただ、この記述はわかりにくいので、引数を複数取れることを利用して、明示的に

"condition":"httpMethod('GET', 'POST', 'PUT')"

と記述する方が分かりやすくなります。


パーミッション構文の例

パーミッション構文の例はよくあるご質問をご覧ください。

pagetop