Taming Dynamic Data with Table Designer
CKAN 2.11 introduces Table Designer: form builder and enforced validation for your data
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.
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:
ckan user token add
command or via the API using the api_token_create action.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.
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.
CKAN 2.11 introduces Table Designer: form builder and enforced validation for your data
Packed with enhancements and fixes, this CKAN version is the most performant ever.