Documentation

Introduction

Documentation for the Identity Policy Audit (IPA) JavaScript Object Notation (JSON) API.

This is largely undocumented. No automatic code documentation is generated when an IPA server is installed like with other large projects like this.

This documentation will most likely remain both minimal and stale.

Rational

The native 'jsonapi' types in this Puppet module use some clever meta-programming to talk directly to the endpoints. Some kind of explanation should exist for their behavior.

IPA Application Programming Interface

Requests

Json requests are from the python module with name "method_name" from the Ipa Python modules. These match the ipa-client commands named 'method-name'.

ipa -vv user-show admin from the mailing list is the json method user_show.

Connections are made through HTTPS to the /ipa/session/json URL for the server.

Method format is fixed for all options and follows roughly Python calling convention for functions:

1. 'method': 'name_of_method'
2. 'params': []
3. an id tag, usually 0.

The parameters are an array containing:

1. fixed array of positional parameters
2. hash of named parameters (i.e., the json API is a direct map to the python internals.)

All json calls return a response hash:

• ipa: INFO: Response: {}

The response contains:

1. error, "error string if not null"
2. id, a number which should match the request ID
3. principal, a keberos principal used to authenticate (user@REALM format)
4. result, a result hash that can be extremely large and deep structure, particularly for LDAP queries
5. version, the API version string

Examples

The API endpoint is only available to authenticated users.

Using cURL from a registered host shows the complexity of the required login for a simple query.

curl -v -H referer:https://ipa.example.com/ipa -H "Content-Type:application/x-www-form-urlencoded" -H "Accept:text/plain" -c cookies.jar -b cookies.jar --cacert /etc/ipa/ca.crt --data "user=my_username&password=SekritPassWord" -X POST https://$IPAHOSTNAME/ipa/session/login_password

This calls the API function to find all or one user. The example call is '{"method":"user_find","params":[[""],{}],"id":0} but most the boilerplate is mandatory for every call regardless of method.

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

This will return a large list of LDAP user entries.

References

• IPA via cURL
• Talking to IPA with sessions
• RedHat mailing list on ipa-client debugging
• jonwuz original IPA module