NTT Com APIゲートウェイの「権限管理機能」を使ってみよう！

2015年9月10日に、NTT Com APIゲートウェイ 権限管理機能をリリースしました。

本機能を利用することで、お客さまご自身でNTT Com APIに対するアクセス制御が設定できます。

アクセス制御は以下の通りきめ細かに設定できますので、お客さま個々の業務用件を満たす柔軟なアクセス制御が可能となります。

• API単位

  アクセス権限の対象として複数のAPIを指定することができます。さらに詳細な設定としてREST APIのメソッド(GET/POST/PUT/DELETE)や、リソースパスも指定することが可能です。

• IPアドレス単位

  お客様が利用されるアクセス元IPアドレスを複数指定することができます。

• 任意のデータ単位

  JSONペイロードやヘッダのうち、利用を許可したいデータをキー、バリューの組み合わせにて指定することができます。これによって、契約情報やサービス名などを個別に権限設定することで、より強固なアクセス制御を実施することが可能です。

権限管理機能の操作手順

権限管理機能の操作手順は以下の通りです。

1. ユーザ・グループを作成する
2. 権限を作成する
3. グループと権限を紐づける

なお、上記操作は「権限管理(IAM)API」を使います。詳細はAPI Docsをご確認ください。

実際に権限管理機能を使ってみる

それでは実際に権限管理機能を使ってみましょう。

今回はBusiness Process APIに対して様々な権限管理を設定してみます。

Business Process APIとは、NTT Com各種サービスのビジネスプロセスに関する情報提供や、操作を可能とするAPIです。契約情報API、サービスオーダーAPI、チケットAPI、メンテナンスAPIがあります。

契約情報APIにアクセスできるようにする

まずはBusiness Process APIの一つである契約情報APIにアクセスできるユーザを作成してみます。

手順は以下の通りです。

1. 準備

   権限管理機能を利用するには、ビジネスポータルからお申込頂くデベロッパポータルのアカウント（以降、権限管理者）が必要です。もしお持ちでない方はこちらからお申込みください。

   API利用のための認証情報の取得

   以下の通り権限管理者でOAuth APIにアクセスし、accessTokenを取得します。今回はhttpieというツールを使ってAPIにアクセスしています。

   リクエスト

   権限管理者のclientIdとclientSecretを入力してaccessTokenを取得します。clientIdとclientSecretはデベロッパポータルから確認できます。

   http -v POST https://api.ntt.com/v1/oauth/accesstokens grantType=client_credentials clientId=[権限管理者のConsumerKey] clientSecret=[権限管理者のConsumerSecret]    
   

   レスポンス

   以下のようなレスポンスが返ってきますので、accessTokenをメモしておきます。

   {
       "accessToken": "[権限管理者のaccessToken]", 
       "expiresIn": "86399", 
       "issuedAt": "1441957092928", 
       "scope": "READ WRITE", 
       "tokenType": "BearerToken"
   }
   

2. ユーザを作成する

   契約情報APIにアクセスできるユーザを、権限管理APIを使って作成します。この操作も権限管理者で実施してください。

   ユーザ(userA@example.com)の作成

   リクエスト

   http -v POST https://api.ntt.com/v1/iam/users
       "Authorization: Bearer [権限管理者のaccessToken]" \ 
         mail=userA@example.com \ 
         portalUse=1  \        # デベロッパポータルの利用を許可する場合は"1"を入力
         password=****** \     
         distributorFlag=0
   

   レスポンス

   正常にユーザが作成されると、以下のようなレスポンスが返ります。

   {
       "users": [
           {
               "consumerKey": "[userAのConsumerKey]", 
               "consumerSecret": "[userAのConsumerSecret]", 
               "distributorFlag": 0, 
               "mail": "userA@example.com", 
               "portalUse": 1, 
               "uuid": "[userAのuuid]"
           }
       ]
   }
   

   以上でユーザ作成は完了です

3. グループを作成する

   次にユーザが所属するグループを作成します。この操作も管理者権限で実施してください。

   グループ（groupA）の作成

   リクエスト

       http -v POST https://api.ntt.com/v1/iam/groups "Authorization: Bearer [権限管理者のaccessToken]" \
         groupName=groupA
   

   レスポンス

   {
       "groups": [
           {
               "groupName": "groupA", 
               "roles": [], 
               "uuid": "[groupAのuuid]"
           }
       ]
   }
   

   ユーザをグループに紐づける

   作成が終わったら、ユーザをグループに紐付けます。複数のユーザを同じグループに紐づけることもできます。

   リクエスト

   groupIdとuserIdは上記手順で取得したuuidを指定してください。

   http -v PUT https://api.ntt.com/v1/iam/groups/[groupAのuuid]/users/[userAのuuid] "Authorization: Bearer[権限管理者のaccessToken]"
   

   レスポンス

   {
       "groups": [
        {
            "users": [
                {
                   "userId": "[userAのuuid]"
                }
               ], 
               "uuid": "[groupAのuuid]"
           }
    ]
   }
   

