diff --git a/.gitignore b/.gitignore index db3b38a..30873bb 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ recipes/.vuepress/dist node_modules/ yarn-error.log +.DS_Store diff --git a/recipes/images/scopes-roles-accreditations/scope_delegation.png b/recipes/images/scopes-roles-accreditations/scope_delegation.png new file mode 100644 index 0000000..f7d7370 Binary files /dev/null and b/recipes/images/scopes-roles-accreditations/scope_delegation.png differ diff --git a/recipes/images/scopes-roles-accreditations/scope_global_schema.png b/recipes/images/scopes-roles-accreditations/scope_global_schema.png new file mode 100644 index 0000000..686104c Binary files /dev/null and b/recipes/images/scopes-roles-accreditations/scope_global_schema.png differ diff --git a/recipes/images/scopes-roles-accreditations/scope_without_end_user.png b/recipes/images/scopes-roles-accreditations/scope_without_end_user.png new file mode 100644 index 0000000..9954d1e Binary files /dev/null and b/recipes/images/scopes-roles-accreditations/scope_without_end_user.png differ diff --git a/recipes/images/scopes-roles-accreditations/use_case.png b/recipes/images/scopes-roles-accreditations/use_case.png new file mode 100644 index 0000000..94e32b4 Binary files /dev/null and b/recipes/images/scopes-roles-accreditations/use_case.png differ diff --git a/recipes/scopes-roles-accreditations.md b/recipes/scopes-roles-accreditations.md new file mode 100644 index 0000000..c003cf4 --- /dev/null +++ b/recipes/scopes-roles-accreditations.md @@ -0,0 +1,108 @@ +--- +description: How should I use the scopes in my application and what are their conventions +complexity: 1 +--- + +# A little bit of context : Scopes, roles and accreditations + +## Use-case + +![use-case-schema](images/scopes-roles-accreditations/use_case.png) + +I own a token to connect to the API, how should o name them and what they should control ? + +In this use case, the user (resource owner) uses an web application (client) which consumes a protected API (resource server). +The OpenId/OAuth provider is out of scope. + +Example authentication token : + +```json +{ + "active": true, + "client_id": "l238j323ds-23ij4", + "username": "jdoe", + "scope": "read:cart write:cart", + "sub": "Z5O3upPC88QrAjx00dis", + "aud": "https://protected.example.net/resource", + "iss": "https://server.example.com/", + "exp": 1419356238, + "iat": 1419350238, + "extension_field": "twenty-seven" +} +``` + +## Definitions + +### Scope + +![scope-schema](images/scopes-roles-accreditations/scope_global_schema.png) + +Scopes are permissions that have been granted to the client + +It’s a list of words which describe a subset of privileges of the resource owner. +The actual privileges of a client are the intersection of the scope and the privileges of the resource owner. + +### Roles + +A role is a group or type of users who shares the same objectives when using an application. +Example : In a market place like application, we can imagine 3 roles : *sellers*, *vendors*, *administrators*. + +### Accreditations + +Accreditations are fine grained user access management. This check is done within the application to grant or not the access to a specific resource (the resource access can be done on id, or by any other information). This is often refered as ACL. +Example : If we take again the market place application, we can imagine a seller being able to modify only his goods and not the ones from other sellers or imagine having multiple user profiles, such as *developper* et or *maintainer* on a github repo. + +## Scopes in detail + +### Scopes without end user + +This scenarri describes the privileges of a client communicating with a resource server (back-to-back communication). + +![scope_without-end-user-schema](images/scopes-roles-accreditations/scope_without_end_user.png) + +- Scopes are permissions owned by the client +- The privileges of a client is the scope granted by the resource server during enrollment + +### Scopes with access delegation + +In this scenario, the user wants to grant access to a client only to a subset of his privileges. + +![scope_without-end-user-schema](images/scopes-roles-accreditations/scope_delegation.png) + +- Scopes are permissions that have been granted to the client +- It’s a list of words which describe a subset of privileges of the resource owner +- The actual privileges of a client are the intersection of the scope and the privileges of the resource owner + +### Naming recommendation + +Explicit naming should uniquely identify the resources accessible (or the API endmoints accessible). + +Our recommendation is to use the format : +read: +write: + +Scopes int the token should be separated by a space. + +Example of a JWT issued to a client with *read only* acces to the cart +```json +{ + [...] + "client_id": "l238j323ds-23ij4", + "username": "jdoe", + "scope": "read:cart", + "sub": "Z5O3upPC88QrAjx00dis", + [...] +} +``` + +Example of a JWT issued to a client with *read* and *write* acces to the cart +```json +{ + [...] + "client_id": "azdzbahjbhbj1234", + "username": "jdoe", + "scope": "read:cart write:cart", + "sub": "Z5O3upPC88QrAjx00dis", + [...] +} +```