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.

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"
        ]
    }
}

Alternatively, accounts can be created using POST. Supply the user id and password in the request body and remove user id from the URL. The following request is equivalent to the example PUT call:

$ echo '{"data": {"id": "bob", password": "azerty123"}}' | http POST http://localhost:8888/v1/accounts --verbose

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.