freeipa/doc/api/jsonrpc_usage.md

JSON-RPC API usage

Apart from Python, the FreeIPA API is also available through HTTPS exchanging requests in JSON-RPC format.

Basic usage

Before sending requests to the FreeIPA server, we need to properly authenticate.

It is possible to authenticate both through Kerberos and password.

Kerberos authentication

To authenticate via Kerberos, it is needed to have actual credentials in the credentials cache first. After this, we need to send a login request to the FreeIPA endpoint, https://$IPAHOSTNAME/ipa/session/login_kerberos.

$ export KRB5CCNAME=FILE:/path/to/ccache
$ export COOKIEJAR=/path/to/my.cookie
$ export IPAHOSTNAME=ipa-master.example.com
$ kinit -k -t /path/to/service.keytab service/ipa-client.example.com
$ curl -v  \
        -H referer:https://$IPAHOSTNAME/ipa  \
        -c $COOKIEJAR -b $COOKIEJAR \
        --cacert /etc/ipa/ca.crt  \
        --negotiate -u : \
        -X POST \
        https://$IPAHOSTNAME/ipa/session/login_kerberos

If authentication was successful, $COOKIEJAR will contain all session cookies returned from the server. We will need to pass this with every request we send to the server.

Password authentication

For password authentication, we just need to post it over HTTPS.

$ export COOKIEJAR=/path/to/my.cookie
$ export IPAHOSTNAME=ipa-master.example.com
$ s_username=admin s_password=mYSecReT1P2 curl -v  \
        -H referer:https://$IPAHOSTNAME/ipa  \
        -H "Content-Type:application/x-www-form-urlencoded" \
        -H "Accept:text/plain"\
        -c $COOKIEJAR -b $COOKIEJAR \
        --cacert /etc/ipa/ca.crt  \
        --data "user=$s_username&password=$s_password" \
        -X POST \
        https://$IPAHOSTNAME/ipa/session/login_password

Same as kerberos authentication, we will need to pass the sessions cookies with every request.

Request and Response format

A JSON-RPC request consists of three properties:

• method: A string containing the name of the name that will be called.
• params: the array of parameters for the command.
• id: the request id, it can be of any type, the response will match it.

The response received from the server consists of four properties:

• result: The returned Object from the command. If the command failed, this will be null.
• principal: The Kerberos principal under which identity the command was performed.
• error: An Error object containing information about the command if it failed. If it succeeded, this will be null.
• ìd: An ID matching the request this response is replying to.

Sending a request

Requests should be sent to the API endpoint https://$IPAHOSTNAME/ipa/session/json over HTTPS. The content type must be set to application/json and session cookies obtained when authentication must be passed with the request.

An example request for the user_find command would be:

curl -v  \
	-H referer:https://$IPAHOSTNAME/ipa  \
        -H "Content-Type:application/json" \
        -H "Accept:applicaton/json"\
        -c $COOKIEJAR -b $COOKIEJAR \
        --cacert /etc/ipa/ca.crt  \
        -d  '{"method":"user_find","params":[[""],{}],"id":0}' \
        -X POST \
        https://$IPAHOSTNAME/ipa/session/json

An easy way to understand how IPA requests are built is via the CLI, by passing the -vv option to an IPA command.

$ ipa -vv user-find 
ipa: INFO: Request: {
    "id": 0,
    "method": "user_find/1",
    "params": [
        [],
        {
            "version": "2.251"
        }
    ]
}

[...]

Converting JSON-RPC requests to Python

FreeIPA provides methods to convert JSON-RPC requests to Python format. This is included in the freeipa-python-ipaserver package in Fedora.

from ipaserver.rpcserver import jsonserver

json_request = '{"method":"user_find","params":[[""],{}],"id":0}'
j = jsonserver(api) # `api` is the initialized IPA API object

(name, args, opts, response_id) = j.unmarshal(json_request)

result = api.Command[name](*args, **opts)

Reporting issues

To report issues related to API usage, they should be reproducible using the API through Python, in order to discard errors related to misconstruction of JSON-RPC requests. These requests can be converted to Python using the steps mentioned earlier.