.. _authentication:

How to authenticate users?
==========================

Out of the box, the embedded Web server of Orthanc supports `HTTP
Basic access authentication
<https://en.wikipedia.org/wiki/Basic_access_authentication>`__. To
configure user authentication for Orthanc, make sure to properly set
the following :ref:`configuration options <configuration>`:

* ``RemoteAccessAllowed`` to ``true``.
* ``AuthenticationEnabled`` to ``true``.
* In ``RegisteredUsers``, assign a username and a password to all your
  users.

**Important:** Make sure to read the FAQ about :ref:`how to secure
Orthanc <security>`.
  
Once a user has logged in, she will have full access, in read-write
mode, to all the features offered by the REST API of Orthanc. This
built-in mechanism might be of limited usefulness in enterprise
scenarios, for which you would need features such as:

* Fine-grained access to the REST resources (e.g. restrict the URIs
  that are visible per user).
* Read-only access (i.e. limit full access to a short list of trusted
  system administrators).
* Integration with an LDAP server.
* Handling groups of users.
* ...

Depending on your scenario, you can consider the following options:

* Implement a Lua callback to :ref:`filter incoming REST requests
  <lua-filter-rest>`. This is the most simple solution, and would
  notably allow you to implement read-only access or, more generally,
  `access control lists
  <https://en.wikipedia.org/wiki/Access_control_list>`__.
* Develop a :ref:`C/C++ plugin <creating-plugins>` that uses the
  ``OrthancPluginRegisterIncomingHttpRequestFilter()``, or a
  :ref:`Python plugin <python_authorization>` that uses
  ``orthanc.RegisterIncomingHttpRequestFilter()``. This solution is
  potentially useful if you wish to integrate with an LDAP server.
* Use Orthanc as a reverse proxy (e.g. behind :ref:`nginx <nginx>`,
  :ref:`Apache <apache>`, or :ref:`Microsoft IIS <iis>`), and use the
  authentication mechanisms of the main Web server.
* Create a :ref:`new Web user interface <improving-interface>` on the
  top of the REST API of Orthanc, using your favorite framework
  (Meteor, AngularJS, Ember.js, Node.js...).
* Pass an :ref:`authorization token <orthanc-explorer-authorization>` 
  in the url search params when opening the Orthanc Explorer.