125 lines
2.9 KiB
ReStructuredText
125 lines
2.9 KiB
ReStructuredText
REST services
|
|
=============
|
|
|
|
LL::NG portal is a REST server that gives access to configuration,
|
|
session and also authentication.
|
|
|
|
Portal REST services
|
|
--------------------
|
|
|
|
Authentication
|
|
~~~~~~~~~~~~~~
|
|
|
|
The authentication service is always available with REST, you just need
|
|
to send credentials on portal URL. But by default, the portal is
|
|
protected by :ref:`one time tokens to prevent CSRF<security-portal>`.
|
|
You must disable them or set a rule (configuration parameter
|
|
``requireToken``) so token will not be required for REST requests, for
|
|
example:
|
|
|
|
.. code-block:: perl
|
|
|
|
$env->{HTTP_ACCEPT} !~ m:application/json:
|
|
|
|
|
|
Another solution is using the :doc:`REST auth/user/password backend<restauthuserpwdbackend>`.
|
|
|
|
API
|
|
^^^
|
|
|
|
Request parameters:
|
|
|
|
- Endpoint: ``/``
|
|
- Method: ``POST``
|
|
- Request headers:
|
|
|
|
- ``Accept``: ``application/json``
|
|
|
|
- POST data:
|
|
|
|
- ``user``: user login
|
|
- ``password``: user password
|
|
- xxx: optional parameters, like ``lmAuth`` if your portal uses
|
|
``Choice`` or ``spoofId`` to impersonate.
|
|
|
|
The JSON response fields are:
|
|
|
|
- ``result``: authentication result, ``0`` if it fails, ``1`` if it
|
|
succeed
|
|
- ``error``: error code, the corresponding error can be found in
|
|
:doc:`Portal error codes<error_codes>`
|
|
- ``id``: if authentication succeed, the session id is returned in this
|
|
field. This id is not returned if you call the REST endpoint with the
|
|
session cookie (which means you are already authenticated).
|
|
|
|
|
|
.. tip::
|
|
|
|
You can also get the cookie by reading the response header
|
|
``Cookie`` returned by the portal.
|
|
|
|
|
|
.. attention::
|
|
|
|
Before version 2.0.4, the response to a success
|
|
authentication had no ``id`` field, and ``error`` field was named
|
|
``code``.
|
|
|
|
Example
|
|
^^^^^^^
|
|
|
|
- Request with curl:
|
|
|
|
::
|
|
|
|
curl -H "Accept: application/json" -d user=rtyler -d password=rtyler http://auth.example.com/ | json_pp
|
|
|
|
|
|
.. attention::
|
|
|
|
With ``cURL > 7.18.0``, to include special characters
|
|
like @, & or + in the cURL POST data:
|
|
|
|
::
|
|
|
|
curl -H "Accept: application/json" -d name=rtyler --data-urlencode passwd=@31&3+*J http://auth.example.com/ | json_pp
|
|
|
|
|
|
|
|
- Response for bad authentication:
|
|
|
|
.. code-block:: javascript
|
|
|
|
{
|
|
"result" : 0,
|
|
"error" : 5
|
|
}
|
|
|
|
- Response for good authentication:
|
|
|
|
.. code-block:: javascript
|
|
|
|
{
|
|
"result" : 1,
|
|
"error" : "0",
|
|
"id" : "b048bf87ca401da1d89419813e3acf466d5e4465fe3a1f7adfd8240bd161bde2"
|
|
}
|
|
|
|
Sessions
|
|
~~~~~~~~
|
|
|
|
REST functions for sessions are protected by Web Server, you can change
|
|
this in :ref:`portal configuration<configlocation-portal>`.
|
|
|
|
See :doc:`REST session backend documentation<restsessionbackend>` for
|
|
more.
|
|
|
|
Configuration
|
|
~~~~~~~~~~~~~
|
|
|
|
REST functions for configuration are protected by Web Server, you can
|
|
change this in :ref:`portal configuration<configlocation-portal>`.
|
|
|
|
See :doc:`REST configuration backend documentation<restconfbackend>` for
|
|
more.
|