diff --git a/docs/.docz/app/db.json b/docs/.docz/app/db.json index 26d643a..15381a7 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/authentication-hydrus.md b/docs/src/content/how-to-guides/authentication-hydrus.md new file mode 100644 index 0000000..4bff178 --- /dev/null +++ b/docs/src/content/how-to-guides/authentication-hydrus.md @@ -0,0 +1,122 @@ +--- +name: How to use Authentication in Hydrus +menu: How To Guides +--- + +# How to Use Authentication and Authorization in Hydrus + +> 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 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 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` + +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 + +...omitted code + +# Add authorized 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 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 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 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: + +```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 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 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. + +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 learned how to use Authentication and Authorization in `hydrus`. + + diff --git a/docs/src/content/how-to-guides/frist.md b/docs/src/content/how-to-guides/frist.md deleted file mode 100644 index 9877ea1..0000000 --- a/docs/src/content/how-to-guides/frist.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -name: First How to Guide -menu: How To Guides ---- - -# First How to guides - -This is a first tutorial - 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; -}