http-apis.github.io

HydraEcoSystem: Main documentation entrypoint for HYDRA-based applications

View on GitHub

Token Authentication

hydrus provides an Authorization/Authentication procedure that can be put in place for allowing operations on endpoints based on a simple Two-Factor Authentication method.

This page explains the authentication options you can apply to your API deployed with hydrus.

How to enable authentication?

Authentication can be enabled using two simple commands in the following manner while setting up your API:

    # 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

Authentication system of the API

Currently the API uses a basic two factor authentication to authenticate the users to the API using user nonce and credentials. Here is a step by step detailed explanation of the authentication system :

Here is an example of server failed authentication response:

 HTTP/1.1 401 UNAUTHORIZED
 Content-type: application/ld+json
 WWW-Authenticate: Basic realm="Login required"
 X-Authentication: ea2ab992-ba92-45ff-89da-2a8e2adce4c1
 Link: <http://localhost:8080/serverapi/vocab>; 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"
}

And here is the corresponding user request to succesfully authenticate with the server:

 GET /serverapi/DroneCollection 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:

Here is the token generation response after client succesfully authenticates in the above request:

 HTTP/1.1 200 OK
 Content-type: application/ld+json
 X-Authorization: f93046c97070998142cbbf8fb42886
 Link: <http://localhost:8080/serverapi/vocab>; 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"
}

And this the sample format of a user request to access any protected endpoint:

 GET /serverapi/DroneCollection HTTP/1.1
 Host: localhost:8080
 User-Agent: curl/7.47.0
 Accept: */*
 X-Authorization:cb6a897d9d47608fcf75c11b59f6ab