From 752c00a242e30fd9b22ecbc3ad60b63f513d9416 Mon Sep 17 00:00:00 2001 From: Priyanshu Nayan Date: Sat, 30 Jan 2021 18:52:08 +0530 Subject: [PATCH 1/3] add content for authentication in hydrus --- docs/src/content/how-to-guides/frist.md | 119 +++++++++++++++++++++++- 1 file changed, 116 insertions(+), 3 deletions(-) diff --git a/docs/src/content/how-to-guides/frist.md b/docs/src/content/how-to-guides/frist.md index 9877ea1..3387b1a 100644 --- a/docs/src/content/how-to-guides/frist.md +++ b/docs/src/content/how-to-guides/frist.md @@ -1,9 +1,122 @@ --- -name: First How to Guide +name: How to use Authentication in Hydrus menu: How To Guides --- +# How to Use Authentication and Authorization in Hydrus + +*> You should know about `hydrus` in general. To get familiar with `hydrus` and other tools of Hydra Ecosystem checkout the Tutorials section.* + +You will be able to understand and implement authentication and authorization in `hydrus` powered APIs after following through this guide. + +`hydrus` provides an authentication procedure that allow operations on endpoints using a simple Two-Factor Authentication method. Authentication is the verification of the credentials of the connection attempt. Two factor authentication is the process where users need to provide two different authentication factors to define themselves. This is generally considered more secure than single-factor authentication where user generally provides just one factor typically a password. Authorization involves checking resources that the user is authorized to access or modify via defined roles or claims. + +## Enabling Authentication in `hydrus` + +Authentication can be enabled while setting up the API using two simple commands: + +```python +from hydrus.data.user import add_user +from hydrus.utils import set_authentication, set_token + +...ommited code + +# Add authorised users to the API. + add_user(id_=1, paraphrase="test", session=session) + with set_authentication(app, True): + # Use authentication for all requests + with set_token(app, True): + #Add token based authorization + + +#start the server +``` + +- `add_user(id_=1, paraphrase="test", session=session):` This function adds authorized user credentials in the database. +- `with set_authentication(app, True):` This function sets the authentication app context variable to use authentication for each request. Set it to `False` if authentication is not needed for the endpoints. +- `with set_token(app, True):` Once authentication is set for endpoints, this function can enable a basic token based authorization for the users. + +## Authentication system of the API + +Currently, the API uses a basic two factor authentication to authenticate the users to the API. user nonce and credentials are used during this process. Here is a step by step explanation of the authentication system : + +- The user requests the server for a protected resource. +- The server responds with a `401 response` along with a nonce-value in the `X-Authentication` header as `X-Authentication: nonce-value` and a `basic authentication` challenge. +- The client has to provide the user credentials in the `Authorization header` encoded in the basic authentication format (i.e base64) as `Authorization: Basic encoded-credentials` where the `encoded-credentials` string. This can be generated, say in REPL as: + + ```bash + from base64 import b64encode + b64encode(b"username:password").decode("ascii") + ``` + + where username is `id_` and password is `paraphrase` passed in `add_user` method. The output of the given expression will be used in request header as `Authorization: Basic MTp0ZXN0.` + +- Along with the credentials, the client has to provide the nonce value obtained from the server in the `X-Authentication` header of the previous response. The **nonce** is **valid for 1 min** and for **1 request only**. The client shall get a unique nonce everytime the server sends a 401 response. +- After successful authentication, the server responds with the user token(if enabled) or the response data. + +Here is an example of server failed authentication response: + +```bash + HTTP/1.1 401 UNAUTHORIZED + Content-type: application/ld+json + WWW-Authenticate: Basic realm="Login required" + X-Authentication: ea2ab992-ba92-45ff-89da-2a8e2adce4c1 + Link: ; rel="http://www.w3.org/ns/hydra/core#apiDocumentation" + Access-Control-Allow-Origin: * + Content-Length: 48 + Date: Wed, 07 Mar 2018 18:28:04 GMT + +{ + "401": "Need credentials to authenticate" +} +``` + +Here is the corresponding user request to successfully authenticate with the server: + +```bash + GET /serverapi/MovieCollection HTTP/1.1 + Host: localhost:8080 + User-Agent: curl/7.47.0 + Accept: */* + X-Authentication:ea2ab992-ba92-45ff-89da-2a8e2adce4c1 + Authorization: Basic MTp0ZXN0 +``` + +## Token based authorization system + +Once the client is authenticated, the API assigns a **unique time-bound token** to the client. This token can now be used by the client to access any protected endpoint within the token-expiry time which is set to **45 min**. The user can request for the token by successfully authenticating with the server, and the token alone can be used to access any resource without any further authentication. + +Here is a step by step explanation to the token-based authorisation system: + +- The server sends a `200` response with the token value in the `X-Authorization` header. +- The client can now request any resource just by adding the token in the `X-Authorization` request header. + +Here is the token generation response after client successfully authenticates in the above request: + +```bash +HTTP/1.1 200 OK + Content-type: application/ld+json + X-Authorization: f93046c97070998142cbbf8fb42886 + Link: ; rel="http://www.w3.org/ns/hydra/core#apiDocumentation" + Access-Control-Allow-Origin: * + Content-Length: 36 + Date: Wed, 07 Mar 2018 18:30:31 GMT + +{ + "200": "User token generated" +} +``` + +This is the sample format of a user request to access any protected endpoint: + +```bash + GET /serverapi/DroneCollection HTTP/1.1 + Host: localhost:8080 + User-Agent: curl/7.47.0 + Accept: */* + X-Authorization:cb6a897d9d47608fcf75c11b59f6ab +``` + +Congratulations! you just learnt how to use Authentication and Authorization in `hydrus`. -# First How to guides -This is a first tutorial From 171ff668548191e9b1ceafb116ffbbeceb230fbc Mon Sep 17 00:00:00 2001 From: Priyanshu Nayan Date: Sat, 30 Jan 2021 18:52:27 +0530 Subject: [PATCH 2/3] remove css and add content --- docs/.docz/app/db.json | 51 ++++++++++--------- docs/doczrc.js | 2 +- .../{frist.md => authentication-hydrus.md} | 26 +++++----- docs/src/styles/global.css | 4 -- 4 files changed, 40 insertions(+), 43 deletions(-) rename docs/src/content/how-to-guides/{frist.md => authentication-hydrus.md} (87%) diff --git a/docs/.docz/app/db.json b/docs/.docz/app/db.json index 26d643a..88028ff 100644 --- a/docs/.docz/app/db.json +++ b/docs/.docz/app/db.json @@ -14,7 +14,7 @@ { "name": "How To Guides", "menu": [ - "First How to Guide" + "How to use Authentication in Hydrus" ] }, { @@ -136,22 +136,37 @@ } }, { - "key": "src/content/how-to-guides/frist.md", + "key": "src/content/how-to-guides/authentication-hydrus.md", "value": { - "name": "First How to Guide", + "name": "How to use Authentication in Hydrus", "menu": "How To Guides", - "id": "070409004a82927d8120fd9a0d24ef51", - "filepath": "src/content/how-to-guides/frist.md", - "fullpath": "/Users/priyanshunayan/Developer/gsoc/docs/docs/src/content/how-to-guides/frist.md", - "link": "https://github.com/http-apis/docs/edit/master/docs/src/content/how-to-guides/frist.md", + "id": "73dd5d6694a46091dde18352eab967ba", + "filepath": "src/content/how-to-guides/authentication-hydrus.md", + "fullpath": "/Users/priyanshunayan/Developer/gsoc/docs/docs/src/content/how-to-guides/authentication-hydrus.md", + "link": "https://github.com/http-apis/docs/edit/master/docs/src/content/how-to-guides/authentication-hydrus.md", "hidden": false, - "slug": "src-content-how-to-guides-frist", - "route": "/src-content-how-to-guides-frist", + "slug": "src-content-how-to-guides-authentication-hydrus", + "route": "/src-content-how-to-guides-authentication-hydrus", "headings": [ { - "slug": "first-how-to-guides", + "slug": "how-to-use-authentication-and-authorization-in-hydrus", "depth": 1, - "value": "First How to guides" + "value": "How to Use Authentication and Authorization in Hydrus" + }, + { + "slug": "enabling-authentication-in-hydrus", + "depth": 2, + "value": "Enabling Authentication in hydrus" + }, + { + "slug": "authentication-system-of-the-api", + "depth": 2, + "value": "Authentication system of the API" + }, + { + "slug": "token-based-authorization-system", + "depth": 2, + "value": "Token based authorization system" } ] } @@ -209,17 +224,5 @@ } } ], - "props": [ - { - "key": "src/components/roadmap.js", - "value": [ - { - "description": "", - "displayName": "Roadmap", - "methods": [], - "actualName": "Roadmap" - } - ] - } - ] + "props": [] } diff --git a/docs/doczrc.js b/docs/doczrc.js index f0b27e4..f17b5ae 100644 --- a/docs/doczrc.js +++ b/docs/doczrc.js @@ -4,7 +4,7 @@ export default { "Welcome to Hydra Ecosystem Docs", "Quickstart", {name: 'Tutorial', menu:['First Tutorial']}, - {name: 'How To Guides', menu: ['First How to Guide']}, + {name: 'How To Guides', menu: ['How to use Authentication in Hydrus']}, {name: 'Conceptual Guides', menu: ['Conceptual Guide 1']}, {name: 'Modules', menu: ['Hydra in Depth']}, {name: 'FAQ', menu: ['Some Questions']}, diff --git a/docs/src/content/how-to-guides/frist.md b/docs/src/content/how-to-guides/authentication-hydrus.md similarity index 87% rename from docs/src/content/how-to-guides/frist.md rename to docs/src/content/how-to-guides/authentication-hydrus.md index 3387b1a..4ad3625 100644 --- a/docs/src/content/how-to-guides/frist.md +++ b/docs/src/content/how-to-guides/authentication-hydrus.md @@ -2,13 +2,14 @@ name: How to use Authentication in Hydrus menu: How To Guides --- + # How to Use Authentication and Authorization in Hydrus -*> You should know about `hydrus` in general. To get familiar with `hydrus` and other tools of Hydra Ecosystem checkout the Tutorials section.* +> You should know about `hydrus` in general. To get familiar with `hydrus` and other tools of Hydra Ecosystem checkout the Tutorials section.\* -You will be able to understand and implement authentication and authorization in `hydrus` powered APIs after following through this guide. +You will be able to understand and implement authentication and authorization in `hydrus` powered APIs after following through this guide. -`hydrus` provides an authentication procedure that allow operations on endpoints using a simple Two-Factor Authentication method. Authentication is the verification of the credentials of the connection attempt. Two factor authentication is the process where users need to provide two different authentication factors to define themselves. This is generally considered more secure than single-factor authentication where user generally provides just one factor typically a password. Authorization involves checking resources that the user is authorized to access or modify via defined roles or claims. +`hydrus` provides an authentication procedure that allows operations on endpoints using a simple Two-Factor Authentication method. Authentication is the verification of the credentials of the connection attempt. Two-factor authentication is the process where users need to provide two different authentication factors to define themselves. This is generally considered more secure than single-factor authentication where user generally provides just one factor typically a password. Authorization involves checking resources that the user is authorized to access or modify via defined roles or claims. ## Enabling Authentication in `hydrus` @@ -26,7 +27,7 @@ from hydrus.utils import set_authentication, set_token # Use authentication for all requests with set_token(app, True): #Add token based authorization - + #start the server ``` @@ -43,12 +44,12 @@ Currently, the API uses a basic two factor authentication to authenticate the us - The server responds with a `401 response` along with a nonce-value in the `X-Authentication` header as `X-Authentication: nonce-value` and a `basic authentication` challenge. - The client has to provide the user credentials in the `Authorization header` encoded in the basic authentication format (i.e base64) as `Authorization: Basic encoded-credentials` where the `encoded-credentials` string. This can be generated, say in REPL as: - ```bash - from base64 import b64encode - b64encode(b"username:password").decode("ascii") - ``` + ```bash + from base64 import b64encode + b64encode(b"username:password").decode("ascii") + ``` - where username is `id_` and password is `paraphrase` passed in `add_user` method. The output of the given expression will be used in request header as `Authorization: Basic MTp0ZXN0.` + where username is `id_` and password is `paraphrase` passed in `add_user` method. The output of the given expression will be used in request header as `Authorization: Basic MTp0ZXN0.` - Along with the credentials, the client has to provide the nonce value obtained from the server in the `X-Authentication` header of the previous response. The **nonce** is **valid for 1 min** and for **1 request only**. The client shall get a unique nonce everytime the server sends a 401 response. - After successful authentication, the server responds with the user token(if enabled) or the response data. @@ -64,7 +65,7 @@ Here is an example of server failed authentication response: Access-Control-Allow-Origin: * Content-Length: 48 Date: Wed, 07 Mar 2018 18:28:04 GMT - + { "401": "Need credentials to authenticate" } @@ -100,7 +101,7 @@ HTTP/1.1 200 OK Access-Control-Allow-Origin: * Content-Length: 36 Date: Wed, 07 Mar 2018 18:30:31 GMT - + { "200": "User token generated" } @@ -117,6 +118,3 @@ This is the sample format of a user request to access any protected endpoint: ``` Congratulations! you just learnt how to use Authentication and Authorization in `hydrus`. - - - diff --git a/docs/src/styles/global.css b/docs/src/styles/global.css index 691a5c9..8b13789 100644 --- a/docs/src/styles/global.css +++ b/docs/src/styles/global.css @@ -1,5 +1 @@ -@import url("https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500;700&display=swap"); -* { - font-family: "Roboto", sans-serif !important; -} From ce3776bee65d3cab0c3eb613ba5c2367f310acbb Mon Sep 17 00:00:00 2001 From: Priyanshu Nayan Date: Sat, 30 Jan 2021 18:57:31 +0530 Subject: [PATCH 3/3] Grammarly and stuffs --- docs/.docz/app/db.json | 2 +- .../how-to-guides/authentication-hydrus.md | 40 ++++++++++--------- 2 files changed, 22 insertions(+), 20 deletions(-) diff --git a/docs/.docz/app/db.json b/docs/.docz/app/db.json index 88028ff..15381a7 100644 --- a/docs/.docz/app/db.json +++ b/docs/.docz/app/db.json @@ -166,7 +166,7 @@ { "slug": "token-based-authorization-system", "depth": 2, - "value": "Token based authorization system" + "value": "Token-based authorization system" } ] } diff --git a/docs/src/content/how-to-guides/authentication-hydrus.md b/docs/src/content/how-to-guides/authentication-hydrus.md index 4ad3625..4bff178 100644 --- a/docs/src/content/how-to-guides/authentication-hydrus.md +++ b/docs/src/content/how-to-guides/authentication-hydrus.md @@ -5,11 +5,11 @@ menu: How To Guides # How to Use Authentication and Authorization in Hydrus -> You should know about `hydrus` in general. To get familiar with `hydrus` and other tools of Hydra Ecosystem checkout the Tutorials section.\* +> You should be familiar with `hydrus` in general. To get familiar with `hydrus` and other tools of Hydra Ecosystem check out the Tutorials section. -You will be able to understand and implement authentication and authorization in `hydrus` powered APIs after following through this guide. +You will be able to understand and implement authentication and authorization in `hydrus` powered APIs after following through with this guide. -`hydrus` provides an authentication procedure that allows operations on endpoints using a simple Two-Factor Authentication method. Authentication is the verification of the credentials of the connection attempt. Two-factor authentication is the process where users need to provide two different authentication factors to define themselves. This is generally considered more secure than single-factor authentication where user generally provides just one factor typically a password. Authorization involves checking resources that the user is authorized to access or modify via defined roles or claims. +`hydrus` provides an authentication procedure that allows operations on endpoints using a simple Two-Factor Authentication method. Authentication is the verification of the credentials of the connection attempt. Two-factor authentication is the process where users need to provide two different authentication factors to define themselves. This is generally considered more secure than single-factor authentication where the user generally provides just one factor typically a password. Authorization involves checking resources that the user is authorized to access or modify via defined roles or claims. ## Enabling Authentication in `hydrus` @@ -19,9 +19,9 @@ Authentication can be enabled while setting up the API using two simple commands from hydrus.data.user import add_user from hydrus.utils import set_authentication, set_token -...ommited code +...omitted code -# Add authorised users to the API. +# Add authorized users to the API. add_user(id_=1, paraphrase="test", session=session) with set_authentication(app, True): # Use authentication for all requests @@ -32,26 +32,26 @@ from hydrus.utils import set_authentication, set_token #start the server ``` -- `add_user(id_=1, paraphrase="test", session=session):` This function adds authorized user credentials in the database. -- `with set_authentication(app, True):` This function sets the authentication app context variable to use authentication for each request. Set it to `False` if authentication is not needed for the endpoints. -- `with set_token(app, True):` Once authentication is set for endpoints, this function can enable a basic token based authorization for the users. +- `add_user(id_=1, paraphrase="test", session=session):` This function adds authorized user credentials in the database. +- `with set_authentication(app, True):` This function sets the authentication app context variable to use authentication for each request. Set it to `False` if authentication is not needed for the endpoints. +- `with set_token(app, True):` Once authentication is set for endpoints, this function can enable a basic token-based authorization for the users. ## Authentication system of the API -Currently, the API uses a basic two factor authentication to authenticate the users to the API. user nonce and credentials are used during this process. Here is a step by step explanation of the authentication system : +Currently, the API uses basic two-factor authentication to authenticate the users to the API. user nonce and credentials are used during this process. Here is a step by step explanation of the authentication system : - The user requests the server for a protected resource. -- The server responds with a `401 response` along with a nonce-value in the `X-Authentication` header as `X-Authentication: nonce-value` and a `basic authentication` challenge. -- The client has to provide the user credentials in the `Authorization header` encoded in the basic authentication format (i.e base64) as `Authorization: Basic encoded-credentials` where the `encoded-credentials` string. This can be generated, say in REPL as: +- The server responds with a `401 response` along with a nonce-value in the `X-Authentication` header as `X-Authentication: nonce-value` and a `basic authentication` challenge. +- The client has to provide the user credentials in the `Authorization header` encoded in the basic authentication format (i.e base64) as `Authorization: Basic encoded-credentials` where the `encoded-credentials` string. This can be generated, say in REPL as: ```bash from base64 import b64encode b64encode(b"username:password").decode("ascii") ``` - where username is `id_` and password is `paraphrase` passed in `add_user` method. The output of the given expression will be used in request header as `Authorization: Basic MTp0ZXN0.` + where username is `id_` and password is `paraphrase` passed in `add_user` method. The output of the given expression will be used in the request header as `Authorization: Basic MTp0ZXN0.` -- Along with the credentials, the client has to provide the nonce value obtained from the server in the `X-Authentication` header of the previous response. The **nonce** is **valid for 1 min** and for **1 request only**. The client shall get a unique nonce everytime the server sends a 401 response. +- Along with the credentials, the client has to provide the nonce value obtained from the server in the `X-Authentication` header of the previous response. The **nonce** is **valid for 1 min** and for **1 request only**. The client shall get a unique nonce every time the server sends a 401 response. - After successful authentication, the server responds with the user token(if enabled) or the response data. Here is an example of server failed authentication response: @@ -82,14 +82,14 @@ Here is the corresponding user request to successfully authenticate with the ser Authorization: Basic MTp0ZXN0 ``` -## Token based authorization system +## Token-based authorization system -Once the client is authenticated, the API assigns a **unique time-bound token** to the client. This token can now be used by the client to access any protected endpoint within the token-expiry time which is set to **45 min**. The user can request for the token by successfully authenticating with the server, and the token alone can be used to access any resource without any further authentication. +Once the client is authenticated, the API assigns a **unique time-bound token** to the client. This token can now be used by the client to access any protected endpoint within the token-expiry time which is set to **45 min**. The user can request the token by successfully authenticating with the server, and the token alone can be used to access any resource without any further authentication. -Here is a step by step explanation to the token-based authorisation system: +Here is a step by step explanation of the token-based authorization system: -- The server sends a `200` response with the token value in the `X-Authorization` header. -- The client can now request any resource just by adding the token in the `X-Authorization` request header. +- The server sends a `200` response with the token value in the `X-Authorization` header. +- The client can now request any resource just by adding the token in the `X-Authorization` request header. Here is the token generation response after client successfully authenticates in the above request: @@ -117,4 +117,6 @@ This is the sample format of a user request to access any protected endpoint: X-Authorization:cb6a897d9d47608fcf75c11b59f6ab ``` -Congratulations! you just learnt how to use Authentication and Authorization in `hydrus`. +Congratulations! you just learned how to use Authentication and Authorization in `hydrus`. + +