認証・認可

Qmonus SDKで開発されたAPIは、APIGWコンポーネントによって外部に公開されます。公開されたAPIを利用するためには、原則認証・認可を行う必要があります。 ただし、APIルーティングの公開スコープの設定によってQmonusの認証認可を無効化することもできます。ここでは認証認可を行うためのロールやユーザリソースについての解説とcurlコマンドを利用したAPI呼び出しのサンプルを紹介します。

ロール

ロールは、APIに対するアクセス制御に利用されます。アクセス可能なHTTP要求パスの正規表現とHTTPメソッドの集合として定義します。

ロールリソースは以下のパラメータを保有します。

属性	概要	備考
name	ロールの名称をユニークに定義します。	-
authorities	HTTP要求パスと当該要求パスに対してアクセスを許可するメソッドのリストを保有するオブジェクトをリストで定義します。	-

以下の例は、/apis/examples* にマッチするAPIのGETのみアクセスが許可されます。

- name: example
  authorities:
    - regex: /apis/examples*
      methods:
        - GET

アカウント

アカウントは、APIを利用するユーザです。1つ以上のロールに所属します。 アカウントを登録するとAPI鍵が払い出され、当該API鍵を使ってログオンAPIを要求することで認証トークンを取得することができます。

アカウントリソースは以下のパラメータを保有します。

属性	概要	備考
username	アカウントの名称をユニークに定義します。	-
password	アカウントのパスワードを定義します。	-
role	ロールを指定します。	複数指定可能です。
expire_days	アカウントの有効期限(生存日数)を定義します。	デフォルトは無期限です。

以下の例は、exampleロールを持つアカウントです。

- username: exampleUser
  password: example1234
  role: example

認証・認可の流れ

APIクライアントは、発行されたAPI鍵をX-Xaas-Api-Key拡張ヘッダにセットしてログオンAPIに対してアカウント名、アカウントパスワードをPOSTすることで認証トークンを取得する必要があります。取得した認証トークンをX-Xaas-Auth-Token拡張ヘッダにセットして各種APIを利用することができます。以下はシーケンスイメージです。

Step1. ログオンAPIにAPI鍵を指定してアカウント情報をPOSTし、認証トークンを取得する例です。

curl -i -X POST -H "Content-Type: application/json" -H "X-Xaas-Api-Key:WY43dLWJQWrkE9LDUvybBACJSBoNiN3pmSeRCccD6LtlHuyWkg6wyvoRnVaqoEek" -d '{"username":"exampleUser", "password":"example1234"}' localhost:9099/logon
HTTP/1.1 200 OK
Server: Qmonus/v21.2LTS-patch20210309
Content-Type: application/json
Date: Mon, 22 Mar 2021 05:14:42 GMT
Connection: close
Content-Length: 325

{"x-xaas-auth-token":"aVsOr4LLR5hruUC0BZw/t42mTLIq3w+SrEj/HISbTJ+Mo6gfUcxznHmCgqdJZXFKrkKQkBq4iQp8V5r77UeQ6FVh2+gJ7Gnz9d4o6cDNvbTzM0PCLbooQehdJmhJSaxGxPca+aFgabn3+Q1eC9OzqA==","expire":"2021-03-23T14:14:42.935056+09:00","limited":false,"role":{"name":"example","authorities":[{"regex":"/apis/examples*$","methods":["GET"]}]}}

Step2. HTTP要求ヘッダに X-Xaas-Auth-Token を設定し、目的のAPIを呼び出す例です。

curl -i -H "X-Xaas-Auth-Token:aVsOr4LLR5hruUC0BZw/t42mTLIq3w+SrEj/HISbTJ+Mo6gfUcxznHmCgqdJZXFKrkKQkBq4iQp8V5r77UeQ6FVh2+gJ7Gnz9d4o6cDNvbTzM0PCLbooQehdJmhJSaxGxPca+aFgabn3+Q1eC9OzqA==" localhost:9099/apis/examples
HTTP/1.1 200 OK
Server: Qmonus/v21.2LTS-patch20210309
Content-Type: application/json
Date: Mon, 22 Mar 2021 05:17:22 GMT
Connection: close
Etag: "d633b32b9233b47f29a10f1b61b53f32d1409882"
Content-Length: 85

[{"Example":{"instance":"RXhhbXBsZTpkZjI2NThhYzhhY2QxMWViOTM4ZGFjZGU0ODAwMTEyMg=="}}]

正しい認証トークンが指定されているにもかかわらず、HTTPメソッドの呼び出しがロールによって許可されていない場合、 401 Unauthorized が返されます。

curl -i -X DELETE -H "X-Xaas-Auth-Token:aVsOr4LLR5hruUC0BZw/t42mTLIq3w+SrEj/HISbTJ+Mo6gfUcxznHmCgqdJZXFKrkKQkBq4iQp8V5r77UeQ6FVh2+gJ7Gnz9d4o6cDNvbTzM0PCLbooQehdJmhJSaxGxPca+aFgabn3+Q1eC9OzqA==" localhost:9099/apis/examples
HTTP/1.1 401 
Server: Qmonus/v21.2LTS-patch20210309
Content-Type: application/problem+json
Date: Mon, 22 Mar 2021 05:19:02 GMT
Connection: close
Content-Length: 2

{}