SORACOM, INC.

User Console »
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(必須)

effect要素は、"allow"もしくは"deny"のいずれかの値がセットできます。必須要素となります。 この要素は、ステートメントブロックが許可(allow)を示すものか、拒否(deny)を示すものかをを設定する要素になります。 allowを指定すると、ステートメントブロックがマッチするAPI呼び出しが行われた場合、APIの利用を許可します。 逆にdenyを指定すると、他のパーミッション構文にAPI呼び出しにマッチするallowのステートメントブロックがあった場合でも、 APIの利用を拒否します。

api(必須)

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

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

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

サービス名、オペレーション名にはワイルドカードを利用することができます。

例:Subscriberサービスのlist系の操作をすべて対象にする

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

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

例:すべての操作を対象にする

    "api":"*"

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

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

例:Subscriberの一覧取得とグループ設定を対象にする

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

condition(オプション)

conditionは、IPアドレスや時刻などを使用して、ステートメントブロックがマッチする条件を指定できます。conditionはオプション要素となります。 例えば、以下のようなユースケースに適用できます。

ある特定の日時からAPIを利用可能にしたい
"condition":"currentDate >= date(2016,01,27)"
APIクライアントのIP制限をかけたい
"condition":"ipAddress('10.0.0.1/24')"
APIではなく、HTTPメソッドで指定したい
"condition":"httpMethod('GET')"

演算子

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')

これは、例えばGETメソッドのAPIのみを許可する、といった使い方が可能です。その場合のstatementは

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

となります。

また、引数は複数取ることができます。

例)

httpMethod('GET', 'POST')

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

演算子 not と組み合わせることも可能です。

例)

not httpMethod('DELETE')

例えば、以下のようなstatementでは、DELETEメソッドのAPIは許可しない、という評価になります。

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

これは、DELETEの場合はallowです。DELETEの場合は、デフォルトが全てdenyなので、結果的にdenyと評価されることになります。 ただ、この記述はわかりにくいので、引数を複数取れることを利用して、明示的に

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

と記述してもよいでしょう。


pagetop