Import Upstream version 4.12.4

2025-08-12 22:28:56 +02:00
parent 03a8170b15
commit 9181ee2487
1629 changed files with 874094 additions and 554378 deletions
--- a/doc/api/jsonrpc_usage.md
+++ b/doc/api/jsonrpc_usage.md
@@ -0,0 +1,135 @@
+# 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`.
+
+```bash
+$ 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.
+
+```bash
+$ 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:
+
+```bash
+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.
+
+```bash
+$ 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.
+
+```python
+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.