.. meta::
   :description: API authentication methods including the login command in Micetro
   :keywords: Micetro's API, Micetro authentication

.. _api-auth:

API Authentication Methods
==========================

There are several ways to authenticate against the Micetro API:

* :ref:`api-login-command`

* :ref:`api-login-headers`

* :ref:`api-login-sso`

.. _api-login-command:

Login Command
-------------

This method is compatible with all versions of Micetro, and all every variant of the Micetro API (SOAP/JSON-RPC/REST). In the REST API, this command is accessible via the URL commands/Login.

The Login command requires a server (for the Micetro Central server), username, and password, and it returns a session ID. This session ID should be used for all other API calls via the session parameter.

The Login command and its parameters are fully documented in the standard API documentation.

.. note::
  Remember to configure HTTPS for the mmws and/or _mmws sites when using this authentication method to prevent usernames and passwords from being intercepted during communication.

.. _api-login-headers:

Authorization Headers
---------------------

API requests can be authenticated using the following Authorization HTTP headers:

* **Bearer**: Token-based authorization, which is the recommended authorization mechanism and is always enabled.
* **Negotate**: Single sign-on authorization mechanism using Kerberos or NTLM, which must be explicitly enabled.
* **Basic**: Authorization with a username and an obfuscated password included in every request, which can b. Can be disabled.

.. note::
  If AuthorizationMethods is not defined in the preference file, mmws will accept Bearer and Basic Authorization headers.

Using authorization headers for authentication eliminates the need to include the session ID in the request body. The "session" parameter should be omitted entirely from all commands, not just left blank.


Bearer Authentication
^^^^^^^^^^^^^^^^^^^^^
Bearer authentication, also known as token-based authentication, is a common method for securing Web APIs and is the preferred method for interacting with and authenticating the Micetro APIs.

A bearer token is an encrypted string typically generated by the server following a login request. The token serves as proof of authorization. 

When making requests to the Micetro API, send this token in the ``Authorization`` header:

.. code-block::

  Authorization: Bearer <token>

In REST, a session token can be generated by sending a POST request to the ``<server>/mmws/api/micetro/sessions`` endpoint with the body ``{ loginName: string, password: string }``. Then use the ``session`` in the response as the token.

For JSON-RPC, the login command is used to create a new session.

.. warning::
  Ensure that your Micetro endpoints use HTTPS to prevent interception of usernames and passwords during communication.

The Micetro API checks the token's validity. If it is valid, the client is granted access to the requested resource.


For more information about Bearer Authentication, see ???


Basic Authentication
^^^^^^^^^^^^^^^^^^^^

.. note::
  Basic Authentication requires only user IP and login password, presenting significant security risk. Consequently, its use is generally discouraged.


For Basic Authentication, simply include a HTTP header like:

.. code-block::

  Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

where the last part is ``<user name>:<password>``, base64 encoded.

For more information on Basic Authorization headers on the client side, see for example here: https://en.wikipedia.org/wiki/Basic_access_authentication

.. note::
  * Remember to configure HTTPS for the mmws site for this authentication method since the username and password can easily be extracted for anyone listening in on the communication.
  * Micetro can be configured to disable the Basic Authorization header by inserting ``<AuthorizationMethods value="" />`` into mmws preference file.

Negotiate Authentication
^^^^^^^^^^^^^^^^^^^^^^^^

Negotiate header Authorization, based on `SPNEGO <https://en.wikipedia.org/wiki/SPNEGO>`_ (Simple and Protected GSSAPI Negotiation Mechanism) for Kerberos and NTLM HTTP Authentication, is supported if suppored by the client supports and enabled in the Micetro Web Interface.

With this method, the username and password are not included in the header; instead the API call is made within the security context of the invoking user. In essence, this serves as the single sign-on authentication method provided by the Micetro Web Interface.

To enable Negotiate header Authorization in the Micetro Web Interface, add the following line to the ``preferences.cfg`` and restart the ``mmws`` service.

.. code-block::

  <AuthorizationMethods value="Kerberos,NTLM" />

You can change the order of the methods, for example, if NTLM is preferred over Kerberos. However, if you want to avoid using NTLM as a less secure fallback, specify only Kerberos as
a value.

.. _api-login-sso:

Single Sign-On
--------------

To enable single sign-on in the web application, make sure that Single Sign-on and Single Sign-on for web is enabled in Micetro. See :ref:`external-auth`.

..
  When using M&M Web Services as an API endpoint, refer to the Negotiate header Authorization section above.
  When using the M&M Web Extension that comes with the M&M Web Interface as an API endpoint, single sign-on is achieved by invoking a POST http request to
  .. code-block::
    http://<web server>/_mmwebext/mmwebext.dll?RequestSSO
  The body of the http request should include simply the M&M Central server name.
  If IIS is correctly configured (see :ref:`disable-kernel-mode-auth`), this request will return an XML similar to what the Login SOAP command would return:
  .. code-block:: XML
    <?xml version="1.0" encoding="utf-8"?><soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <soap:Body>
          <LoginResponse xmlns="http://menandmice.com/webservices/">
              <session>UzL9uSNNcLjmlRx1PQsP</session>
              <userName>mydomain\myuser</userName>
          </LoginResponse>
      </soap:Body>
    </soap:Envelope>
  The *session* should then be used for all subsequent API commands.