New Releases for Cerberus and Eve

Yesterday Cerberus 0.8.1 was released with a few little fixes, one of them being more a new feature than a fix really: sub-document fields can now be set as field dependencies by using a ‘dotted’ notation.

So, suppose we set the following validation schema:

schema = {
  'test_field': {
    'dependencies': [
  'a_dict': {
    'type': 'dict',
      'schema': {
        'foo': {'type': 'string'},
        'bar': {'type': 'string'}

Then, we can validate a document like this:

>>> v = Validator(schema)
>>> document = {
      'test_field': 'foobar', 
      'a_dict': {'foo': 'foo'}

>>> v.validate(document, schema)

>>> v.errors
{'test_field': "field '' is required"}

This release will not work with Eve 0.5.2 or less so if you want to use Cerberus 0.8.1 with Eve make sure you upgrade to Eve 0.5.3, released today.

By the way, yesterday we hit 2K stargazers and 70 contributors on the Eve repository, quite the milestone!

If you want to get in touch, I am @nicolaiarocci on Twitter.

Attention is a Resource

Today, the New York Times’ SundayReview features a great column by Matthew B. Crawford: The Cost of Paying Attention.

Attention is a resource; a person has only so much of it […] What if we saw attention in the same way that we saw air or water, as a valuable resource that we hold in common? Perhaps, if we could envision an “attentional commons,” then we could figure out how to protect it.

Fattura Elettronica Open Source

this post is about an all-italian open source release, so it’s going to be in italian

FatturaElettronicaPA è un nuovo progetto open source che ho rilasciato qualche giorno fa assieme alla mia azienda. Si tratta di una libreria C# che permette di leggere, scrivere e convalidare le Fatture Elettroniche aderenti alle specifiche del sistema di interscambio della Pubblica Amministrazione. Continue reading

On Sustainable Open Source Management

Tom Christie has some very good things to say on how to successfully maintain an open source project without losing sanity.

Truth one: There are, and will always be, a non-finite number of possible valid issues to address. Your code can always be better polished, your APIs better defined, and your project more fully featured. Your documentation can always be better. The ecosystem within which your project lives is constantly evolving. You will never run out of things you could work on. Ever.

Truth two: You have finite resources. Damn.

If you are an open source maintainer, contributor or even a user do yourself a favour and read what Tom has to say on the subject. Tom is the creator and maintainer of the Django REST Framework, a hugely successful open source project so he really knows what he’s talking about. And for what is worth, his conclusions mirror mines.

On a completely unrelated note, I met Tom at EuroPython 2014. He was so nice to come and meet me minutes after I was done delivering my REST API for Humans talk. Good vibes.

How about a Sentinel for your Flask Application?

Flask-Sentinel is a OAuth2 Server implementation of the Resource Owner Password Credentials Grant pattern described in Section 1.3.3 of RFC 6749. It is powered by Flask-Oauthlib, Redis and MongoDB and is bundled as a Flask extension so it can be used to add OAuth2 capabilities to an existing application.

So what is the Resource Owner Password Credentials Grant pattern? According to the official RFC:

The resource owner password credentials (i.e., username and password) can be used directly as an authorization grant to obtain an access token. The credentials should only be used when there is a high degree of trust between the resource owner and the client (e.g., the client is part of the device operating system or a highly privileged application).

A typical use case would be when the remote API maintainer controls the client application. Say that you have a REST API being consumed by your own iOS, Android, WinPhone, desktop or web applications. Users register to your service by creating their accounts. Then, they consume the service using your applications.

Even though this grant type requires direct client access to the resource owner credentials, the resource owner credentials are used for a single request and are exchanged for an access token. This grant type can eliminate the need for the client to store the resource owner credentials for future use, by exchanging the credentials with a long-lived access token or refresh token.

So let’s get back at the proprietary client scenario. The user has just installed the application on his/her device. On first run he/she is asked to provide his/her username and password. These are sent to the OAuth2 server through a SSL/TLS encrypted channel. If the user is registered for the service and the client id, which has also been sent along with the user credentials, is recognised, then the server sends back a valid access token. Otherwise responds with a 401 Unhautorized.

From now on the application will only be using the access token for all requests until, eventually, the token expires. If that happens, the cycle repeats. Please note that in this scenario the client does not need to (and probably should not) store the username and/or password on the local cache. The User Credentials pattern usually relies on long lived tokens so asking again for username and password is not a big deal (you could also opt for permanent, revokable tokens.)

Flask-Sentinel provides two endpoints: one for token creation which defaults to /oauth/token and is consumed by clients, and another for users and clients management, accessible at /oauth/management:

API Management
Note that the password is hashed and salted on the server, so no plain password is stored on either sides of the channel.

Only existing users and recognised clients will be provided an access token. A typical token request would be as follows:

$ curl -k -X POST -d \
   password=pass" \

And the response would be like so:

    "access_token": "NYODXSR8KalTPnWUib47t5E8Pi8mo4", 
    "token_type": "Bearer", 
    "refresh_token": "s6L6OPL2bnKSRSbgQM3g0wbFkJB4ML", 
    "scope": ""

The client can now use the access token to access protected API endpoints:

$ curl -k -H \
  "Authorization:Bearer NYODXSR8KalTPnWUib47t5E8Pi8mo4" \

200 OK

There are a number of configuration options of course, for example you can change the url of token and management endpoints, set token expiration, setup database connection, stuff like that. Redis is used to store active access tokens, allows for optimal performance.

While you can use Flask-Sentinel to extend an existing API, you might want to instance it as a stand-alone Flask application to optimize for scalability. You would end up with a distributed network of three different (micro)services: the OAuth2 server, the resouces API with protected endpoints as needed, and the Redis instance bridging the two. Check out the project page on GitHub for details.

Of course Flask-Sentinel integrates seamlessly with any Eve powered REST API. Check out the Eve-OAuth2 sample, a fork of the original Eve-Demo project with a couple protected endpoints and a static HTML page, also protected.

The project is very new and lacks a few little things, but I suspect it is already usable even at this stage. Enjoy!

If you want to get in touch, I am @nicolaiarocci on Twitter.