Skip to content

Authorization Modes

The authorization mode decides how the MetaMiner Server (MMS) accepts REST API calls: with the token of an API client, or from the MMS machine only.

How it works

The mode is one MMS setting, Authorization for MMS API endpoints:, in the Server API Auth section of MetaMiner Administrator (MMA). It applies to every REST API endpoint: /fss/v1, /tab/credentials and /fss/backup.

Mode Stored as Who may call How
API clients TOKEN Any host that can reach the MMS port Each call sends Authorization: Bearer <token> with the token of an active API client. Anything else gets 401.
Local only NONE Callers on the MMS machine only (loopback: 127.0.0.0/8 and ::1) No credential. A call from any other host gets 401 with API_AUTH_REQUIRED, and nothing is run or changed.

Under Local only, a local caller acts as a full-access client named local, and the audit shows it under that name. An address the MMS cannot resolve as loopback is treated as remote.

Do not publish the API through a proxy under Local only

A reverse proxy on the MMS machine forwards remote calls as local ones. Under Local only that would let any host reach the API without a credential. To call the API from other machines, choose API clients.

Which mode applies

Situation Mode
Fresh installation API clients
Upgrade The configured mode is kept. A configuration without a value starts in Local only.
Unrecognised value in the configuration Treated as Local only, so a typing mistake cannot open the API to the network

You can seed the mode of a new installation with the JVM argument -Dmms.api.auth=TOKEN or -Dmms.api.auth=NONE. After that, change it in MMA.

Upgrading from a release where None accepted remote calls

Local only answers callers on the MMS machine only. A script on another host that called the API without a token now gets 401 API_AUTH_REQUIRED. Switch to API clients and give the script its own client.

Before you begin

  • Run MMA on the MMS machine.
  • Plan a short MMS restart: the new mode takes effect after it.
  • If you switch to API clients, plan to create a client for each script straight away (see Manage API Clients). Until a client exists, every remote API call is refused.

Steps

  1. In MMA, choose Preferences > Settings... and open Advanced.
  2. In Server API Auth, set Authorization for MMS API endpoints: to API clients or Local only.
  3. Save the settings.
  4. Restart the MMS.
  5. If you chose API clients, click Manage API Clients... and create the clients your scripts need. The button appears only while API clients is selected.

Verify

Call GET /fss/v1/info and read authMode in the answer: TOKEN for API clients, NONE for Local only.

curl -sS "https://<mms-host>:<port>/fss/v1/info" -H "Authorization: Bearer <token>"

(Invoke-RestMethod -Uri "https://<mms-host>:<port>/fss/v1/info" `
  -Headers @{ Authorization = "Bearer <token>" }).authMode

Under Local only, run the call on the MMS machine against http://127.0.0.1:<port> (or https:// if SSL is enabled) without the header.

Troubleshooting

Remote calls get 401 API_AUTH_REQUIRED

The mode is Local only and the call came from another machine. Switch to API clients, restart the MMS and send a client token.

Every remote call gets 401 after switching to API clients

No client exists yet, or the script sends a token that is not a client's. Create a client in MMA and give the script its token.

Next steps