Using the Identity Management API to Communicate with the IdM Server (TECHNOLOGY PREVIEW)

Updated -
This document describes how to access the Identity Management (IdM) management framework in a programmatic way remotely over the HTTPS connection. NOTE: The IdM API is a Technology Preview feature. See Technology Preview Features Support Scope for details. For a basic overview of what the IdM API is used for and how it works, see: For concept explanations, see: For usage examples, see: For information on how to obtain information about the available IdM API commands, see:

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:
  1. Arguments as an array
  2. 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:

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:

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

Was this helpful?

We appreciate your feedback. Leave a comment if you would like to provide more detail.
It looks like we have some work to do. Leave a comment to let us know how we could improve.
Close

Welcome! Check out the Getting Started with Red Hat page for quick tours and guides for common tasks.