REST API でのトークン・ベースの認証の使用

REST API のユーザーは、 REST API login リソースに HTTPでユーザーIDとパスワードを提供することで認証を行うことができます。ユーザーが今後の要求を認証できるようにする LTPA トークンが生成されます。この LTPA トークンの接頭部は、LtpaToken2 です。 HTTP DELETE メソッドを使用するとログアウトでき、HTTP GET メソッドを使用すると現行ユーザーのログイン情報を照会できます。

始める前に

REST APIの使用を許可されるようにユーザー、グループ、および役割を構成します。詳細については、ユーザーとロールの設定を参照してください。
LTPA トークンが含まれる Cookie の名前のデフォルトは、先頭が LtpaToken2 で、mqweb サーバーの再始動時に変更される可能性がある接尾部が付きます。このように Cookie 名がランダム化されているので、複数の mqweb サーバーを同一のシステム上で実行できます。しかし、Cookie 名を一定の値にしておく場合は、setmqweb コマンドを使用して Cookie の名前を指定することができます。詳しくは、 LTPA トークンの構成を参照してください。
デフォルトでは、LTPA トークンの Cookie は 120 分後に有効期限が切れます。 LTPA トークンの Cookie の有効期限の時間は、setmqweb コマンドを使用して構成できます。詳しくは、 LTPA トークンの構成を参照してください。
REST 要求を送信するときは、セキュア接続を使用していることを確認してください。 login リソースで HTTP POST メソッドを使用するとき、要求とともに送信されるユーザー名とパスワードの組み合わせは暗号化されません。そのため、 REST API でトークンベースの認証を使用する場合は、セキュアな接続 HTTPS を使用する必要があります。デフォルトでは、HTTP を LTPA トークン認証で使用することはできません。 secureLTPA を False に設定することによって、セキュアでない HTTP 接続で LTPA トークンを使用できます。詳しくは、 LTPA トークンの構成を参照してください。
login リソースに対する HTTP GET メソッドを使用することにより、現行ユーザーの資格情報を照会できます。このメソッドを使用する際、その要求を認証するための LTPA トークンを指定する必要があります。この要求は、ユーザー名、およびユーザーに割り当てられている役割に関する情報を返します。詳しくは、 GET /loginを参照してください。

手順

ユーザーをログインします。
1. login リソースHTTP メソッドを使用します。
```
https://host:port/ibmmq/rest/v1/login
```
  JSON 要求の本体にユーザー名とパスワードを、以下の形式で組み込みます。
```
{
    "username" : name,
    "password" : password
}
```
2. その要求から返された LTPA トークンをローカル Cookie ストアに保管します。デフォルトでは、この LTPA トークンの接頭部は LtpaToken2です。
すべての要求の Cookie として、保管した LTPA トークンを使用して、REST 要求の認証を行います。
HTTP の PUT、PATCH、DELETE のいずれかのメソッドを使用する要求には ibm-mq-rest-csrf-token ヘッダーを組み込みます。このヘッダーの値は、ブランクでも他のどんな値でも構いません。
ユーザーをログアウトします。
1. login リソースに対して HTTPを使用します。
```
https://host:9443/ibmmq/rest/v1/login
```
  要求の認証を行うための Cookie として LTPA トークンを指定する必要があります。ibm-mq-rest-csrf-token ヘッダーも組み込んでください。このヘッダーの値は、ブランクでも他のどんな値でも構いません。
2. ローカルの Cookie ストアから LTPA トークンを削除するための命令を処理します。
  
  注: 命令が処理されず、LTPA トークンがローカル Cookie ストアに残っている場合は、LTPA トークンを使用して将来の REST 要求を認証できます。つまり、セッションの終了後にユーザーがその LTPA トークンを使用して認証を試みると、既存のトークンを使用する新しいセッションが作成されます。

例

以下の cURL の例は、 Windows システムで、トークン・ベースの認証を使用して、キュー・マネージャー QM1に新しいキュー Q1を作成する方法を示しています。

ログインして、接頭部が LtpaToken2 の LTPA トークンをローカルの Cookie ストアに追加します。ユーザー名とパスワード情報は JSON 本体に組み込まれています。 -c フラグはトークンを保管するファイルの場所を指定するためのフラグです。
```
curl -k https://localhost:9443/ibmmq/rest/v1/login -X POST 
-H "Content-Type: application/json" --data "{\"username\":\"mqadmin\",\"password\":\"mqadmin\"}" 
-c c:\cookiejar.txt
```
キューを作成します。キュー・リソースを使用して HTTP POST メソッドを実行し、LTPA トークンで認証を行います。接頭部が LtpaToken2 の LTPA トークンは、 -b フラグを使用して cookiejar.txt ファイルから取得されます。 ibm-mq-rest-csrf-token HTTP ヘッダーを組み込むことによって、CSRF 保護を指定します。
```
curl -k https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM1/queue -X POST -b 
c:\cookiejar.txt -H "ibm-mq-rest-csrf-token: value" -H "Content-Type: application/json" 
--data "{\"name\":\"Q1\"}"
```
ローカルの Cookie ストアからログアウトし、LTPA トークンを削除します。 LTPA トークンは、 -b フラグを使用して cookiejar.txt ファイルから取得されます。 ibm-mq-rest-csrf-token HTTP ヘッダーを組み込むことによって、CSRF 保護を指定します。以下のように、cookiejar.txt ファイルの場所は -c フラグによって指定されるため、LTPA トークンはファイルから削除されます。
```
curl -k https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM1/queue -X DELETE 
-H "ibm-mq-rest-csrf-token: value" -b c:\cookiejar.txt 
-c c:\cookiejar.txt
```