120 lines
2.7 KiB
ReStructuredText
120 lines
2.7 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 :doc:`one time tokens to prevent CSRF<security>`. You must
|
||
|
disable them or set a rule (configuration parameter ``requireToken``) so
|
||
|
token will not be required for REST requests, for example:
|
||
|
|
||
|
.. code:: perl
|
||
|
|
||
|
$env->{HTTP_ACCEPT} !~ m:application/json:
|
||
|
|
||
|
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
|
||
|
``Lemonldap::NG::Portal::Main::Constants``
|
||
|
- ``id``: if authentication succeed, the session id is returned in this
|
||
|
field
|
||
|
|
||
|
|
||
|
.. tip::
|
||
|
|
||
|
You can also get the cookie by reading the response header
|
||
|
``Cookie`` returned by the portal.
|
||
|
|
||
|
|
||
|
.. important::
|
||
|
|
||
|
Before version 2.0.4, the response to a success
|
||
|
authentication had no ``id`` field, and ``error`` field was named
|
||
|
``code`` *(use Cookie header to get id value)*.
|
||
|
|
||
|
Example
|
||
|
^^^^^^^
|
||
|
|
||
|
- Request with curl:
|
||
|
|
||
|
::
|
||
|
|
||
|
curl -H "Accept: application/json" -d user=rtyler -d password=rtyler http://auth.example.com/ | json_pp
|
||
|
|
||
|
|
||
|
.. important::
|
||
|
|
||
|
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:: javascript
|
||
|
|
||
|
{
|
||
|
"result" : 0,
|
||
|
"error" : 5
|
||
|
}
|
||
|
|
||
|
- Response for good authentication:
|
||
|
|
||
|
.. code:: javascript
|
||
|
|
||
|
{
|
||
|
"result" : 1,
|
||
|
"error" : "0",
|
||
|
"id" : "b048bf87ca401da1d89419813e3acf466d5e4465fe3a1f7adfd8240bd161bde2"
|
||
|
}
|
||
|
|
||
|
Sessions
|
||
|
~~~~~~~~
|
||
|
|
||
|
REST functions for sessions are protected by Web Server, you can change
|
||
|
this in :doc:`portal configuration<configlocation>`.
|
||
|
|
||
|
See :doc:`REST session backend documentation<restsessionbackend>` for
|
||
|
more.
|
||
|
|
||
|
Configuration
|
||
|
~~~~~~~~~~~~~
|
||
|
|
||
|
REST functions for configuration are protected by Web Server, you can
|
||
|
change this in :doc:`portal configuration<configlocation>`.
|
||
|
|
||
|
See :doc:`REST configuration backend documentation<restconfbackend>` for
|
||
|
more.
|