Introduction to the IdM Management API

The IdM API enables developers to integrate their third-party applications with the IdM server. An example of an application that uses the IdM API is the IdM web UI:

The web UI is a JavaScript-based application that is downloaded by the browser when visiting the IdM web site.

The application bootstraps itself and issues JSON-RPC requests with the API calls to the IdM server.

On the client side, the browser automatically performs the authentication and caching using cookies.

The IdM management framework provides tools to modify the data in the LDAP server without the need to use different tools to manage the various IdM components, such as the LDAP server, Certificate Authority, or DNS. The management framework is written in Python and is run as a web application. Its client side, also written in Python, hides all details on how to communicate with the server side.

Using the client code in Python enables easier consumption of the IdM management API. For more flexibility and other programming language environments, IdM provides direct access to HTTPS-based end points.

JSON Request and Response Sequence

IdM framework exchanges are based on the JSON-RPC v1.0 format. The IdM framework extends the JSON specification to add several properties and behavior changes required for communication within IdM.

During the request and response exchanges, the IdM management framework:

Authenticates incoming HTTPS connection and maps the authenticated entity to a known Kerberos principal in the IdM realm.

Gathers results of the command execution and structures them according to the JSON-RPC format.

Sends out the result of the processed request as a JSON-RPC-formatted response.

Request

To invoke a remote command, a request is sent to a remote service. The request is a single object serialized using the JSON notation and has these properties:

method: A string containing the name of the command to be invoked.

params: An array of objects to pass as arguments to the command

id: The request ID. All ID types are accepted. The id property of the request matches the id property of the corresponding response.

Response

After a command invocation completes, the service replies with a response. The response is a single object serialized using the JSON notation and has these properties:

result: The object returned by the invoked command. If an error occurred when invoking the command, result is null.

princial: The Kerberos principal of the identity under which the request was performed. The principal property is not part of the JSON-RPC v1.0 format.

error: An error object if an error occurred when invoking the command. If no error occurred, error is null.

id: The id property of the response matches the id property of the corresponding request.

The structure of result differs from command to command. It can include an array called messages, which contains a number of JSON objects with additional diagnostic information from the IdM management framework. The structure of the JSON object within the messages array is:

code: The numeric code of the message.

data: A dictionary of properties related to the message.

message: The actual message string.

name: The name of the message class within the IdM framework.

type: The type of the message, such as warning.

The Structure of IdM Commands

Terminology: Methods, Commands, Topics, and Operations

IdM commands are structured into topics. A topic represents a set of operations related to the same object type. For example, the cert topic includes certificate-related commands, and the group topic includes group-related commands.

Commands within the IdM framework are represented by specifying:

A topic, such as user, group, or host

An operation, such as add, mod, or del

Some common operations, such as add, modify, or delete, are available for multiple topics. For example, it is possible to add users, certificates, hosts, and a number of other objects.

IdM distinguishes two types of commands:

Methods: Commands that operate on an LDAP object. A method always has an associated LDAP object.

Commands: Commands that do not have associated LDAP objects.

For example, certificates are usually stored in other LDAP objects as an attribute value, but do not have their own LDAP object. Therefore, commands that modify certificates are not methods, but commands.

The Structure of JSON-RPC Commands

A JSON-RPC call addresses methods and commands by specifying the topic and operation joined by an undescore (topic_operation). For example:

user_add = a command that adds a user object

group_mod = a command that modifies a group object

host_del = a command that deletes a host object

Each JSON-RPC command has positional arguments and options. They are specified in the JSON-RPC format as part of the params array in the following order:

Arguments as an array

Options as a dictionary

IMPORTANT: The IdM server expects the JSON-RPC request to specify an API version using the version option. The server accepts a request without version as well, but the subsequent response contains a warning that version is missing and that forward compatibility is not guaranteed. See Requesting the JSON Format Using the API Methods for information on how to discover the API version of the server.

Requirements for Requests Sent to the IdM API End Points

On the server side, the IdM management framework runs as a web application within the Apache web server’s virtual host. The framework is installed under https://ipa-server.example.com/ipa. The URLs of all end points start with this address.

When sending a request to any end point, the client must have the HTTP referrer value set to the framework's primary URL: https://ipa-server.example.com/ipa. For that, set the HTTP Referer header to:

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

NOTE: The referrer field is Referer in the HTTP 1.1 specification, not Referrer.

Additionally, all content under https://ipa-server.example.com/ipa is protected with GSSAPI authentication. Every request attempting to access the content must be properly authenticated: the authenticated entity must be a valid Kerberos principal that has a corresponding valid LDAP object in the IdM LDAP data store.

Normally, GSSAPI authentication negotiation requires multiple rounds. For conveniency, the IdM framework supports the use of HTTP sessions. A successfull client authentication results in a session cookie, which is valid for a certain time. When the client presents a valid cookie upon the next request, the request is no longer redirected to the authentication end-points.

If the GSSAPI negotiation is successful, a session cookie with the HTTP 1.1 status code 200 Success is returned. You can then present the cookie to the https://ipa-server.example.com/ipa/session/json end point when sending the JSON request (see End Point for Handling JSON Requests).

End Point for Password-based Authentication

The URL of the end point to authenticate using a password is: https://ipa-server.example.com/ipa/session/login_password.

The end point requires an HTTP POST request.

The end point implements parsing of an HTML form with two mandatory fields: username and password.

The request must contain the following HTTP headers:

Content-Type: application/x-www-form-urlencoded
Accept: text/plain

The following example shows how to access the /ipa/usession/login_password end point using the curl utility. In the example:

If the authentication is successful, the HTTP 1.1 status code 200 Success is returned and a Cookie header is set to the cookie value. You can then present the cookie to the /ipa/session/json end point when sending the JSON request (see End Point for Handling JSON Requests).

End Point for Handling JSON Requests

The URL of the primary end point for accessing the IdM API with HTTP sessions is: https://ipa-server.example.com/ipa/session/json.

The end point requires an HTTP POST request.

The HTTP header of the request must specify the expected and accepted content types as application/json.

The request must include a session cookie that was previously obtained through any of the authentication end points.

The body of the request is the JSON-formatted data for the JSON-RPC request.

The following example shows all HTTP headers that a valid JSON-RPC request must include when accessing JSON-RPC:

NOTE: The displayed JSON-RPC method name might include a version. For example, user_show/1 in the above output means version 1 of the user_show method. This feature was introduced in Red Hat Enterprise Linux 7.3 to enable versioned commands in the future. Right now, only version 1 is supported. Version 1 is the default version. See the upstream API Compatibility design page on freeipa.org for details.

Formatting Tips

Request Japanese Translation

Are you sure you want to request a translation?
It seems an existing Japanese Translation exists already. However, the english version is more up to date.
We appreciate your interest in having Red Hat content localized to your language. Please note that excessive use of this feature could cause delays in getting specific content you are interested in translated.