> For the complete documentation index, see [llms.txt](https://guide-api-rest.marmicode.fr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide-api-rest.marmicode.fr/securite-des-apis-rest/autorisation-et-gestion-des-permissions.md).

# Autorisation et Gestion des Permissions

En fonction des *credentials* du client, les autorisations et permissions d’accès sur une ressource peuvent varier.

**Une même ressource** peut donc **retourner des informations différentes en fonction du client**. Cela ne transgresse pas les principes ReST.

Par exemple, pour la même ressource *user*, un rôle *owner* et un rôle *friend* n’auront pas accès aux mêmes opérations et propriétés :

**Avec le rôle *****owner***** :** `GET /users/123`

```javascript
{
    "id": "123",
    "firstName": "John",
    "lastName": "DOE",
    "address": {
        "street": "...",
        ...
    }
}
```

**Avec le rôle *****friend***** :** `GET /users/123`

```javascript
{
    "id": "123",
    "firstName": "John",
    "lastName": "DOE"
}
```

### Les Trois Niveaux d'Autorisation

1. **Niveau ressource :** autorisation d’accès à la ressource.
2. **Niveau verbe :** méthodes autorisées sur la ressource *(create / read / update / delete)*.
3. **Niveau propriété :** gestion de l’autorisation par propriété *(read / write / mask / restricted values per role)*.\
   Ce dernier niveau est malheureusement souvent omis par la plupart des implémentations et frameworks d’API ReST.

Par exemple, la ressource *post* d’un blog peut avoir une propriété `state` pouvant prendre les valeurs suivantes : `draft`, `private` ou `published`.

Les utilisateurs avec le rôle **administrator** peuvent **modifier cette propriété**.

En revanche, les utilisateurs avec le rôle **editor** peuvent **modifier toutes les autres propriétés sauf celle-ci**.

{% hint style="success" %}
Peu importe l’implémentation, les permissions doivent être faites à base de **whitelist**.
{% endhint %}

{% hint style="success" %}
**Séparez l'implémentation fonctionnelle et la gestion des permissions.**

Pour respecter la *separation of concerns*, améliorer la *scalability* et faciliter l’implémentation et la compréhension de l’API ReST, il est recommandé d'implémenter la gestion des permissions sur un connecteur dédié.
{% endhint %}

Pour commencer, cette implémentation peut se faire dans un middleware du framework qui plus tard pourra être migré vers un service dédié ou une solution d'API management.

* Ce connecteur est similaire aux A.C.L. *(Access Control List)* que l’on retrouve dans les filesystems ou sur les firewalls.