4. 権限を作成する

   いよいよ権限の作成です。

   今回はBusiness Process APIで提供されるAPIのうち、契約情報APIだけアクセスできる権限(roleA)を作成します。

   なお権限付与はホワイトリスト形式で指定します。デフォルトでALL DENYになっているので、リソースに対して許可したい値を権限に追加していく形になります。全て許可したい場合はワイルドカードを指定してください。

   なお、本操作も権限管理者で実施してください。

   リクエスト

   http -v POST https://api.ntt.com/v1/iam/roles "Authorization: Bearer [権限管理者のaccessToken]" \
           resources:='[basePath:=/v1/business-process, ipAddress:=*, path:=/contracts, verb:=*, "ipAddress": "*"]'\
         　　　roleName:=roleA
   

   レスポンス

   {
     "roles": [
         {
             "resources": [
                   {
                       "basePath": "/v1/business-process", 
                       "ipAddress": "*", 
                       "path": "/contracts", 
                       "verb": "*"
                   }
               ], 
               "roleName": "roleA", 
               "uuid": "[roleAのuuid]"
           }
       ]
   }
   

   グループと権限を紐づける

   最後にグループと権限を紐付けます。この設定によってユーザは契約情報APIにアクセスできるようになります。

   リクエスト

   http -v PUT https://api.ntt.com/v1/iam/groups/[groupAのuuid]/roles/[roleAのuuid] "Authorization: Bearer[権限管理者のaccessToken]"
   

   以上で設定完了です。ここまで約５分！

