state
draft

Admin API Authentication function

Summary

The authentication function of Node-RED supports the 'credentials' scheme and the 'strategy' scheme, but there is a problem that the Admin API can not be used in the 'strategy' scheme .

This design note proposes a feature that enables the execution of the Admin API even in the 'strategy' scheme by adding a customizable token-based authentication function.

Authors

@KazuhiroIto

Details

Current behavior

adminAuth defines the authentication scheme used by the Admin API.
The authentication scheme results in a token being generated.
This token is then included in future http requests to authenticate the request.
This authentication is done by comparing the token to the list of known tokens that Node-RED maintains.
For the 'credentials' scheme, tokens can be generated by doing an HTTP POST to /auth/token.
For the "strategy" scheme, this is not possible. Because the OAuth strategy requires interaction with the browser, the Admin API cannot be executed.

Adding a customizable token-based authentication function

Add a new option tokens and tokenHeader to adminAuth.

The tokens options is a user-defined function process that has a 'token' as an argument, and can verify the provided token. This function is called if the token is not recognized from Node-RED's internal token store.

The token is obtained from the existing Authorization header. If you want to get the token from any custom header, use the tokenHeader option. You can obtain a token from the specified header name instead of the authorization header by specifying the header name in tokenHeader option.

setting.js example:

adminAuth: {
  type: 'strategy',
  strategy : { ... },
  users: function(username) { ... },
  tokens: function(token) {
    return new Promise(function(resolve, reject) {
      // Do whatever work is needed to check token is valid
      if (valid) {
        // Resolve with the user object. It must contain
        // properties 'username' and 'permissions'
        var user = { username: 'admin', permissions: '*' };
        resolve(user);
      } else {
        // Resolve with null as this user does not exist
        resolve(null);
      }
    });
  },
  // Change the value to be set to the argument 'token' to
  // the specified header name.
  // If not specified, get from Authorization header.
  tokenHeader: '<token header name>'
}

curl example:

curl -H '<token header name>: <valid token>' http://localhost:1880/settings

History

2020-02-21 - Initial proposal submitted

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!