Identity Management API を使用して IdM サーバーに接続する (テクノロジープレビュー)

このドキュメントでは、HTTPS 接続においてプログラミングを使ってリモートで Identity Management (IdM) 管理フレームワークにアクセスする方法を説明します。

注意: IdM API はテクノロジープレビュー機能です。詳細は Technology Preview Features Support Scope を参照してください。

IdM API が使用されるものと、その機能については、次を参照してください。

IdM Management API の概要

概念については、次を参照してください。

JSON リクエストおよびレスポンスのシーケンス
IdM コマンドの構造
IdM API エンドポイントへのリクエストの要件

使用例については、次を参照してください。

curl を使用して JSON-RPC リクエストを送信する
ユーザーに関する情報を表示する JSON-RPC リクエスト
サーバー環境の詳細への JSON-RPC リクエスト

利用可能な IdM API コマンドの情報を取得する方法については、次を参照してください。

API 構造の検出

IdM Management API の概要

IdM API を使用すると、開発者はサードパーティアプリケーションを IdM サーバーと統合することができます。IdM API を使用するアプリケーションの例は IdM web UI です。

web UI は、IdM web サイトを訪れるときにブラウザーからダウンロードされる JavaScript ベースのアプリケーションです。
アプリケーションが自身をブートして、IdM サーバーへの API コールで JSON-RPC リクエストを発行します。
クライアントで、ブラウザーが、認証と、クッキーを使用したキャッシュを自動的に実行します。

IdM 管理フレームワークは、LDAP サーバー、認証局、DNS など、さまざまな IdM コンポーネントを管理するさまざまなツールを使用しなくても、LDAP サーバーのデータを修正するツールを提供します。管理フレームワークは Python で作成され、web アプリケーションとして実行します。クライアントも Python で作成されていますが、サーバーとの接続に関する詳細をすべて隠します。

Python でクライアントコードを使用すると、IdM 管理 API における開示が簡単になります。より柔軟なその他のプログラミング言語環境に対して、IdM は HTTPS ベースのエンドポイントへのダイレクトアクセスを提供します。

JSON リクエストおよびレスポンスのシーケンス

IdM フレームワークのやりとりは、JSON-RPC v1.0 フォーマットに基づいています。IdM フレームワークは JSON 仕様を拡大適用して、IdM でのやりとりに必要な複数のプロパティと挙動変更を追加します。

リクエストとレスポンスの送受信時、IdM 管理フレームワークは以下を行います。

受信 HTTPS 接続を認証し、認証されたエントリーを、IdM レルムにおける既知の Kerberos プリンシパルにマッピングします。
JSON-RPC フォーマットリクエストから、入力データ (コマンド名、引数、オプション) を収集します。
リクエストに参照されているコマンドの実行をディスパッチします。
コマンドが LDAP データストアにアクセスすると、認証された Kerberos プリンシパルを再利用することを透過的に許可します。
LDAP に保存されるオブジェクトに IdM オブジェクトのマッピングを提供し、LDAP オブジェクトの操作を許可します。
コマンド実行の結果を取得し、JSON-RPC フォーマットで構築します。
JSON-RPC フォーマットのレスポンスとして処理されたリクエストの結果を送信します。

リクエスト

リモートコマンドを呼び出すために、リモートサービスにリクエストが送信されました。リクエストは、 JSON 表記を使用して 1 つのオブジェクトをシリアル化して、以下のプロパティを所有します。

method: 呼び出されるコマンド名を含む文字列。
params: コマンドへの引数として渡すオブジェクトの配列。
id: リクエスト ID。すべての ID タイプが許可されます。リクエストの id プロパティが、対応するレスポンスの id プロパティに一致します。

レスポンス

コマンドの呼び出しが完了すると、サービスはレスポンスを送信します。JSON 表記を使用して 1 つのオブジェクトをシリアル化して、以下のプロパティを所有します。

result: 呼び出したコマンドから返されるオブジェクト。コマンドを呼び出す際にエラーが発生すると、result が null になります。
princial: リクエストが実行された ID の Kerberos プリンシパル。principal プロパティは JSON-RPC v1.0 フォーマットの一部ではありません。
error: コマンドの呼び出し時にエラーが発生した場合のエラーオブジェクト。エラーが発生しないと、error は null になります。
id: レスポンスの id プロパティは、対応するリクエストの id プロパティに一致します。

