26 |
27 | ## Introduction
28 |
29 | **Django REST Framework API Key is a powerful library for allowing server-side clients to safely use your API.** These clients are typically third-party backends and services (i.e. _machines_) which do not have a user account but still need to interact with your API in a secure way.
30 |
31 | ### Features
32 |
33 | - ✌️ **Simple to use**: create, view and revoke API keys via the admin site, or use built-in helpers to create API keys programmatically.
34 | - 🔒 **As secure as possible**: API keys are treated with the same level of care as user passwords. They are only visible at creation and hashed before storing in the database.
35 | - 🎨 **Customizable**: satisfy specific business requirements by building your own customized API key models, permission classes and admin panels.
36 |
37 | ### Should I use API keys?
38 |
39 | There are important security aspects you need to consider before switching to an API key access control scheme. We've listed some of these in [Security caveats](security.md#caveats), including serving your API over HTTPS.
40 |
41 | Besides, see [Why and when to use API keys](https://cloud.google.com/endpoints/docs/openapi/when-why-api-key#top_of_page) for hints on whether API keys can fit your use case.
42 |
43 | API keys are ideal in the following situations:
44 |
45 | - Blocking anonymous traffic.
46 | - Implementing API key-based [throttling](https://www.django-rest-framework.org/api-guide/throttling/). (Note that Django REST Framework already has many built-in utilities for this use case.)
47 | - Identifying usage patterns by logging request information along with the API key.
48 |
49 | They can also present enough security for authorizing internal services, such as your API server and an internal frontend application.
50 |
51 | !!! warning
52 | Please note that this package is NOT meant for authentication. You should NOT use this package to identify individual users, either directly or indirectly.
53 |
54 | If you need server-to-server authentication, you may want to consider OAuth instead. Libraries such as [django-oauth-toolkit](https://django-oauth-toolkit.readthedocs.io/en/latest/index.html) can help.
55 |
56 | ## Quickstart
57 |
58 | Install with `pip`:
59 |
60 | ```bash
61 | pip install "djangorestframework-api-key==3.*"
62 | ```
63 |
64 | !!! important
65 | It is highly recommended to **pin your dependency** to the latest major version (as depicted above), as breaking changes may and will happen between major releases.
66 |
67 | Add the app to your `INSTALLED_APPS`:
68 |
69 | ```python
70 | # settings.py
71 |
72 | INSTALLED_APPS = [
73 | # ...
74 | "rest_framework",
75 | "rest_framework_api_key",
76 | ]
77 | ```
78 |
79 | Run the included migrations:
80 |
81 | ```bash
82 | python manage.py migrate
83 | ```
84 |
85 | To learn how to configure permissions and manage API keys, head to the [User Guide](guide.md).
86 |
--------------------------------------------------------------------------------
/docs/security.md:
--------------------------------------------------------------------------------
1 | # Security
2 |
3 | ## Implementation details
4 |
5 | ### Key generation scheme
6 |
7 | An API key is composed of two items:
8 |
9 | - A prefix `P`, which is a generated string of 8 characters.
10 | - A secret key `SK`, which is a generated string of 32 characters.
11 |
12 | The generated key that clients use to [make authorized requests](#making-authorized-requests) is `GK = P.SK`. It is treated with the same level of care as passwords:
13 |
14 | - Only a hashed version is stored in the database. The hashing algorithm is sha512. [^1]
15 | - The generated key is shown only once to the client upon API key creation.
16 |
17 | [^1]: Older versions of this module used the same hashers as Django's [`PASSWORD_HASHERS`](https://docs.djangoproject.com/en/2.2/ref/settings/#std:setting-PASSWORD_HASHERS). These hashers come with a large performance penalty and while critical for passwords, they aren't needed for high-entropy, randomly generated keys like the ones created by this module. Keys stored using these slower hashers will be upgraded when used.
18 |
19 | ### Grant scheme
20 |
21 | Access is granted if and only if all of the following is true:
22 |
23 | 1. The configured API key header is present and correctly formatted. [^3]
24 | 2. A usable API key with the prefix of the given key exists in the database. [^4]
25 | 3. The hash of the given key matches that of the API key.
26 |
27 | [^3]: To customize this behavior, see [API key parsing](guide.md#api-key-parsing).
28 | [^4]: Only unrevoked keys are usable by default, but this can be customized with a [custom manager](guide.md#managers).
29 |
30 | ## Caveats
31 |
32 | [API keys ≠ Security](https://nordicapis.com/why-api-keys-are-not-enough/): depending on your situation, you should probably not use API keys only to authorize your clients.
33 |
34 | Besides, it is NOT recommended to use this package for authentication, i.e. retrieving user information from API keys.
35 |
36 | Indeed, **using API keys shifts the responsibility of Information Security on your clients**. This induces risks, especially if obtaining an API key gives access to confidential information or write operations. For example, an attacker could impersonate clients if they let their API keys leak.
37 |
38 | As a best practice, you should apply the _Principle of Least Privilege_: allow only those who require resources to access those specific resources. In other words: **if your client needs to access an endpoint, add API permissions on that endpoint only** instead of the whole API.
39 |
40 | Besides, it is highly recommended to serve the API over **HTTPS** to ensure the confidentiality of API keys passed in requests.
41 |
42 | Act responsibly!
43 |
--------------------------------------------------------------------------------
/docs/upgrade/1.0.md:
--------------------------------------------------------------------------------
1 | # Upgrading to 1.0
2 |
3 | ## Introduction
4 |
5 | **The 1.0 release is incompatible with 0.x**. It introduces a new and more transparent API key generation and validation scheme which allows to pass it in a single header, instead of two previously.
6 |
7 | This document lists the steps necessary to upgrade from 0.x to 1.0.
8 |
9 | ## Steps
10 |
11 | ### 1. Backup existing API keys
12 |
13 | Unfortunately, it is not possible to provide a migration that would preserve existing API keys. This is because the cryptographic generation and validation methods have changed fundamentally, which means that new keys cannot be inferred from existing ones.
14 |
15 | As a result, **all existing API keys will be destroyed** during Step 1/ described below. You may want to backup the existing data so that you can regenerate keys notify clients once migration is complete.
16 |
17 | ### 2. Reset migrations
18 |
19 | **This step will destroy existing API keys**. It is necessary for the new migrations to run correctly.
20 |
21 | ```bash
22 | python manage.py migrate rest_framework_api_key zero
23 | ```
24 |
25 | ### 3. Upgrade
26 |
27 | ```bash
28 | pip install "djangorestframework-api-key==1.0.*"
29 | ```
30 |
31 | ### 4. Run migrations
32 |
33 | ```bash
34 | python manage.py migrate rest_framework_api_key
35 | ```
36 |
--------------------------------------------------------------------------------
/docs/upgrade/1.4.md:
--------------------------------------------------------------------------------
1 | # Upgrading to 1.4
2 |
3 | ## Introduction
4 |
5 | The 1.4 release includes a migration that adds and populates the `prefix` and `hashed_key` fields to API keys.
6 |
7 | This document lists the steps necessary to upgrade from 1.3.x to 1.4.
8 |
9 | ## Steps
10 |
11 | ### 1. Migrate the built-in API key model
12 |
13 | The `APIKey` model can be migrated using the migration shipped with this package:
14 |
15 | ```bash
16 | python manage.py migrate rest_framework_api_key
17 | ```
18 |
19 | ### 2. Migrate custom API key models (if applicable)
20 |
21 | If you have a custom API key model deriving from `AbstractAPIKey`, you need to **manually add the migration** to your application.
22 |
23 | - Copy the migration script below to your app's `migrations/` directory. Be sure to modify `APP_NAME`, `MODEL_NAME` and `DEPENDENCIES` as seems fit. You can name the migration script `xxxx_prefix_hashed_key.py` (replace `xxxx` with the next available migration ID).
24 |
25 | ```python
26 | --8<-- "src/rest_framework_api_key/migrations/0004_prefix_hashed_key.py"
27 | ```
28 |
29 | - Apply the migration:
30 |
31 | ```bash
32 | python manage.py migrate 
11 |
12 |
13 | 
14 |
15 | 
18 | 
19 | 
20 |