2.2. 認証
Red Hat Virtualization Manager アカウントを持つユーザーは、API にアクセスできます。すべての要求は、以下で説明するように OAuth または Basic 認証を使用して認証する必要があります。
2.2.1. OAuth 認証
Red Hat Virtualization バージョン 4.0 以降、RFC 6749 に説明されているように、推奨の認証メカニズムは OAuth 2.0 です。
OAuth は高性能なプロトコルであり、認可およびアクセストークンを取得するメカニズムがいくつかあります。Red Hat Virtualization API と合わせて使用する場合は、RFC 6749 で説明されているように、Resource Owner Password Credentials Grant (リソース所有者のパスワード認証情報の付与) のみがサポートされます。
最初に トークン を取得し、ユーザー名とパスワードを Red Hat Virtualization Manager のシングルサインオンサービスに送信する必要があります。
POST /ovirt-engine/sso/oauth/token HTTP/1.1 Host: myengine.example.com Content-Type: application/x-www-form-urlencoded Accept: application/json
リクエスト本文には、grant_type、scope、username、および password パラメーターが含まれている必要があります。
| 名前 | 値 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
これらのパラメーターは URL でエンコード されている必要があります。たとえば、ユーザー名の @ 文字を %40 としてエンコードする必要があります。結果のリクエスト本文は以下のようになります。
grant_type=password&scope=ovirt-app-api&username=admin%40internal&password=mypassword
scope パラメーターは OAuth RFC で任意として説明されていますが、Red Hat Virtualization API と併用する場合は必須であり、この値は ovirt-app-api である必要があります。
ユーザー名とパスワードが有効な場合、Red Hat Virtualization Manager のシングルサインオンサービスは、以下のような JSON ドキュメントで応答します。
{
"access_token": "fqbR1ftzh8wBCviLxJcYuV5oSDI=",
"token_type": "bearer",
"scope": "...",
...
}
API 認証の目的で、関連する唯一の名前/値のペアは access_token です。これは操作しないでください。SSO サービスが提供するとおりに使用してください。
トークンを取得すると、HTTP Authorization ヘッダーにトークンを追加して、Bearer スキームで API への要求を実行するために使用できます。たとえば、仮想マシンのリストを取得するには、以下のような要求を送信します。
GET /ovirt-engine/api/vms HTTP/1.1 Host: myengine.example.com Accept: application/xml Authorization: Bearer fqbR1ftzh8wBCviLxJcYuV5oSDI=
トークンは、複数の要求に対して複数回使用できますが、最終的に期限切れになります。期限が切れると、サーバーは 401 HTTP 応答コードで要求を拒否します。
HTTP/1.1 401 Unauthorized
これが生じる場合は、Red Hat Virtualization Manager のシングルサインオンサービスは現在トークンの更新をサポートしていないため、新しいトークンが必要です。上記と同じ方法を使用して新しいトークンを要求できます。
2.2.2. Basic 認証
Basic 認証は後方互換性としてのみサポートされます。Red Hat Virtualization のバージョン 4.0 以降は非推奨となり、今後削除されます。
各要求は、HTTP Basic 認証を使用して [1] 認証情報をエンコードします。要求に適切な Authorization ヘッダーが含まれていない場合には、サーバーは 401 Authorization Required 応答を送信します。
HEAD /ovirt-engine/api HTTP/1.1 Host: myengine.example.com HTTP/1.1 401 Authorization Required
要求は、指定したレルムの Authorization ヘッダーで発行されます。username@domain:password 規則を使用して、提供された認証情報で適切な Red Hat Virtualization Manager ドメインおよびユーザーをエンコードします。
下記の表には、Base64 認証情報をエンコードするためのプロセスをまとめています。
| 項目 | 値 |
|---|---|
| ユーザー名 |
|
| ドメイン |
|
| パスワード |
|
| エンコードされていない認証情報 |
|
| Base64 エンコードされた認証情報 |
|
Base64 でエンコードされた認証情報を以下のように指定します。
HEAD /ovirt-engine/api HTTP/1.1 Host: myengine.example.com Authorization: Basic YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA== HTTP/1.1 200 OK
Basic 認証では、パスワードなどの機密情報がプレーンテキストで送信される可能性があります。API では、プレーンテキスト要求のトランスポートレベルの暗号化に Hypertext Transfer Protocol Secure (HTTPS) が必要です。
Base64 ライブラリーによっては、結果を複数行に分割して、行末には改行文字をつけます。これによりヘッダーが破損し、要求に問題が発生します。Authorization ヘッダーには、エンコードされた認証情報がヘッダー内に一行で記載されている必要があります。
2.2.3. 認証セッション
API は認証セッションサポートを提供します。認証情報で最初の要求を送信し、次にセッションクッキーを使用して後続のすべての要求を送信し、認証を行います。
2.2.3.1. 認証されたセッションの要求
AuthorizationおよびPrefer: persistent-authヘッダーを使用して要求を送信します。HEAD /ovirt-engine/api HTTP/1.1 Host: myengine.example.com Authorization: Basic YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA== Prefer: persistent-auth HTTP/1.1 200 OK ...
これは、以下のヘッダーで応答を返します。
Set-Cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK; Path=/ovirt-engine/api; Secure
JSESSIONID=の値を書き留めておきます。この例では、値は5dQja5ubr4yvI2MM2z+LZxrKです。JSESSIONID=の値でPrefer: persistent-authおよびCookieヘッダーで後続のすべての要求を送信します。認証セッションを使用する場合は、Authorizationヘッダーが不要になりました。HEAD /ovirt-engine/api HTTP/1.1 Host: myengine.example.com Prefer: persistent-auth Cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK HTTP/1.1 200 OK ...
セッションが必要なくなった場合は、
Prefer: persistent-authヘッダーなしでサーバーへの要求を実行します。HEAD /ovirt-engine/api HTTP/1.1 Host: myengine.example.com Authorization: Basic YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA== HTTP/1.1 200 OK ...