result の構造はコマンドによって異なります。これには、messages という名前の配列が含まれます。これには IdM 管理フレームワークからの追加の診断情報が含まれる JSON オブジェクトが多数含まれます。messages 配列の JSON オブジェクトの構造は以下のようになります。

code: メッセージの数字コード。
data: このメッセージに関連するプロパティのディクショナリ。
message: 実際のメッセージ文字列。
name: IdM フレームワークのメッセージクラスの名前。
type: warning などのメッセージの種類。

IdM コマンドの構造

用語: メソッド、コマンド、トピック、オペレーション

IdM コマンドはトピックになります。トピックは、同じ種類のオブジェクトに関するオペレーションセットを表します。たとえば、cert トピックには証明書関連のコマンドが含まれ、group トピックにはグループ関連のコマンドが含まれます。

IdM フレームワークのコマンドは、以下を指定することで表わします。

user、group、host などのトピック
add、mod、del などのオペレーション

追加、修正、削除などの一般的なオペレーションが複数のトピックに利用できます。たとえば、ユーザー、証明書、ホスト、その他の多数のオブジェクトを追加できます。

IdM は 2 つのタイプのコマンドを区別します。

メソッド: LDAP オブジェクトで動作するコマンド。メソッドには常に関連する LDAP オブジェクトがあります。
コマンド: LDAP オブジェクトに関連していないコマンド。

たとえば、証明書は、通常、その他の LDAP オブジェクトを属性値として保存しますが、独自の LDAP オブジェクトはありません。したがって、証明書を修正するコマンドはメソッドではなくコマンドです。

JSON-RPC コマンドの構造

JSON-RPC コールは、トピックとオペレーションをアンダーラインでつなげて指定 (topic_operation) することで、メソッドおよびコマンドを処理します。たとえば以下のようになります。

user_add: ユーザーオブジェクトを追加するコマンド
group_mod: グループオブジェクトを修正するコマンド
host_del: ホストオブジェクトを削除するコマンド

各 JSON-RPC コマンドには、場所の引数とオプションがあります。以下の順で params 配列の一部として JSON-RPC フォーマットに指定されます。

配列となる引数
ディクショナリとなるオプション

重要: IdM サーバーは、JSON-RPC が version オプションを使用して API バージョンを指定することを期待します。サーバーは、version がないリクエストも許可しますが、その後のレスポンスでは version がなく、上位互換性が保証されないことを示す警告が含まれます。サーバーの API バージョンを検出する方法については、API メソッドを使用した JSON フォーマットのリクエストを参照してください。

個々のコマンドの構造の詳細は、API 構造の検出を参照してください。

IdM API エンドポイントに送信したリクエストの要件

サーバーで、IdM 管理フレームワークを、Apache web サーバーの仮想ホストにある web アプリケーションとして実行します。フレームワークが https://ipa-server.example.com/ipa にインストールされました。このアドレスですべてのエンドポイントの URL が開始します。

エンドポイントにリクエストを送信すると、クライアントでは HTTP リファラ値をフレームワークのプライマリ URL: https://ipa-server.example.com/ipa に設定する必要があります。そのためには、HTTP Referer ヘッダーを以下に設定します。

Referer: https://ipa-server.example.com/ipa

注意: リファラフィールドは、HTTP 1.1 では Referer です。Referrer ではありません。

また、https://ipa-server.example.com/ipa にあるすべてのコンテンツは GSSAPI 認証を使用して保護されます。コンテンツにアクセスしようとするすべてのリクエストは適切に認証される必要があります。認証されたエントリーは有効な Kerberos プリンシパルであるべきで、IdM LDAP データストアで対応する有効な LDAP オブジェクトがあります。

通常、GSSAPI 認証交渉には複数のやりとりが必要です。便宜上、IdM フレームワークは HTTP セッションの使用をサポートします。クライアント認証に成功すると、一定期間有効なセッションクッキーになります。次のリクエスト時に有効なクッキーをクライアントが表示すると、リクエストは認証のエンドポイントにリダイレクトされなくなります。

セッションクッキーを取得するには、以下のいずれかを選択してください。

GSSAPI 認証については GSSAPI 認証のエンドポイントを参照してください。
パスワードベースの認証については、パスワードベース認証のエンドポイントを参照してください。

GSSAPI 認証のエンドポイント

