Accounts¶
When the built-in plugin kinto.plugins.accounts
is enabled in configuration,
it becomes possible to manage accounts via a new resource /accounts
.
Via this endpoint, users can sign-up, modify their password or delete their account. Administrators configured in settings can manage users accounts.
Important
This plugin is highly experimental
Setup¶
Add the following settings to the .ini
file:
# Enable built-in plugin.
kinto.includes = kinto.plugins.accounts
# Enable authenticated policy.
multiauth.policies = account
multiauth.policy.account.use = kinto.plugins.accounts.authentication.AccountsAuthenticationPolicy
# Allow anyone to create accounts.
kinto.account_create_principals = system.Everyone
You can use the create-user
command to create an admin:
kinto create-user --ini /etc/kinto.ini --username admin --password ThisIsN0tASecurePassword
You can then use it in your config:
# Allow anyone to create accounts.
kinto.account_create_principals = account:admin
kinto.account_write_principals = account:admin
Authentication¶
Accounts are defined using a username and a password, and uses Basic Authentication.
For example, once the bob
account has been created, you can check if authentication
works using the Hello view.
$ http GET http://localhost:8888/v1/ --auth bob:azerty123
GET /v1/ HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Authorization: Basic Ym9iOmF6ZXJ0eTEyMw==
Connection: keep-alive
Host: localhost:8888
User-Agent: HTTPie/0.9.8
HTTP/1.1 200 OK
Access-Control-Expose-Headers: Alert, Backoff, Content-Length, Retry-After
Content-Length: 448
Content-Type: application/json
Date: Tue, 21 Mar 2017 14:40:14 GMT
Server: waitress
X-Content-Type-Options: nosniff
{
"capabilities": {
"accounts": {
"description": "Manage user accounts.",
"url": "http://kinto.readthedocs.io/en/latest/api/1.x/accounts.html"
}
},
"http_api_version": 1.16,
"project_docs": "https://kinto.readthedocs.io/",
"project_name": "kinto",
"project_version": "6.1.0.dev0",
"settings": {
"batch_max_requests": 25,
"readonly": false
},
"url": "http://localhost:8888/v1/",
"user": {
"id": "account:bob",
"principals": [
"account:bob",
"system.Everyone",
"system.Authenticated"
]
}
}
Create account¶
-
PUT
/accounts/
(user_id)¶ Synopsis: Creates a new account. Anonymous
Example Request
$ echo '{"data": {"password": "azerty123"}}' | http PUT http://localhost:8888/v1/accounts/bob --verbose
PUT /v1/accounts/bob HTTP/1.1 Accept: application/json, */* Accept-Encoding: gzip, deflate Connection: keep-alive Content-Length: 36 Content-Type: application/json Host: localhost:8888 User-Agent: HTTPie/0.9.8 { "data": { "password": "azerty123" } }
Example Response
HTTP/1.1 201 Created Access-Control-Expose-Headers: Backoff, Retry-After, Content-Length, Alert Content-Length: 165 Content-Type: application/json Date: Tue, 21 Mar 2017 14:30:14 GMT Etag: "1490106614601" Last-Modified: Tue, 21 Mar 2017 14:30:14 GMT Server: waitress X-Content-Type-Options: nosniff { "data": { "id": "bob", "last_modified": 1490106614601, "password": "$2b$12$zlTlYet5v.v57ak2gEYyoeqKSGzLvwXF/.v3DGpT/q69LecHv68gm" }, "permissions": { "write": [ "account:bob" ] } }
By default, users can only create their own accounts. “Administrators”, meaning anyone who matches account_write_principals
, can create accounts for other users as well.
You can set account_create_principals
if you want to limit account creation to certain users. The most common situation is when you want to have a small number of administrators, who are responsible for creating accounts for other users. In this case, you should add the administrators to both account_create_principals
and account_write_principals
.
Change password¶
-
PUT
/accounts/
(user_id)¶ Synopsis: Changes the password for an existing account. Requires authentication
Example Request
$ echo '{"data": {"password": "azerty123"}}' | http PUT http://localhost:8888/v1/accounts/bob --verbose --auth 'bob:azerty123'
PUT /v1/accounts/bob HTTP/1.1 Accept: application/json Accept-Encoding: gzip, deflate Authorization: Basic Ym9iOmF6ZXJ0eTEyMw== Connection: keep-alive Content-Length: 36 Content-Type: application/json Host: localhost:8888 User-Agent: HTTPie/0.9.2 { "data": { "password": "azerty123" } }
Example Response
HTTP/1.1 200 OK Access-Control-Expose-Headers: Backoff, Alert, Content-Length, Retry-After Content-Length: 165 Content-Type: application/json Date: Tue, 21 Mar 2017 17:11:58 GMT Etag: "1490116321096" Last-Modified: Tue, 21 Mar 2017 17:12:01 GMT Server: waitress X-Content-Type-Options: nosniff { "data": { "id": "bob", "last_modified": 1490116321096, "password": "$2b$12$c12ui4O/z9gmVpGe1NMG2.Sb4zdw9p20oka2Seg3Xqq9rDpNR5HoW" }, "permissions": { "write": [ "account:bob" ] } }
Delete account¶
-
DELETE
/accounts/
(user_id)¶ Synopsis: Deletes an existing account. Requires authentication
Example Request
$ http DELETE http://localhost:8888/v1/accounts/bob --verbose --auth 'bob:azerty123'
DELETE /v1/accounts/bob HTTP/1.1 Accept: */* Accept-Encoding: gzip, deflate Authorization: Basic Ym9iOmF6ZXJ0eTEyMw== Connection: keep-alive Content-Length: 0 Host: localhost:8888 User-Agent: HTTPie/0.9.2
Example Response
HTTP/1.1 200 OK Access-Control-Expose-Headers: Backoff, Alert, Content-Length, Retry-After Content-Length: 66 Content-Type: application/json Date: Tue, 21 Mar 2017 17:18:14 GMT Etag: "1490116696859" Last-Modified: Tue, 21 Mar 2017 17:18:16 GMT Server: waitress X-Content-Type-Options: nosniff { "data": { "deleted": true, "id": "bob", "last_modified": 1490116696859 } }
Manage accounts¶
It is possible to configure administrators in settings. They will be able to manage others users accounts via the API.
First create the actual accounts:
$ echo '{"data": {"password": "azerty123"}}' | http PUT http://localhost:8888/v1/accounts/admin
Then mention the created accounts via the following settings in the .ini
file.
For example to account IDs admin
and members of the admin
groups in the bid
bucket:
# Give read/write access to all accounts to ``account:admin``.
kinto.account_write_principals = account:admin /buckets/bid/groups/admin
kinto.account_read_principals = account:admin /buckets/bid/groups/admin
Note
It is not very convenient to require a server restart for configuring administrators. But we thought it was acceptable as a first iteration.