// to display images directly on GitHub
ifdef::env-github[]
:encoding: UTF-8
:lang: en
:doctype: book
:toc: left
:imagesdir: ../../images
endif::[]

////

    This file is part of the PacketFence project.

    See PacketFence_Installation_Guide.asciidoc
    for authors, copyright and license information.

////


==== JSON-RPC interface

The JSONRPC module shipped with PacketFence is meant as a generic firewall SSO module to be used with Linux or BSD firewalls that do not by default ship with a vendor-specific interface to do SSO with.

A compatible server must implement the methods `Start` and `Stop`, both with the identical set of parameters provided below.

[options="compact"]
* *Protocol*: JSON-RPC 2.0 over HTTPS
* *Authentification*: HTTP Basic authentication
* *Methods*: `Start` and `Stop`
* *Parameters*:
  - `user`    _(string)_: Username that registered the device
  - `mac`     _(string)_: MAC address of the device
  - `ip`      _(string)_: IP address of the device
  - `role`    _(string)_: PacketFence role assigned to the device
  - `timeout` _(int)_:    Duration until the registration expires in seconds
* *Response*: Success must be indicated by `"result": ["OK"]`. Every string other than `OK` is taken as an error message.

A simple JSON-RPC server written in Python that is compatible with this specification and creates ipsets based on the SSO information provided by PacketFence can be found at https://github.com/tribut/ipset-rpcd.

==== SSO Configuration in PacketFence

Go to *'Configuration' -> 'Integration' -> 'Firewall SSO' -> 'Add Firewall' -> 'JSONRPC'*.

[options="compact"]
* *Hostname or IP Address*: IP of your JSON-RPC server
* *Username* and *Password*: HTTP Basic credentials
* *Port of the service*: 9090
* *Roles*: Add the roles that you want to do SSO with

image::doc-jsonrpc-cfg_sso_pf.png[scaledwidth="100%",alt="Configure the JSON-RPC SSO in PacketFence"]