5. 契約情報APIにアクセスしてみる

   それでは作成したユーザで契約情報APIにアクセスしてみます。

   ユーザでOAuth認証を行う

   リクエスト
   ここからは作成したユーザでアクセスしてください。

   http -v POST https://api.ntt.com/v1/oauth/accesstokens grantType=client_credentials clientId=[userAのConsumerKey] clientSecret=[userAのConsumerSecret] 
   

   レスポンス

   {
     "accessToken": "[userAのACCESS_TOKEN]", 
       "expiresIn": "86399", 
       "issuedAt": "1441869735683", 
       "scope": "READ WRITE", 
       "tokenType": "BearerToken"
   }
   

   契約情報を参照してみる

   リクエスト（ネットワークサービス"UNO"の例）

   http -v GET https://api.ntt.com/v1/business-process/contracts?serviceName=uno" "Authorization: Bearer [userAのACCESS_TOKEN]"
   

   レスポンス

   {
     "items": [
         {
           "accessLineSet": , 
               "accountId": *********, 
               "cRef": *********, 
               "contractId": "N********", 
               "distinguishName": *********, 
               "internalContractId": *********, 
               "mainBack": *********, 
               "mainBackGroup": *********, 
               "optionType": *********, 
               "serviceName": "*********", 
               "serviceStatus": *********, 
               "site": *********, 
               "vpnGroupId": "V*******"
           }, 
           {
               "accessLineSet": *********, 
               以下略
   

   同様に他のサービスオーダーを確認したいときは、contracts?serviceName=****に確認したいサービス名を入力して参照してください。

特定サービスの契約情報だけ参照できるようにする

上に書いた手順で、契約情報APIにアクセスし新規契約情報を登録したり参照したりすることができるユーザを作成できました。

しかしながら実際の業務では、特定のサービスに関する契約情報だけを参照させたいケースや、参照はできるが更新や削除はできないようにしたいケースなどがあると思います。

このようなケースにも柔軟に対応できることが、今回の権限管理機能の特徴でもあります。

そこで次は、特定サービス(UNO)の契約情報だけ参照できる（更新や削除はできない）ように権限を変更してみたいと思います。

権限（ロール）を変更する

先ほど作成した権限(roleA)を以下の通り変更します。

• serviceNameに、unoを指定
• verbをGET(参照)のみに変更

リクエスト

    http -v PUT https://api.ntt.com/v1/iam/roles/[roleAのuuid] "Authorization: Bearer [権限管理者のACCESS_TOKEN]" roleName=roleA  resources:='[{"basePath":"/v1/business-process","path":"/contracts", "serviceName":"uno", "verb":"GET", "ipAddress":"*"}]'

レスポンス

    {
        "roles": [
            {
                "resources": [
                    {
                        "basePath": "/v1/business-process", 
                        "ipAddress": "*", 
                        "path": "/contracts", 
                        "serviceName": "uno", 
                        "verb": "GET"
                 }
                ], 
                "roleName": "roleA", 
                "uuid": "[roleAのuuid]"
            }
        ]
    }

UNO以外の契約情報APIにアクセスしてみる

レスポンス

    {
        "errorCode": "403", 
        "errorMessage": "You do not have permission to the API."
    }

このように、パーミッションエラーが表示されアクセスできないように制御できます。

契約情報API以外のAPIへもアクセスできるようにする

次に、契約情報以外のAPIへもアクセスできるように設定してみます。
追加するAPIはサービスオーダーAPIです。
今回は契約情報APIとサービスオーダーAPIにアクセスできるようにする(=or条件)ため、権限(roleA)に新たなresourcesを追加するように設定します。
グループと権限の関係性についてはAPI Docsに詳細を記載してありますのでご確認ください。

リクエスト

http -v  PUT https://api.ntt.com/v1/iam/roles/[roleAのuuid] "Authorization: Bearer [権限管理者のaccessToken]" roleName=roleA  resources:='[{"basePath":"/v1/business-process","path":"/contracts", "serviceName":"uno","verb":"GET"}, {"basePath":"/v1/business-process","path":"/service-orders", "serviceName":"*", "verb":"*"}]'

レスポンス

{
    "roles": [
        {
            "resources": [
                {
                    "basePath": "/v1/business-process", 
                    "path": "/contracts", 
                    "serviceName": "uno", 
                    "verb": "GET"
                }, 
                {
                    "basePath": "/v1/business-process", 
                    "path": "/service-orders", 
                    "serviceName": "*", 
                    "verb": "*"
                }
            ], 
            "roleName": "roleA", 
            "uuid": "[roleAのuuid]"
        }
    ]
}

サービスオーダーAPIへアクセスする

それでは追加したサービスオーダーAPIへアクセスしてみます。

リクエスト

    http -v GET https://api.ntt.com/v1/business-process/service-orders?serviceName=uno" "Authorization: Bearer [userAのACCESS_TOKEN]"

レスポンス

    {
       "items":
        [
            {
            　"contractId":"N********",
            　"serviceName":"********",
            　"orderType":1,
            　"offerPlanDate":"********",
            　"orderStatus":1
            　"orderRequestNum":"************"
            }
        ]
        "resultCount":1
    }

このようにサービスオーダーAPIにもアクセスできるようになりました。

特定の場所からだけ契約情報APIにアクセスできるようにする

利用するユーザによってアクセスできるリソースを限定することができましたが、現在の設定ではどこからでも契約情報APIやサービスオーダーAPIにアクセスできてしまいます。外出先や自宅などからはリソースにアクセスさせたくないケースもあるかと思います。
次は社内など特定の場所からだけ契約情報APIにアクセスできるように設定してみます。

新たな権限(roleB)を作成する

リクエスト

http -v  POST https://api.ntt.com/v1/iam/roles "Authorization: Bearer [権限管理者のaccessToken]" roleName=roleB resources:='[{"ipAddress":"192.168.1.100"}]'

レスポンス

{
    "roles": [
        {
            "resources": [
                {
                    "ipAddress": "192.168.1.100"
                }
            ], 
            "roleName": "roleB", 
            "uuid": "[roleBのuuid]"
        }
    ]
}

権限(roleB)をグループに紐付ける

リクエスト

http -v  PUT https://api.ntt.com/v1/iam/groups/[groupAのuuid]/roles/[roleBのuuid] "Authorization: Bearer [権限管理者のaccessToken]"

レスポンス

{
    "groups": [
        {
            "groupName": "groupA", 
            "roles": [
                {
                    "roleId": "[roleAのuuid]"
                }, 
                {
                    "roleId": "[roleBのuuid]"
                }
            ], 
            "uuid": "[groupAのuuid]"
        }
    ]
}

許可されていない場所からAPIにアクセスすると、パーミッションエラーが表示されます。

    {
        "errorCode": "403", 
        "errorMessage": "You do not have permission to the API."
    }

今回はBusiness Process APIに対して権限設定を実施してみました。
次回以降、弊社のクラウドサービスやネットワークサービスにおける権限管理の設定例を随時紹介していく予定です。お楽しみに。