Account Management
Creating a User Account
Create a user account by performing an HTTP POST
or PUT
with a
unique email address and username. Here’s an example:
curl -X POST http://localhost:8080/riak-cs/user /
-H 'Content-Type: application/json' /
--data '{"email":"foobar@example.com", "name":"foo bar"}' /
By default, only the admin user may create new user accounts. If you need to
create a user account without authenticating yourself, you must set
{anonymous_user_creation, true}
in the Riak CS app.config
.
The submitted user document may be either JSON or XML, but the type
should match the value of the Content-Type
header used. Here are some
examples for JSON and XML input formats.
{
"email": "foobar@example.com",
"name": "foo bar"
}
<User>
<Email>foobar@example.com</Email>
<Name>foo bar</Name>
</User>
The response will be in JSON or XML, and resembles the following examples.
{
"email": "foobar@example.com",
"display_name": "foobar"
"key_id": "324ABC0713CD0B420EFC086821BFAE7ED81442C",
"key_secret": "5BE84D7EEA1AEEAACF070A1982DDA74DA0AA5DA7",
"name": "foo bar",
"id": "8d6f05190095117120d4449484f5d87691aa03801cc4914411ab432e6ee0fd6b",
"buckets": []
}
<User>
<Email>foobar@example.com</Email>
<DisplayName>foobar</DisplayName>
<KeyId>324ABC0713CD0B420EFC086821BFAE7ED81442C</KeyId>
<KeySecret>5BE84D7EEA1AEEAACF070A1982DDA74DA0AA5DA7</KeySecret>
<Name>foo bar</Name>
<Id>8d6f05190095117120d4449484f5d87691aa03801cc4914411ab432e6ee0fd6b</Id>
<Buckets></Buckets>
</User>
Once the user account exists, you can use the key_id
and key_secret
to authenticate requests with Riak CS. To do that, add the key_id
and
key_secret
values to your s3cmd configuration file, which is located
by default in the ~/.s3cmd
folder,
The canonical id represented by the id
field can be used as an
alternative to an email address for user identification when granting or
revoking ACL permissions, for example with the --acl-grant
or
--acl-revoke
options to s3cmd setacl
.
Retrieving User Account Information
A user may retrieve their account information by sending a properly
signed request to the riak-cs/user
resource. Additionally, the admin
user may request the information for any individual user on the system
as part of their role as administrator. Users are only permitted to
retrieve information for their account.
Assuming the proper credentials were set in the .s3cfg
file, an s3/
request to retrieve this information would look like this:
s3cmd get s3://riak-cs/user -
Using the admin credentials to retrieve another user’s info would look like this:
s3cmd -c ~./s3cfg-admin get s3://riak-cs/user/XQKMYF4UL_MMTDFD6NCN
In this example, XQKMYF4UL_MMTDFD6NCN
is the key_id
of the user
whose information the administrator wishes to retrieve.
Modifying User Account Information
Changing the User Account Name and Email Address
A user may use a PUT
to /riak-cs/user
to update the name and email
address associated with an account. The PUT
must include a document
with a name and email field. JSON or XML formats are supported for this
document. Samples of each are shown below. The Content-Type
header
should also be set appropriately. The admin user may also update a
user’s account via a PUT
to /riak-cs/user/<user-key-id>
. The value
for the email field must be a valid email address and must not be
already used by another user account in the system. Violation of either
condition results in an error response.
Sample JSON and XML status update documents:
{
"name": "foobaz",
"email": "foobaz@example.com"
}
<?xml version="1.0" encoding="UTF-8"?>
<UserUpdate>
<Name>foobaz</Name>
<Email>foobaz@example.com</Email>
</UserUpdate>
Enabling and Disabling a User Account
A user may use a PUT
to /riak-cs/user
to disabled their account. The
PUT
must include a document with a status field whose value is
disabled. JSON or XML formats are supported for this document. Samples
of each are shown below. The Content-Type
header should also be set
appropriately. The admin user may also disable or re-enable a user’s
account via a PUT
to /riak-cs/user/<user-key-id>
. Users may not
re-enable their own account once it is disabled.
Sample JSON and XML status update documents:
{
"status": "enabled"
}
<?xml version="1.0" encoding="UTF-8"?>
<UserUpdate>
<Status>disabled</Status>
</UserUpdate>
Issuing New User Credentials
The key_secret
for a user account can be reissued by a PUT
to
/riak-cs/user
with the appropriate JSON or XML document. For admin
users, the PUT
would be to /riak-cs/user/<key-id>
.
The documents should resemble the following examples.
{
"new_key_secret": true
}
<?xml version="1.0" encoding="UTF-8"?>
<UserUpdate>
<NewKeySecret>true</NewKeySecret>
</UserUpdate>
The new_key_secret
field (or NewKeySecret
in XML) may be combined with
other user update fields in the same request. Currently, the only other
supported field is status, but more may be added in the future. Unsupported
fields are ignored.
Retrieving a List of All Users
The admin user may retrieve a list of all user accounts on the system.
This accomplished via a properly signed HTTP GET
request to the
/riak-cs/users
resource. Any non-admin user request for the user list
is rejected and a 403 Forbidden
error is returned. This request does
not properly work with s3cmd, but can be performed using a less dogmatic
tool such as s3-curl.
You must modify the @endpoints
variable in the s3curl.pl
script to include
your Riak CS hostname so that the following example will return the list of
users.
A sample URL for a user listing request looks like this:
GET http://data.example.com/riak-cs/users -
An example using s3-curl that assumes properly specified credentials for
the admin user in the .s3curl
configuration file with an id
of
admin
is as follows:
s3curl --id admin -- http://data.mystorage.me/riak-cs/users
By default, the listing of all users includes accounts that are both enabled and disabled. The list can be filtered to only include enabled or disabled accounts by using the status query parameter with a value of enabled or disabled respectively.