Managing Security Sources
If you’re looking for more general information on Riak Security, it may be best to start with our general guide to authentication and authorization.
This document provides more granular information on the four available
authentication sources in Riak Security: trusted networks, password,
pluggable authentication modules (PAM), and certificates. These sources
correspond to trust, password, pam, and certificate,
respectively, in the riak admin security interface.
The examples below will assume that the network in question is
127.0.0.1/32 and that a Riak user named riakuser has been
created and that
security has been enabled.
If you use any of the aforementioned security sources, even trust, you
will need to do so via a secure SSL connection.
Trust-based Authentication
This form of authentication enables you to specify trusted CIDRs from which all clients will be authenticated by default.
riak admin security add-source all 127.0.0.1/32 trust
Produces:
Successfully added source
ok
Here, we have specified that anyone connecting to Riak from the
designated CIDR (in this case localhost) will be successfully
authenticated:
curl https://localhost:8098/types/<type>/buckets/<bucket>/keys/<key>
If this request returns not found or a Riak object, then things have
been set up appropriately. You can specify any number of trusted
networks in the same fashion.
You can also specify users as trusted users, as in the following example:
riak admin security add-source riakuser 127.0.0.1/32 trust
Produces:
Successfully added source
ok
Now, riakuser can interact with Riak without providing credentials.
Here’s an example in which only the username is passed to Riak:
curl -u riakuser: \
https://localhost:8098/types/<type>/buckets/<bucket>/keys/<key>
Password-based Authentication
Authenticating via the password source requires that our riakuser be
given a password. riakuser can be assigned a password upon creation,
as in this example:
riak admin security add-user riakuser password=captheorem4life
Or a password can be assigned to an already existing user by modifying that user’s characteristics:
riak admin security alter-user riakuser password=captheorem4life
Produces:
ok
+----------+---------------+----------------------------------------+------------------------------+
| username | member of | password | options |
+----------+---------------+----------------------------------------+------------------------------+
| riakuser | |652517e4703dab90f693db95acaedeec55acb530| [] |
+----------+---------------+----------------------------------------+------------------------------+
ok
You can specify that all users must authenticate themselves via
password when connecting to Riak from localhost:
riak admin security add-source all 127.0.0.1/32 password
Or you can specify that any number of specific users must do so:
riak admin security add-source riakuser 127.0.0.1/32 password
riak admin security add-source otheruser 127.0.0.1/32 password
# etc
Now, our riakuser must enter a username and password to have any
access to Riak whatsoever:
curl -u riakuser:captheorem4life \
https://localhost:8098/types/<type>/buckets/<bucket>/keys/<key>
Certificate-based Authentication
This form of authentication (certificate) requires that Riak and a
specified client—or clients—interacting with Riak bear certificates
signed by the same Root Certificate
Authority.
Note
At this time, client certificates are not supported in Riak’s HTTP interface, and can be used only through the protocol buffers interface.
Let’s specify that our user riakuser is going to be authenticated
using a certificate on localhost:
riak admin security add-source riakuser 127.0.0.1/32 certificate
When the certificate source is used, riakuser must also be entered
as the common name, aka CN, that you specified when you generated your
certificate, as in the following OpenSSL example:
openssl req -new ... '/CN=riakuser'
You can add a certificate source to any number of clients, as long as
their CN and Riak username match.
On the server side, you need to configure Riak by specifying a path to
your certificates. First, copy all relevant files to your Riak cluster.
The default directory for certificates is /etc, though you can specify
a different directory in your riak.conf by either uncommenting those lines if you choose to use the defaults or setting the paths yourself:
ssl.certfile = /path/to/cert.pem
ssl.keyfile = /path/to/key.pem
ssl.cacertfile = /path/to/cacert.pem
In the client-side example above, the client’s CN and Riak username
needed to match. On the server (i.e. Riak) side, the CN specified on
each node must match the node’s name as registered by Riak. You can
find the node’s name in riak.conf under the parameter nodename. And so if the nodename for a cluster is
riak-node-1, you would need to generate your certificate with that in
mind, as in this OpenSSL example:
openssl req -new ... '/CN=riak-node-1'
Once certificates have been properly generated and configured on all of
the nodes in your Riak cluster, you need to perform a rolling restart. Once that process is complete, you can use the client
certificate that you generated for the user riakuser.
How to use Riak clients in conjunction with OpenSSL and other certificates varies from client library to client library. We strongly recommend checking the documentation of your client library for further information.
PAM-based Authentication
This section assumes that you have set up a PAM service bearing the name
riak_pam, e.g. by creating a pam.d/riak_pam service definition
specifying auth and/or other PAM services set up to authenticate a
user named riakuser. As in the certificate-based authentication
example above, the user’s name must be the same in both your
authentication module and in Riak Security.
If we want the user riakuser to use this PAM service on localhost,
we need to add a pam security source in Riak and specify the name of
the service:
riak admin security add-source all 127.0.0.1/32 pam service=riak_pam
Note: If you do not specify a name for your PAM service, Riak will
use the default, which is riak.
To verify that the source has been properly specified:
riak admin security print-sources
That command should output the following:
+--------------------+------------+----------+------------------------+
| users | cidr | source | options |
+--------------------+------------+----------+------------------------+
| riakuser |127.0.0.1/32| pam |[{"service","riak_pam"}]|
+--------------------+------------+----------+------------------------+
You can test that setup most easily by using curl. A normal request to
Riak without specifying a user will return an Unauthorized message:
curl -u riakuser: \
https://localhost:8098/types/<type>/buckets/<bucket>/keys/<key>
Response:
<html><head><title>401 Unauthorized</title></head><body><h1>Unauthorized</h1>Unauthorized<p><hr><address>mochiweb+webmachine web server</address></body></html>
If you identify yourself as riakuser and are successfully
authenticated by your PAM service, you should get either not found or
a Riak object if one is stored in the specified bucket type/bucket/key
path:
curl -u riakuser:<pam_password> \
https://localhost:8098/types/<type>/buckets/<bucket>/keys/<key>
How Sources Are Applied
When managing security sources—any of the sources explained
above—you always have the option of applying a source to either a
single user, multiple users, or all users (all). If specific users and
all have no sources in common, this presents no difficulty. But what
happens if one source is applied to all and a different source is
applied to a specific user?
The short answer is that the more specifically assigned source—i.e. to
the user—will be consider a user’s security source. We’ll illustrate
that with the following example, in which the certificate source is
assigned to all, but the password source is assigned to riakuser:
riak admin security add-source all 127.0.0.1/32 certificate
riak admin security add-source riakuser 127.0.0.1/32 password
If we run riak admin security print-sources, we’ll get the following
output:
+--------------------+------------+-----------+----------+
| users | cidr | source | options |
+--------------------+------------+-----------+----------+
| riakuser |127.0.0.1/32| password | [] |
| |127.0.0.1/32|certificate| [] |
| all |127.0.0.1/32|certificate| [] |
+--------------------+------------+-----------+----------+
As we can see, password is set as the security source for riakuser,
whereas everyone else will authenticate using certificate.