API Authentication Methods

There are several ways to authenticate against the Micetro API:

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.

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:

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:

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 (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.

<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.

Single Sign-On

To enable single sign-on in the Web Interface, make sure that Single Sign-on and Single Sign-on for web is enabled in Micetro. See External Authentication (Management Console, obsolete).