Upcoming authentication changes in CKAN 2.10

Now that the upcoming CKAN 2.10 release has started the final phase of stabilization and testing, it is a good time to look ahead and check how some of its new features and changes may affect your CKAN site and workflows when you upgrade. We’ve been collecting some migration tips in the CKAN 2.9 to 2.10 Migration Guide but wanted to highlight a couple of them specifically focused on security and authentication.

Several changes in CKAN 2.10 are focused on increasing the overall security of CKAN, with big internal changes in how users are authenticated and requests validated, so we will look at some of them which will impact how both external users and extensions interact with CKAN and its API.

Dropped support for API keys, long live API tokens

CKAN 2.9 introduced API tokens as the preferred way of authenticating when using the API. These replaced the old legacy API keys, and are used in exactly the same way, adding them to an Authorization header in the request.

🚫 API key -> Authorization: ec5c0860-9e48-41f3-8850-4a7128b18df8

✅ API token -> Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiI0MFhFbldxNk0tVnNYbDdISi14eU02YXVPc25uMzl4Z25GOVRqV0hVOFpaSjhNa2NaaFprUVF3Yk8xdkljaHNqbGZlcFcwN0pFaV9TOVcwYiIsImlhdCI6MTY2Mzc2MDI5NywiZXhwIjoxNjYzNzcyMjk3fQ.nK27uHVmmhPoFrp8iNi9tS_DnG0uxmxkvJT9vLIv0ZY

API tokens are significantly more secure, as they are stored encrypted in the database, can be created and revoked as many times as needed and can be set to expire at a certain time (when using the expire_api_token plugin).

Starting from CKAN 2.10, API keys are no longer supported, and all API requests that authenticate using the Authorization header must use API tokens.

Some things to consider:

• Users don't have associated tokens by default. These can be created in the UI, in the command line with the ckan user token add command or via the API using the api_token_create action.
• External services that relied on API keys to perform API actions like the XLoader or the DataPusher will need to be reconfigured to use a token instead. Check the relevant READMEs for details on how to do that.

Built-in CSRF protection

While it is possible to add protection against CSRF attacks to previous CKAN versions, this needs to be done via extensions and in many cases customized to fit each site needs.

CKAN 2.10 incorporates a generic, built-in CSRF protection in all forms by default, and extensions that implement forms to send data will need to include the CSRF input field in their requests.

This is as easy as including a helper in your form, which will include the necessary markup with the correct CSRF token:

<form class="dataset-form form-horizontal" method="post" enctype="multipart/form-data">
    {{ h.csrf_input() }}

Extension maintainers that need to keep compatibility with older versions of CKAN can add an extra check to only use the helper if it is defined on that particular CKAN version:

<form class="dataset-form form-horizontal" method="post" enctype="multipart/form-data">
     {{ h.csrf_input() if 'csrf_input' in h }}

Forms that are submitted via JavaScript modules also need to submit the CSRF token, here’s an example of how to append it to an existing form:

// Get the csrf value from the page meta tag
var csrf_value = $('meta[name=_csrf_token]').attr('content')

// Create the hidden input
var hidden_csrf_input = $('<input name="_csrf_token" type="hidden" value="'+csrf_value+'">')

// Insert the hidden input at the beginning of the form
hidden_csrf_input.prependTo(form)

API calls performed from JavaScript modules from the UI (which use cookie-based authentication) should also include the token, in this case in the X-CSRFToken header. CKAN Modules using the builtin client to perform API calls will have the header added automatically. If you are performing API calls directly from a UI module you will need to add the header yourself.

API calls and cookie-based authentication

As mentioned above, API calls made from UI JavaScript modules will use cookie-based authentication (and thus need to send the CSRF token alongside the request). Site maintainers can choose to completely ignore cookie-based authentication by using the ckan.auth.enable_cookie_auth_in_api configuration option. When set to False, all API requests must use API Tokens. Note that this is likely to break some existing JS widgets and view plugins, so it should be used with caution.

---

If you have questions about these or other CKAN 2.10 changes, feel free to start a Discussion, ask on Gitter or jump to one of our Developer Meetings.