Table of Contents
When adminAuth is used to secure the editor and admin api, and is set to type credentials, here's how to login and access the API securely. It is an implementation of Resource Owner Password Credentials Grant of OAuth 2.0 (RFC 6749, Section 4.3).
The basic process is:
- obtain an access token
- provide that access token with any request to the api
- revoke the token when it is no longer required
More concretely, with example curl invocations:
-
Get a token by POST ing your username/password to /auth/token:
curl http://localhost:1880/auth/token --data 'client_id=node-red-editor&grant_type=password&scope=*&username=admin&password=password'
that gives you back something like:
{"access_token":"agm6RUh6jmEPApI8eO25uW1X3A7tYBJxzKe9Z0sIEYdhTTy5Rzh3uBUTCawxgAmHFaqNL0gxH9wijA12BslxOwo9eouqwOnQ1tYjpqTnH8EWRZfw7dtQDX21owA9KiPR", "token_type":"Bearer"}
-
use the "access_token" in the authorization header for subsequent requests:
curl -H "Authorization: Bearer agm6RUh6jmEPApI8eO25uW1X3A7tYBJxzKe9Z0sIEYdhTTy5Rzh3uBUTCawxgAmHFaqNL0gxH9wijA12BslxOwo9eouqwOnQ1tYjpqTnH8EWRZfw7dtQDX21owA9KiPR" http://localhost:1880/settings -
To revoke a token, post to /auth/revoke:
curl --data 'token=agm6RUh6jmEPApI8eO25uW1X3A7tYBJxzKe9Z0sIEYdhTTy5Rzh3uBUTCawxgAmHFaqNL0gxH9wijA12BslxOwo9eouqwOnQ1tYjpqTnH8EWRZfw7dtQDX21owA9KiPR' -H "Authorization: Bearer agm6RUh6jmEPApI8eO25uW1X3A7tYBJxzKe9Z0sIEYdhTTy5Rzh3uBUTCawxgAmHFaqNL0gxH9wijA12BslxOwo9eouqwOnQ1tYjpqTnH8EWRZfw7dtQDX21owA9KiPR" http://localhost:1880/auth/revoke
Access the editor
When the Editor attempts to access the API, it checks for an access_token in localStorage. If one is found, it automatically provides it with any subsequent request.
In what will be released as 0.10.5 (and already in git master), it also checks the query parameters for one called access_token - if that is found, that is used in place of anything found in localStorage. This allows a system that has already obtained a token through some other means to direct a user to the UI without requiring them to enter their credentials again. NB: if such a query parameter is found, after storing the token in localStorage, the page is reloaded to remove the query parameters.
If no access_token is found, it attempts to access /settings. If that succeeds, it proceeds to provide anonymous access to the editor. Otherwise, it does a GET request to /auth/login to get details of the require authentication scheme. Currently, only credentials is supported - but may, in the future, indicate other types of authentication such as oauth.
It then prompts the user for their details and performs the POST to /auth/token to get an access_token.