mirror of
https://salsa.debian.org/freeipa-team/freeipa.git
synced 2024-12-23 15:40:01 -06:00
88d8534e49
This includes: * Section about command/param info in usage guide * Section about metadata retrieval in usage guide * Guide about differences between CLI and API * Access control guide (management of roles, privileges and permissions). * Guide about API contexts * JSON-RPC usage guide and JSON-to-Python conversion * Notes about types in API Reference Signed-off-by: Antonio Torres <antorres@redhat.com> Reviewed-By: Alexander Bokovoy <abokovoy@redhat.com> Reviewed-By: Rob Crittenden <rcritten@redhat.com>
136 lines
4.2 KiB
Markdown
136 lines
4.2 KiB
Markdown
# 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.
|