SORACOM Developers

Documents

Permission statements for configuring access permission

Introduction

SORACOM Access Management (SAM) makes it possible to control the permission of SAM users to access the User Console and the API.

The forms used to control access permission are referred to as “permission statements.”

The use of permission statements makes it possible to control access permission flexibly, specifying the contents described in the statements either by specifying permission directly to SAM users or else by specifying it to roles.


Permission statements

Permission statements are expressed in JSON format. JSON has a structure like the following:

Sample statement

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

“statements” is a route element into which the statement goes. There are three elements in “statements”: “api,” “effect,” and “condition.”

An object that contains these three elements is called a “statement block.”

In the example above, this means that all APIs and Group APIs to which the name of the Subscriber API list is attached become available for use by clients in IP address range 10.0.0.1/24 beginning February 1st, 2016.

Furthermore, because this API limitation is directly reflected on the User Console, it is possible to carry out operations on the list of Subscribers (an operation to obtain a list of SIMs) and on Groups at the User Console as well.

The individual elements of the statement block are explained below.

effect(required)

The “effect” element can be set either to the value “allow” or the value “deny.”

It is a required element. This element configures whether the statement block will show “allow” or “deny.” If “allow” is specified, then if an API invocation occurs that matches the statement block, the use of API will be allowed. If, conversely, “deny” is specified, then even if there is an “allow” statement block in another permission statement that matches an API invocation, the use of API will be denied.

api(required)

This specifies the API to which the statement block applies. It is a required element.

The value described in “api” is described in the form “Subscriber:listSubscribers.” The “Subscriber” part indicates the name of the service, while the “listSubscribers” part indicates the name of the operation.

The service name and operation name can be verified using the API reference. Service name and operation name

In the service name and operation name, wild cards can be used.

Example: Including all operations in the list of the Subscriber service

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

In addition, by abbreviating the service name to “*” it is possible to include all operations.

Example: Include all operations

    "api":"*"

However, even when all operations are included, operations that regard the Operator — such as modification of the Operator’s password or e-mail address — cannot be carried out.

Example: Make obtaining a list of Subscribers and obtaining Group settings the object

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

condition (optional)

“condition” can use items such as IP address or time of day to specify the condition for matching a statement block. “condition” is an optional element. It can, for example, be applied in situations like the following:

You wish to be able to use an API starting at a specific date and time
"condition":"currentDate >= date(2016,01,27)"
You wish to impose IP limitations on an API client
"condition":"ipAddress('10.0.0.1/24')"
You wish to specify not by API but by HTTP method
"condition":"httpMethod('GET')"

Operators

Operators can be used with “condition,” which permits the description of complex conditions. The following operators can be used:

Comparison operators
Logical operators
Arithmetic operators

Variables

Within “condition” the following variables can be used:

currentDate

Assigns the current date. It is primarily used in combination with the “date” function, which will be described below.

Example:

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

Assigns the current date and time. It is primarily used in combination with the “dateTime” function, which will be described below.

Example:

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

Assigns — as a character string — the IP address of the API client. To implement IP limitations, one can describe using operators such as “eq” and “match.”

Example:

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

If you wish to specify more flexibly, instead of IP address specification using a variable we recommend using the “ipAddress()” function, which will be described below.

httpMethod

Assigns — as a character string — the HTTP method of the API. It can be used, for example, to allow only GET operations.

Example:

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

If you desire even more flexible specification, we suggest specifying the “httpMethod()” function, which will be described below.

samUserName

Assigns — as a character string — the SAM user name that is under login (i.e. own SAM user name).

Example:

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

This variable makes flexible permission management with using pathVariable() function together.

Functions

Within “condition” the following functions can be used:

date(yyyy,MM,dd)

Example:

date(2016,01,27)

Arguments having one-digit numbers can be described either as “01” or as “1.”

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

Example:

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

Arguments having one-digit numbers can be described either as “01” or as “1.”

Note that “date(2016,01,27)” and “dateTime(2016,01,27,00,00,00)” have the same meaning.

ipAddress(CIDR…)

Determines whether the IP address of the API client falls within the specified range.

Example:

ipAddress('10.0.0.1/24')

The address is specified using CIDR notation. In the above example, the IP address is in the range 10.0.0.1–10.0.0.254.

The function can take multiple arguments.

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

Because the function is evaluated based upon the condition “OR,” in this case the IP address can be in the ranges 10.0.0.1–10.0.0.254 and 10.0.1.1–10.0.1.254.

httpMethod(methods…)

Determines whether the HTTP method of the API is one of the methods of the argument.

Example:

httpMethod('GET')

This can be used, for example, to allow only APIs using the GET method. In that case the statement would be as follows:

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

The function can also take multiple arguments.

Example:

httpMethod('GET', 'POST')

Because the function is evaluated based upon the condition “OR,” in this case the specification is for only APIs using the GET method or the POST method.

It can also be combined with the operator “not.”

Example:

not httpMethod('DELETE')

For example, in a statement like the following, the evaluation would be that APIs using the DELETE method are not allowed.

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

In this case DELETE is allowed. In the case of DELETE the default is to deny all, so the result is that the evaluation would be “deny.” Because this description is difficult to understand, it can be described more clearly taking advantage of the fact that the function can take multiple arguments:

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

This function returns the value of the placeholder of API path.

For example, API path definition is /operators/{operator_id}/users/{user_name}/password; and when actual API calling is /operators/OP9999999999/users/EXAMPLE-USER/password, pathVariable('operator_id') returns OP9999999999 and pathVariable('user_name') returns EXAMPLE-USER.

Example:

Following statement grants the permission to change the SAM user password only when user_name (i.e. SAM user name that is under login) equals EXAMPLE-USER.

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

This notation can grant the permission to change the SAM user password only owned when using samUserName variable together (i.e. it denies changing other SAM user’s password):

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

Please refer to the API Reference for API path and placeholder definitions.


Getting Started

SORACOM Air for Cellular

SORACOM Air for Sigfox

SORACOM Beam

SORACOM Canal/Direct/Door

SORACOM Endorse

SORACOM Funnel

SORACOM Gate

SORACOM Harvest

SORACOM Inventory

SORACOM Junction

SORACOM Krypton

SORACOM Lagoon

Service Detail

Developer Tools

pagetop