GSSAPI を使用して認証するエンドポイントの URL は https://ipa-server.example.com/ipa/session/login_kerberos です。

エンドポイントには HTTP POST リクエストが必要です。
詳細は RFC 4559 を参照してください。

重要: Red Hat Enterprise Linux 7.3 以降では、 IdM レルムの Kerberos プリンシパルだけが許可されます。

以下の例は、curl ユーティリティを使用して https://ipa-server.example.com/ipa/usession/login_kerberos エンドポイントへのアクセス方法を示しています。この例では、以下のようになります。

$COOKIEJAR には、クッキーを保存するファイル名が含まれます。

kinit ユーティリティを使用するか IdM にログインして、Kerberos 信用情報が先に取得されています。

# Login with Kerberos
$ curl -v  \
-H Referer:https://ipa-server.example.com/ipa  \
-c $COOKIEJAR -b $COOKIEJAR \
--cacert /etc/ipa/ca.crt  \
--negotiate -u : \
-X POST \
https://ipa-server.example.com/ipa/session/login_kerberos

GSSAPI 交渉に成功すると、HTTP 1.1 ステータスコード 200 Success を持つセッションクッキーが返されます。JSON リクエストを送信する際に、クッキーを https://ipa-server.example.com/ipa/session/json エンドポイントに表示します (JSON リクエストを処理するエンドポイントを参照)。

パスワードベース認証のエンドポイント

パスワードを使用して認証するエンドポイントの URL は https://ipa-server.example.com/ipa/session/login_password です。

エンドポイントには HTTP POST リクエストが必要です。
エンドポイントは、2 つの必須フィールド username および password を持つ HTML フォームのパースを実装します。
リクエストには、以下の HTTP ヘッダーを含む必要があります。
```
Content-Type: application/x-www-form-urlencoded
Accept: text/plain
```

以下の例は、curl ユーティリティを使用して /ipa/usession/login_password エンドポイントにアクセスする方法を示します。この例では、以下のようになります。

$COOKIEJAR には、クッキーを保存するファイルの名前が含まれます。
$_USERNAME には、認証するユーザーの名前が含まれます。

$_PASSWORD には、認証ユーザーのパスワードが含まれます。

# Login with user name and password
$ curl -v  \
-H Referer:https://ipa-server.example.com/ipa  \
-H "Content-Type:application/x-www-form-urlencoded" \
-H "Accept:text/plain"\
-c $COOKIEJAR -b $COOKIEJAR \
--cacert /etc/ipa/ca.crt  \
--data "user=$_USERNAME&password=$_PASSWORD" \
-X POST \
https://ipa-server.example.com/ipa/session/login_password

認証に成功したら、HTTP 1.1 ステータスコード 200 Success が返され、Cookie ヘッダーがクッキー値に設定されます。JSON リクエストを送信する際に、クッキーを /ipa/session/json エンドポイントに表示できます (JSON リクエストを処理するエンドポイントを参照)。

JSON リクエストを処理するエンドポイント

HTTP セッションを使用した IdM API にアクセスするプライマリのエンドポイントの URL は https://ipa-server.example.com/ipa/session/json になります。

エンドポイントには HTTP POST リクエストが必要です。
リクエストの HTTP ヘッダーには、application/json として期待され許可されるコンテンツタイプを指定する必要があります。
リクエストには、以前認証エンドポイントから取得したセッションクッキーを含む必要があります。
リクエストの本文は、JSON-RPC リクエストの JSON フォーマットデータです。

以下の例は、JSON-RPC にアクセスする際に有効な JSON-RPC リクエストを含む必要がある HTTP ヘッダーをすべて示します。

POST /ipa/session/json HTTP/1.1
Host: ipa-server.example.com
Referer: https://ipa-server.example.com/ipa
Content-type: application/json
Accept: application/json
Cookie: ipa_session=...cookie..value...

エンドポイントに送られる JSON-RPC リクエストの例については、curl を使用して JSON-RPC リクエストを送信するを参照してください。

例

`curl` を使用して JSON-RPC リクエストを送信する

以下の例は、curl ユーティリティを使用して IdM JSON-RPC エンドポイントにアクセスする方法を示しています。

curl -v  \
    -H referer:https://ipa-server.example.com/ipa  \
    -H "Content-Type:application/json" \
    -H "Accept:applicaton/json"\
    -c $COOKIEJAR -b $COOKIEJAR \
    --cacert /etc/ipa/ca.crt  \
    -d  $JSON_REQUEST \
    -X POST \
    https://ipa-server.example.com/ipa/session/json

