Using the Identity Management API to communicate with an IdM Server

This document describes how to access the Identity Management (IdM) management framework in a programmatic way remotely over the HTTPS connection.

NOTE: The Identity Management API is fully supported since the release of Red Hat Enterprise Linux 9.3. Please note though, that while IdM API provides a JSON-RPC interface, it is recommended to access the API through Python instead, since it automates important parts such as the metadata retrieval from the server, which allows to list all available commands. This is also the only supported method to access the IdM API. More information are available in the IdM API documentation.

For a basic overview of what the IdM API is used for and how it works, see:

Introduction to the IdM Management API

For concept explanations, see:

JSON Request and Response Sequence
The Structure of IdM Commands
Requirements for Requests to the IdM API End Points

For usage examples, see:

Send a JSON-RPC Request Using curl
JSON-RPC Request to Display Information About a User
JSON-RPC Request for Server Environment Details

For information on how to obtain information about the available IdM API commands, see:

Discover the API Structure

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 input data (command name, arguments, options) from the JSON-RPC-formatted request.
Dispatches execution of a command referenced by the request.
Transparently allows to re-use the authenticated Kerberos principal when a command accesses the LDAP data store.
Provides IdM object mapping to objects stored in LDAP and allows to manipulate LDAP objects.
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.

For details on the structure of individual commands, see Discover the API Structure.

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.

To obtain the session cookie, choose one of the following:

GSSAPI authentication, see End Point for GSSAPI Authentication
Password-based authentication, see End Point for Password-based Authentication

End Point for GSSAPI Authentication

The URL of the end point to authenticate with GSSAPI is: https://ipa-server.example.com/ipa/session/login_kerberos.

The end point requires an HTTP POST request.
For details, see RFC 4559.

IMPORTANT: In Red Hat Enterprise Linux 7.3 and earlier, only Kerberos principals from the IdM realm are accepted.

The following example shows how to access the https://ipa-server.example.com/ipa/usession/login_kerberos end point using the curl utility. In the example:

$COOKIEJAR contains a name of the file that stores the cookies

Kerberos credentials were obtained earlier using the kinit utility or by logging in to IdM

# 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

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:

$COOKIEJAR contains the name of the file that stores the cookies
$_USERNAME contains the name of the user to authenticate

$_PASSWORD contains the password of the authenticating user

# 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

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:

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...

For an example of a JSON-RPC request sent to the end point, see Send a JSON-RPC Request Using curl.

Examples

Send a JSON-RPC Request Using `curl`

The following example shows how to access the IdM JSON-RPC end point using the curl utility:

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

The example includes:

the $JSON_PAYLOAD variable, which represents the actual body of the JSON-RPC request (such as the example in JSON-RPC Request to Display Information About a User).
the -H option, which defines the HTTP referrer (see Requirements for Requests to the IdM API End Points).
the -c option, which defines the location of the authentication cookies (see End Point for GSSAPI Authentication and End Point for Password-based Authentication).
the end point for accessing the IdM API over JSON-RPC with HTTP sessions: https://ipa-server.example.com/ipa/session/json (see End Point for Handling JSON Requests).

JSON-RPC Request to Display Information About a User

The following example shows a request for the IdM server to display all information about the john user:

{
    "method": "user_show", 
    "params": [
        [
            "john"
        ], 
        {
            "all": true, 
            "version": "2.215"
        }
    ]
    "id": 0, 
}

NOTE: The ipa command-line utility equivalent is the ipa user-show --all john command.

In the example:

The request includes a method (user_show), parameters (an argument john and options --all, version), and the request ID (0) (see Request).
The method (user_show) consists of a topic (user) and an operation (show) (see Terminology: Methods, Commands, Topics, and Operations).

The response returned by the server contains all attributes associated with the user object john:

{
    "error": null, 
    "id": 0, 
    "principal": "admin@EXAMPLE.COM", 
    "result": {
        "result": {
            "cn": [
                "John Smith"
            ], 
            "displayname": [
                "John Smith"

[... response truncated ...]

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

JSON-RPC Request for Server Environment Details

To request information about the server environment:

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

The response contains a number of properties. For example:

session_auth_duration, which specifies how long an authentication cookie is valid
api_version, which specifies the server's API version

version, which specifies the IdM server's version

{
    "error": null, 
    "id": 0, 
    "principal": "admin@EXAMPLE.COM", 
    "result": {
        "count": 109, 
        "messages": [
            {
                "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"
}

Discover the API Structure

API Browser: The IdM API Reference in the Web UI

IdM provides built-in API reference documentation in the web UI. To access it, select IPA Server → API Browser.

The documentation describes the following for every IdM command:

Arguments
Options (options specific for a particular ipa command)
Common Options (options common for a set of ipa commands)
Descriptions and requirements for the above

Request the JSON Format Using the API Methods

The IdM management framework includes several methods for discovering the API structure.

The most comprehensive method is schema. It accepts no arguments or options:

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

Calling the schema method returns all details about the IdM API schema:

commands and the structure of their parameters and options
object classes and their properties
topics

The resulting JSON output is large, approximately 2 MiB in the Identity Management version in Red Hat Enterprise Linux 7.3. It is recommended to cache the result.

NOTE: The schema method is only available for the JSON requests, not for the ipa command-line utility.

It is also possible to discover:

topics, using the topic_find and topic_show methods
classes, using the class_find and class_show methods
commands, using the command_find and command_show methods

NOTE: Commands for these methods are also available for the ipa command-line utility. For example, $ ipa topic-find.

Display the JSON Format from the Command Line

To display the JSON request and response format for a command, run the command with the -vv option. For example:

$ 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": [
        [
            "tuser"
        ], 
        {
            "version": "2.213"
        }
    ]
}
ipa: INFO: Response: {
    "error": null, 

    [... output truncated ...]

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.

Select Your Language

Using the Identity Management API to communicate with an IdM Server

Introduction to the IdM Management API

JSON Request and Response Sequence

Request

Response

The Structure of IdM Commands

Terminology: Methods, Commands, Topics, and Operations

The Structure of JSON-RPC Commands

Requirements for Requests Sent to the IdM API End Points

End Point for GSSAPI Authentication

End Point for Password-based Authentication

End Point for Handling JSON Requests

Examples

Send a JSON-RPC Request Using `curl`

JSON-RPC Request to Display Information About a User

JSON-RPC Request for Server Environment Details

Discover the API Structure

API Browser: The IdM API Reference in the Web UI

Request the JSON Format Using the API Methods

Display the JSON Format from the Command Line

Comments

Quick Links

Help

Site Info

Related Sites

About

Red Hat legal and privacy links

Red Hat legal and privacy links

Introduction to the IdM Management API

JSON Request and Response Sequence

Request

Response

The Structure of IdM Commands

Terminology: Methods, Commands, Topics, and Operations

The Structure of JSON-RPC Commands

Requirements for Requests Sent to the IdM API End Points

End Point for GSSAPI Authentication

End Point for Password-based Authentication

End Point for Handling JSON Requests

Examples

Send a JSON-RPC Request Using curl

JSON-RPC Request to Display Information About a User

JSON-RPC Request for Server Environment Details

Discover the API Structure

API Browser: The IdM API Reference in the Web UI

Request the JSON Format Using the API Methods

Display the JSON Format from the Command Line

Comments

Quick Links

Help

Site Info

Related Sites

Systems Status

About

Red Hat legal and privacy links

Red Hat legal and privacy links

Send a JSON-RPC Request Using `curl`