Enable Basic Auth
Table of contents
- Quick reference
- Additional info
- Create a password file
- Enable basic auth at the Namespace level
- Enable auth at the HTTP listener level
Quick reference
FireFly has a pluggable auth system which can be enabled at two different layers of the stack. At the top, auth can be enabled at the HTTP listener level. This will protect all requests to the given listener. FireFly has three different HTTP listeners, which could each use a different auth scheme:
- The main API
- The SPI (for internal or admin use)
- The metrics API.
Auth can also be enabled at the namespace level within FireFly as well. This enables several different use cases. For example, you might have two different teams that want to use the same FireFly node, each with different sets of authorized users. You could configure them to use separate namespaces and create separate auth schemes on each.
FireFly has a basic auth plugin built in, which we will be configuring in this tutorial.
NOTE: This guide assumes that you have already gone through the Getting Started Guide and have set up and run a stack at least once.
Additional info
- Config Reference: HTTP Auth
- Auth plugin interface
- Basic auth plugin implementation
Create a password file
FireFly’s built in basic auth plugin uses a password hash file to store the list of authorized users. FireFly uses the bcrypt algorithm to compare passwords against the stored hash. You can use htpasswd
on a command line to generate a hash file.
Create the test_users
password hash file
touch test_users
Create a user named firefly
htpasswd -B test_users firefly
You will be prompted to type the password for the new user twice. Optional: You can continue to add new users by running this command with a different username.
htpasswd -B test_users <username>
Enable basic auth at the Namespace level
To enable auth at the HTTP listener level we will need to edit the FireFly core config file. You can find the config file for the first node in your stack at the following path:
~/.firefly/stacks/<stack_name>/runtime/config/firefly_core_0.yml
Open the config file in your favorite editor and add the auth
section to the plugins
list:
plugins:
auth:
- name: test_user_auth
type: basic
basic:
passwordfile: /etc/firefly/test_users
You will also need to add test_user_auth
to the list of plugins used by the default
namespace:
namespaces:
predefined:
- plugins:
- database0
- blockchain0
- dataexchange0
- sharedstorage0
- erc20_erc721
- test_user_auth
Mount the password hash file in the Docker container
If you set up your FireFly stack using the FireFly CLI we will need to mount the password hash file in the Docker container, so that FireFly can actually read the file. This can be done by editing the docker-compose.override.yml
file at:
~/.firefly/stacks/<stack_name>/docker-compose.override.yml
Edit the file to look like this, replacing the path to your test_users
file:
# Add custom config overrides here
# See https://docs.docker.com/compose/extends
version: "2.1"
services:
firefly_core_0:
volumes:
- PATH_TO_YOUR_TEST_USERS_FILE:/etc/firefly/test_users
Restart your FireFly Core container
To restart your FireFly stack and have Docker pick up the new volume, run:
ff stop <stack_name>
ff start <stack_name>
NOTE: The FireFly basic auth plugin reads this file at startup and will not read it again during runtime. If you add any users or change passwords, restarting the node will be necessary to use an updated file.
Test basic auth
After FireFly starts back up, you should be able to test that auth is working correctly by making an unauthenticated request to the API:
curl http://localhost:5000/api/v1/status
{"error":"FF00169: Unauthorized"}
However, if we add the username and password that we created above, the request should still work:
curl -u "firefly:firefly" http://localhost:5000/api/v1/status
{"namespace":{"name":"default","networkName":"default","description":"Default predefined namespace","created":"2022-10-18T16:35:57.603205507Z"},"node":{"name":"node_0","registered":false},"org":{"name":"org_0","registered":false},"plugins":{"blockchain":[{"name":"blockchain0","pluginType":"ethereum"}],"database":[{"name":"database0","pluginType":"sqlite3"}],"dataExchange":[{"name":"dataexchange0","pluginType":"ffdx"}],"events":[{"pluginType":"websockets"},{"pluginType":"webhooks"},{"pluginType":"system"}],"identity":[],"sharedStorage":[{"name":"sharedstorage0","pluginType":"ipfs"}],"tokens":[{"name":"erc20_erc721","pluginType":"fftokens"}]},"multiparty":{"enabled":true,"contract":{"active":{"index":0,"location":{"address":"0xa750e2647e24828f4fec2e6e6d61fc08ccca5efa"},"info":{"subscription":"sb-d0642f14-f89a-41bb-6fd4-ae74b9501b6c","version":2}}}}}
Enable auth at the HTTP listener level
You may also want to enable auth at the HTTP listener level, for instance on the SPI (Service Provider Interface) to limit administrative actions. To enable auth at the HTTP listener level we will need to edit the FireFly core config file. You can find the config file for the first node in your stack at the following path:
~/.firefly/stacks/<stack_name>/runtime/config/firefly_core_0.yml
Open the config file in your favorite editor and change the spi
section to look like the following:
spi:
address: 0.0.0.0
enabled: true
port: 5101
publicURL: http://127.0.0.1:5101
auth:
type: basic
basic:
passwordfile: /etc/firefly/test_users
Restart FireFly to apply the changes
NOTE You will need to mount the password hash file following the instructions above if you have not already.
You can run the following to restart your stack:
ff stop <stack_name>
ff start <stack_name>
Test basic auth
After FireFly starts back up, you should be able to query the SPI and the request should be unauthorized.
curl http://127.0.0.1:5101/spi/v1/namespaces
{"error":"FF00169: Unauthorized"}
Adding the username and password that we set earlier, should make the request succeed.
curl -u "firefly:firefly" http://127.0.0.1:5101/spi/v1/namespaces
[{"name":"default","networkName":"default","description":"Default predefined namespace","created":"2022-10-18T16:35:57.603205507Z"}]