この例には以下が含まれます。

$JSON_PAYLOAD 変数。JSON-RPC リクエストの実際の本文を示しています (ユーザーに関する情報を表示するための JSON-RPC の例など)。
-H オプション。HTTP リファラを定義します (IdM API エンドポイントへのリクエスト要件)。
-c オプション。認証クッキーの場所を定義します (GSSAPI 認証のエンドポイントおよびパスワードベース認証のエンドポイントを参照)。
HTTP セッションを持つ JSON-RPC で IdM API アクセスするエンドポイント (https://ipa-server.example.com/ipa/session/json (JSON リクエストを処理するエンドポイント))

ユーザーに関する情報を表示する JSON-RPC リクエスト

以下の例は、IdM サーバーに対して、john ユーザーに関するすべての情報を表示するリクエストを示します。

{
    "method": "user_show", 
    "params": [http://rhn.redhat.com/errata/RHSA-2011-0017.html
        [http://rhn.redhat.com/errata/RHSA-2011-0017.html
            "john"
        ], 
        {
            "all": true, 
            "version": "2.215"
        }
    ]
    "id": 0, 
}

注意: ipa コマンドラインユーティリティに同等のものは、ipa user-show --all john コマンドです。

この例では、以下のようになります。

リクエストにはメソッド (user_show)、パラメーター (引数 john およびオプション --all、version)、およびリクエスト ID (0) (リクエストを参照) が含まれます。
メソッド (user_show) は、トピック (user) とオペレーション (show) で構成されます (用語: メソッド、コマンド、トピック、およびオペレーションを参照)。

サーバーから返されたレスポンスには、ユーザーオブジェクト john に関連付けられている属性がすべて含まれます。

{
    "error": null, 
    "id": 0, 
    "principal": "admin@EXAMPLE.COM", 
    "result": {
        "result": {
            "cn": [http://rhn.redhat.com/errata/RHSA-2011-0017.html
                "John Smith"
            ], 
            "displayname": [http://rhn.redhat.com/errata/RHSA-2011-0017.html
                "John Smith"

[... response truncated ...]

        }, 
        "summary": null, 
        "value": "John"
    }, 
    "version": "4.4.1"
}

サーバー環境の詳細に対する JSON-RPC リクエスト

サーバー環境に関する情報を要求する場合は、以下のようになります。

    {
        "method" : "env",
        "params":[
            [],
            {},
        ],
        "id":0
    }

レスポンスには、多数のプロパティが含まれます。たとえば以下のようになります。

session_auth_duration: 認証クッキーが有効な期間を指定します。
api_version: サーバーの API バージョンを指定します。

version: IdM サーバーのバージョンを指定します。

{
    "error": null, 
    "id": 0, 
    "principal": "admin@EXAMPLE.COM", 
    "result": {
        "count": 109, 
        "messages": [http://rhn.redhat.com/errata/RHSA-2011-0017.html
            {
                "code": 13001, 
                "data": {
                    "server_version": "2.212"
                }, 
                "message": "API Version number was not sent, forward compatibility not guaranteed.Assuming server's API version, 2.212", 
                "name": "VersionMissing", 
                "type": "warning"
            }
        ], 
        "result": {
            "api_version": "2.212", 

[... output truncated ...]

            "session_auth_duration": "20 minutes", 

[... output truncated ...]

            "version": "4.4.1", 

[... output truncated ...]
        }, 
        "summary": "109 variables", 
        "total": 109
    }, 
    "version": "4.4.1"
}

API 構造の検出

API ブラウザー: Web UI の IdM API 参照

IdM は、web UI に組み込み API 参照ドキュメントを提供します。これにアクセスするには、IPA Server → API Browser を選択します。

ドキュメントは、各 IdM コマンドに対して以下を説明します。

引数
オプション (特定の ipa コマンドに固有のオプション)
一般的なオプション (ipa コマンド設定に一般的なオプション)
上述に対する説明と要件

API メソッドを使用した JSON フォーマットのリクエスト

IdM 管理フレームワークには、API 構造を検出するさまざまなメソッドが含まれます。

もっとも包括的なメソッドは schema です。これは、引数またはオプションがないのを許可します。

{
    "method" : "schema",
    "params":[
        [],
        {},
    ],
    "id":0
}

schema メソッドを呼び出すと、IdM API スキーマに関する詳細をすべて返します。

コマンドと、パラメーターとオプションの構造
オブジェクトクラスとプロパティ
トピック

結果として作成される JSON 出力ファイルは大きく、Red Hat Enterprise Linux 7.3 の Identity Management バージョンで約 2 MiB になります。結果をキャッシュすることが推奨されます。

注意: schema メソッドは JSON リクエストに対してのみ利用可能で、ipa コマンドラインユーティリティには利用できません。

以下も検出できます。

トピック。topic_find メソッドおよび topic_show メソッドを使用。
クラス。class_find メソッドおよび class_show メソッドを使用。
コマンド。command_find メソッドおよび command_show メソッドを使用。

注意: これらのメソッドのコマンドは、ipa コマンドラインユーティリティに対しても利用できます。たとえば $ ipa topic-find です。

コマンドラインから JSON フォーマットを表示する

コマンドの JSON リクエストとレスポンスを表示するには、-vv オプションを付けてコマンドを実行します。たとえば以下のようになります。

$ ipa -vv user_show [user_name]
ipa: INFO: trying https://ipa-server.example.com/ipa/session/json
ipa: INFO: Forwarding 'user_show/1' to json server 'https://ipa-server.example.com/ipa/session/json’
ipa: INFO: Request: {
    "id": 0, 
    "method": "user_show/1", 
    "params": [http://rhn.redhat.com/errata/RHSA-2011-0017.html
        [http://rhn.redhat.com/errata/RHSA-2011-0017.html
            "tuser"
        ], 
        {
            "version": "2.213"
        }
    ]
}
ipa: INFO: Response: {
    "error": null, 

    [... output truncated ...]

注意: 表示された JSON-RPC メソッド名にはバージョンが含まれる可能性があります。たとえば、上述の出力の user_show/1 は、user_show のバージョン 1 を示しています。この機能は、今後バージョンが付いたコマンドを有効にするために、Red Hat Enterprise Linux 7.3 に導入されました。現時点は、バージョン 1 だけがサポートされます。バージョン 1 がデフォルトのバージョンです。詳細は the upstream API Compatibility design page on freeipa.org を参照してください。

Select Your Language

Translated message

Identity Management API を使用して IdM サーバーに接続する (テクノロジープレビュー)

IdM Management API の概要

JSON リクエストおよびレスポンスのシーケンス

リクエスト

レスポンス

IdM コマンドの構造

用語: メソッド、コマンド、トピック、オペレーション

JSON-RPC コマンドの構造

IdM API エンドポイントに送信したリクエストの要件

GSSAPI 認証のエンドポイント

パスワードベース認証のエンドポイント

JSON リクエストを処理するエンドポイント

例

`curl` を使用して JSON-RPC リクエストを送信する

ユーザーに関する情報を表示する JSON-RPC リクエスト

サーバー環境の詳細に対する JSON-RPC リクエスト

API 構造の検出

API ブラウザー: Web UI の IdM API 参照

API メソッドを使用した JSON フォーマットのリクエスト

コマンドラインから JSON フォーマットを表示する

Comments

Quick Links

Help

Site Info

Related Sites

About

Red Hat legal and privacy links

Red Hat legal and privacy links

Translated message

IdM Management API の概要

JSON リクエストおよびレスポンスのシーケンス

リクエスト

レスポンス

IdM コマンドの構造

用語: メソッド、コマンド、トピック、オペレーション

JSON-RPC コマンドの構造

IdM API エンドポイントに送信したリクエストの要件

GSSAPI 認証のエンドポイント

パスワードベース認証のエンドポイント

JSON リクエストを処理するエンドポイント

例

curl を使用して JSON-RPC リクエストを送信する

ユーザーに関する情報を表示する JSON-RPC リクエスト

サーバー環境の詳細に対する JSON-RPC リクエスト

API 構造の検出

API ブラウザー: Web UI の IdM API 参照

API メソッドを使用した JSON フォーマットのリクエスト

コマンドラインから JSON フォーマットを表示する

Comments

Quick Links

Help

Site Info

Related Sites

Systems Status

About

Red Hat legal and privacy links

Red Hat legal and privacy links

`curl` を使用して JSON-RPC リクエストを送信する