From 221c855ccb6c59c234c4c73fae129bd511b0dab4 Mon Sep 17 00:00:00 2001 From: Felipe Ripoll Date: Fri, 10 Aug 2018 15:58:29 -0600 Subject: [PATCH] [#47] updating REST documentation --- doc/.build | 7 +- doc/404.html | 8 +- doc/POABackend.Auth.Guardian.Plug.html | 512 ++++++++++++++ doc/POABackend.Auth.Models.Token.html | 241 +++++++ doc/POABackend.Auth.Models.User.html | 245 +++++++ doc/POABackend.Auth.REST.html | 432 ++++++++++++ doc/POABackend.Auth.html | 816 +++++++++++++++++++++++ doc/POABackend.CustomHandler.REST.html | 130 +++- doc/POABackend.CustomHandler.html | 8 +- doc/POABackend.Protocol.DataType.html | 8 +- doc/POABackend.Protocol.Message.html | 8 +- doc/POABackend.Protocol.MessageType.html | 8 +- doc/POABackend.Protocol.html | 86 ++- doc/POABackend.Receiver.html | 8 +- doc/POABackend.Receivers.Dashboard.html | 18 +- doc/POABackend.Receivers.DynamoDB.html | 8 +- doc/POABackend.html | 50 +- doc/api-reference.html | 51 +- doc/dist/sidebar_items-3739fd4c82.js | 1 + doc/dist/sidebar_items-ffeb4f1e51.js | 1 - doc/index.html | 4 +- doc/initial_architecture.html | 8 +- doc/search.html | 8 +- lib/poa_backend.ex | 43 +- lib/poa_backend/auth/models/token.ex | 2 +- lib/poa_backend/auth/rest.ex | 180 +++++ lib/poa_backend/custom_handler/rest.ex | 81 ++- lib/poa_backend/protocol.ex | 29 +- mix.exs | 8 + test/auth/api_test.exs | 4 +- 30 files changed, 2856 insertions(+), 157 deletions(-) create mode 100644 doc/POABackend.Auth.Guardian.Plug.html create mode 100644 doc/POABackend.Auth.Models.Token.html create mode 100644 doc/POABackend.Auth.Models.User.html create mode 100644 doc/POABackend.Auth.REST.html create mode 100644 doc/POABackend.Auth.html create mode 100644 doc/dist/sidebar_items-3739fd4c82.js delete mode 100644 doc/dist/sidebar_items-ffeb4f1e51.js create mode 100644 lib/poa_backend/auth/rest.ex diff --git a/doc/.build b/doc/.build index c47573c..20cb5e2 100644 --- a/doc/.build +++ b/doc/.build @@ -4,12 +4,17 @@ fonts/icomoon.eot fonts/icomoon.svg fonts/icomoon.ttf fonts/icomoon.woff -dist/sidebar_items-ffeb4f1e51.js +dist/sidebar_items-3739fd4c82.js api-reference.html initial_architecture.html search.html 404.html POABackend.html +POABackend.Auth.html +POABackend.Auth.Guardian.Plug.html +POABackend.Auth.Models.Token.html +POABackend.Auth.Models.User.html +POABackend.Auth.REST.html POABackend.Protocol.html POABackend.Protocol.DataType.html POABackend.Protocol.Message.html diff --git a/doc/404.html b/doc/404.html index c8ebf9b..48ca53c 100644 --- a/doc/404.html +++ b/doc/404.html @@ -4,11 +4,11 @@ - + 404 – poa_backend v0.1.0 - + @@ -29,7 +29,7 @@
- +

poa_backend @@ -79,7 +79,7 @@ you were looking for.

Built using - ExDoc (v0.18.3), + ExDoc (v0.18.4), designed by diff --git a/doc/POABackend.Auth.Guardian.Plug.html b/doc/POABackend.Auth.Guardian.Plug.html new file mode 100644 index 0000000..fdbacb4 --- /dev/null +++ b/doc/POABackend.Auth.Guardian.Plug.html @@ -0,0 +1,512 @@ + + + + + + + + POABackend.Auth.Guardian.Plug – poa_backend v0.1.0 + + + + + + + + + + + +

+ + +
+ + + +
+

+ poa_backend +

+

+ v0.1.0 +

+
+ + + +
+ + +
+ + +
+ +
+ +
+
+
+ + +

+ poa_backend v0.1.0 + POABackend.Auth.Guardian.Plug + + + + View Source + + +

+ + + + +
+

+ + + Link to this section + + Summary +

+ + + +
+

+ Functions +

+
+
+ authenticated?(conn, opts \\ []) +
+ +
+
+
+ current_claims(conn, opts \\ []) +
+ +
+
+
+ current_resource(conn, opts \\ []) +
+ +
+
+
+ current_token(conn, opts \\ []) +
+ +
+
+
+ implementation() +
+ +
+
+
+ put_current_claims(conn, claims, opts \\ []) +
+ +
+
+
+ put_current_resource(conn, resource, opts \\ []) +
+ +
+
+
+ put_current_token(conn, token, opts \\ []) +
+ +
+
+
+ remember_me(conn, resource, claims \\ %{}, opts \\ []) +
+ +
+
+
+ remember_me_from_token(conn, token, claims \\ %{}, opts \\ []) +
+ +
+
+
+ sign_in(conn, resource, claims \\ %{}, opts \\ []) +
+ +
+
+
+ sign_out(conn, opts \\ []) +
+ +
+ +
+ + + + +
+ + + + + +
+

+ + + Link to this section + + Functions +

+
+ + + + +
+ + + Link to this function + + authenticated?(conn, opts \\ []) + + + + View Source + + + + +
+
+ +
+
+
+ + + + +
+ + + Link to this function + + current_claims(conn, opts \\ []) + + + + View Source + + + + +
+
+ +
+
+
+ + + + +
+ + + Link to this function + + current_resource(conn, opts \\ []) + + + + View Source + + + + +
+
+ +
+
+
+ + + + +
+ + + Link to this function + + current_token(conn, opts \\ []) + + + + View Source + + + + +
+
+ +
+
+
+ + +
+ + + Link to this function + + implementation() + + + + View Source + + + + +
+
+ +
+
+
+ + + + +
+ + + Link to this function + + put_current_claims(conn, claims, opts \\ []) + + + + View Source + + + + +
+
+ +
+
+
+ + + + +
+ + + Link to this function + + put_current_resource(conn, resource, opts \\ []) + + + + View Source + + + + +
+
+ +
+
+
+ + + + +
+ + + Link to this function + + put_current_token(conn, token, opts \\ []) + + + + View Source + + + + +
+
+ +
+
+
+ + + + + + +
+ + + Link to this function + + remember_me(conn, resource, claims \\ %{}, opts \\ []) + + + + View Source + + + + +
+
+ +
+
+
+ + + + + + +
+ + + Link to this function + + remember_me_from_token(conn, token, claims \\ %{}, opts \\ []) + + + + View Source + + + + +
+
+ +
+
+
+ + + + + + +
+ + + Link to this function + + sign_in(conn, resource, claims \\ %{}, opts \\ []) + + + + View Source + + + + +
+
+ +
+
+
+ + + + +
+ + + Link to this function + + sign_out(conn, opts \\ []) + + + + View Source + + + + +
+
+ +
+
+ +
+ + + + +
+
+
+
+ + + + + + + + diff --git a/doc/POABackend.Auth.Models.Token.html b/doc/POABackend.Auth.Models.Token.html new file mode 100644 index 0000000..7a8e395 --- /dev/null +++ b/doc/POABackend.Auth.Models.Token.html @@ -0,0 +1,241 @@ + + + + + + + + POABackend.Auth.Models.Token – poa_backend v0.1.0 + + + + + + + + + + + +
+ + +
+ + + +
+

+ poa_backend +

+

+ v0.1.0 +

+
+ + + +
+ + +
+ + +
+ +
+ +
+
+
+ + +

+ poa_backend v0.1.0 + POABackend.Auth.Models.Token + + + + View Source + + +

+ + +
+

This module encapsulates the Token model. This is used in order to store banned tokens in Database

+ +
+ + + +
+

+ + + Link to this section + + Summary +

+ +
+

+ Types +

+
+
+ t() +
+ +
+ +
+ + + +
+

+ Functions +

+
+
+ new(token, expires) +
+ +
+ +
+ + + + +
+ + + +
+

+ + + Link to this section + + Types +

+
+
+ + +
+ + + Link to this type + + t() + + + + View Source + + + + +
+ + 
t() :: %POABackend.Auth.Models.Token{
+  __meta__: term(),
+  expires: Integer.t(),
+  inserted_at: term(),
+  token: String.t(),
+  updated_at: term()
+}
+ +
+ +
+
+ +
+
+ +
+
+ + + +
+

+ + + Link to this section + + Functions +

+
+ + +
+ + + Link to this function + + new(token, expires) + + + + View Source + + + + +
+
+ +
+
+ +
+ + + + +
+
+
+
+ + + + + + + + diff --git a/doc/POABackend.Auth.Models.User.html b/doc/POABackend.Auth.Models.User.html new file mode 100644 index 0000000..3afa4ef --- /dev/null +++ b/doc/POABackend.Auth.Models.User.html @@ -0,0 +1,245 @@ + + + + + + + + POABackend.Auth.Models.User – poa_backend v0.1.0 + + + + + + + + + + + +
+ + +
+ + + +
+

+ poa_backend +

+

+ v0.1.0 +

+
+ + + +
+ + +
+ + +
+ +
+ +
+
+
+ + +

+ poa_backend v0.1.0 + POABackend.Auth.Models.User + + + + View Source + + +

+ + +
+

This module encapsulates the User model

+ +
+ + + +
+

+ + + Link to this section + + Summary +

+ +
+

+ Types +

+
+
+ t() +
+ +
+ +
+ + + +
+

+ Functions +

+
+
+ changeset(user, params \\ %{}) +
+ +
+ +
+ + + + +
+ + + +
+

+ + + Link to this section + + Types +

+
+
+ + +
+ + + Link to this type + + t() + + + + View Source + + + + +
+ + 
t() :: %POABackend.Auth.Models.User{
+  __meta__: term(),
+  active: :boolean,
+  inserted_at: term(),
+  password: String.t(),
+  password_hash: String.t(),
+  updated_at: term(),
+  user: String.t()
+}
+ +
+ +
+
+ +
+
+ +
+
+ + + +
+

+ + + Link to this section + + Functions +

+
+ + + + +
+ + + Link to this function + + changeset(user, params \\ %{}) + + + + View Source + + + + +
+
+ +
+
+ +
+ + + + +
+
+
+
+ + + + + + + + diff --git a/doc/POABackend.Auth.REST.html b/doc/POABackend.Auth.REST.html new file mode 100644 index 0000000..56f8ebf --- /dev/null +++ b/doc/POABackend.Auth.REST.html @@ -0,0 +1,432 @@ + + + + + + + + POABackend.Auth.REST – poa_backend v0.1.0 + + + + + + + + + + + +
+ + +
+ + + +
+

+ poa_backend +

+

+ v0.1.0 +

+
+ + + +
+ + +
+ + +
+ +
+ +
+
+
+ + +

+ poa_backend v0.1.0 + POABackend.Auth.REST + + + + View Source + + +

+ + +
+

Here we define the REST Endpoints for Authentication/Authorization features in poa_backend. +There are two types of users who will use this Endpoints.

+
    +
  • One is the standard user which is associated to one Agent. This user will call only the /session endpoint in order to retrieve a JWT token +needed for using the POA Protocol Endpoints. Those users are stored in a Database. +
    • +
  • The other kind of users are the POA administrators. This users can create normal users using the /user Endpoint, banning tokens, banning users… +Those Admins are defined in the Config (ie prod.exs) file and are loaded when the app starts. This is an example of how the Admins are defined +
    • +
+
      config :poa_backend,
+       :admins,
+       [
+         {"admin1", "password12345678"},
+         {"admin2", "password87654321"}
+       ]
+

Those Endpoints must run under https schema

+

+ + Session Endpoint +

+ +

This endpoint will be responsible of returning valid JWT tokens to the Agents if they use a valid user/password for authentication. The form of the endpoint is:

+

POST /session

+ ++++ + + + + + + + + + + + +
HTTP headerValues
content-typeapplication/json or application/msgpack
authorizationBasic encodeBase64(username + “:” + password)
+ ++++ + + + + + + + + + + + +
PayloadValue
JSON{“agent-id”:”theAgentID”}
MessagePackSame as JSON but packed with MessagePack
+

Response:

+ ++++ + + + + + + + + + + + + + + +
CODEDescription
200Success: {“token”:”NewToken”}
401Authentication failed
415Unsupported Media Type (only application/json and application/msgpack allowed)
+

Example:

+
curl -i -X POST -H "Authorization: Basic Ump1YURzdi06WHY3X0xvQ0FVZVduYmN5" -H "Content-Type: application/json" https://localhost:4003/session --insecure
+
+HTTP/1.1 200 OK
+server: Cowboy
+date: Fri, 10 Aug 2018 20:25:05 GMT
+content-length: 362
+cache-control: max-age=0, private, must-revalidate
+
+{"token":"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJwb2FfYmFja2VuZCIsImV4cCI6MTUzMzkzNjMwNiwiaWF0IjoxNTMzOTMyNzA2LCJpc3MiOiJwb2FfYmFja2VuZCIsImp0aSI6ImI0MzBkNTMwLWExZDYtNDk1Yy1hMjYyLThjNTcxMmM1OTM4YSIsIm5iZiI6MTUzMzkzMjcwNSwic3ViIjoiUmp1YURzdi0iLCJ0eXAiOiJhY2Nlc3MifQ.E3gqpCxY5wAAhZwcr7vZVLcC7X-bSHcXfX6NgeJc-LMbpcDgJvZgcgYQ-VTIkulb2mWw_Fjc7sXVwYMeIIliMg"}
+

+ + User Endpoint +

+ +

This Endpoint is needed in order to add a new user. Only Admin people can do that.

+

POST /user

+ ++++ + + + + + + + + + + + +
HTTP headerValues
content-typeapplication/json or application/msgpack
authorizationBasic encodeBase64(adminname + “:” + password)
+ ++++ + + + + + + + + + + + +
PayloadValue
JSON{“agent-id”: “AgentId”, user-name”:”userName”, “password”: “mypassword”}
MessagePackSame as JSON but packed with MessagePack
+

NOTE user-name and password field are optional. If we send only the user-name the server will create a random password. If we don’t send any value the the server +will create both, user-name and password

+

Response

+ ++++ + + + + + + + + + + + + + + + + + +
CODEDescription
200Success: {“user”:”Username”, “password”:”mypassword”}
401Authentication failed
409The user already exists
415Unsupported Media Type (only application/json and application/msgpack allowed)
+

Example:

+
curl -i -X POST -H "Authorization: Basic YWRtaW4xOnBhc3N3b3JkMTIzNDU2Nzg=" -H "Content-Type: application/json" https://localhost:4003/user --insecure
+
+HTTP/1.1 200 OK
+server: Cowboy
+date: Fri, 10 Aug 2018 20:40:04 GMT
+content-length: 53
+cache-control: max-age=0, private, must-revalidate
+
+{"user-name":"vhuevkMy","password":"XkBCEJmuuEzPvy8"}
+

+ + Blacklist Token Endpoint +

+ +

This Endpoint is used when we want to ban a single JWT Token (not the entire user) and that will convert that Token invalid. This Endpoint is only called by Admins.

+

In order to achive that we have to track the tokens in a Mnesia table. We also have to create a process which cleans the DB every day

+

POST /blacklist/token

+ ++++ + + + + + + + + + + + +
HTTP headerValues
content-typeapplication/json or application/msgpack
authorizationBasic encodeBase64(adminname + “:” + password)
+ ++++ + + + + + + + + + + + +
PayloadValue
JSON{“token”:”myJWTToken”}
MessagePackSame as JSON but packed with MessagePack
+

Response

+ ++++ + + + + + + + + + + + + + + + + + +
CODEDescription
200Success
401Authentication failed
404The Token is not valid
415Unsupported Media Type (only application/json and application/msgpack allowed)
+

Example:

+
curl -i -d '{"token":"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJwb2FfYmFja2VuZCIsImV4cCI6MTUzMzkzNjMwNiwiaWF0IjoxNTMzOTMyNzA2LCJpc3MiOiJwb2FfYmFja2VuZCIsImp0aSI6ImI0MzBkNTMwLWExZDYtNDk1Yy1hMjYyLThjNTcxMmM1OTM4YSIsIm5iZiI6MTUzMzkzMjcwNSwic3ViIjoiUmp1YURzdi0iLCJ0eXAiOiJhY2Nlc3MifQ.E3gqpCxY5wAAhZwcr7vZVLcC7X-bSHcXfX6NgeJc-LMbpcDgJvZgcgYQ-VTIkulb2mWw_Fjc7sXVwYMeIIliMg"}' -X POST -H "Authorization: Basic YWRtaW4xOnBhc3N3b3JkMTIzNDU2Nzg=" -H "Content-Type: application/json" https://localhost:4003/blacklist/token --insecure
+
+HTTP/1.1 200 OK
+server: Cowboy
+date: Fri, 10 Aug 2018 20:59:25 GMT
+content-length: 0
+cache-control: max-age=0, private, must-revalidate
+

+ + Blacklist User Endpoint +

+ +

This Endpoint bans a User, that will invalidate its tokens. This Endpoint is only called by Admins.

+

In order to achive that we have to track the tokens in a Mnesia table. We also have to create a process which cleans the DB every day

+

POST /blacklist/user

+ ++++ + + + + + + + + + + + +
HTTP headerValues
content-typeapplication/json or application/msgpack
authorizationBasic encodeBase64(adminname + “:” + password)
+ ++++ + + + + + + + + + + + +
PayloadValue
JSON{“user”:”theUserName”}
MessagePackSame as JSON but packed with MessagePack
+

Response

+ ++++ + + + + + + + + + + + + + + + + + +
CODEDescription
200Success
401Authentication failed
404The user doesn’t exist
415Unsupported Media Type (only application/json and application/msgpack allowed)
+

Example:

+
curl -i -d '{"user":"vhuevkMy"}' -X POST -H "Authorization: Basic YWRtaW4xOnBhc3N3b3JkMTIzNDU2Nzg=" -H "Content-Type: application/json" https://localhost:4003/blacklist/user --insecure
+
+HTTP/1.1 200 OK
+server: Cowboy
+date: Fri, 10 Aug 2018 21:55:03 GMT
+content-length: 0
+cache-control: max-age=0, private, must-revalidate
+ +
+ + + + + + + + + + +
+
+
+
+ + + + + + + + diff --git a/doc/POABackend.Auth.html b/doc/POABackend.Auth.html new file mode 100644 index 0000000..656f55b --- /dev/null +++ b/doc/POABackend.Auth.html @@ -0,0 +1,816 @@ + + + + + + + + POABackend.Auth – poa_backend v0.1.0 + + + + + + + + + + + +
+ + +
+ + + +
+

+ poa_backend +

+

+ v0.1.0 +

+
+ + + +
+ + +
+ + +
+ +
+ +
+
+
+ + +

+ poa_backend v0.1.0 + POABackend.Auth + + + + View Source + + +

+ + +
+

This module defines the API for the Authorisation

+ +
+ + + +
+

+ + + Link to this section + + Summary +

+ + + +
+

+ Functions +

+
+
+ activate_user(user) +
+ +

This function Activates a user, storing active: true in the database for the given user

+
+ +
+
+
+ authenticate_admin(admin_name, password) +
+ +

Authenticates an Admin

+
+ +
+
+
+ authenticate_user(user_name, password) +
+ +

This function authenticates a user/password pair

+
+ +
+
+
+ create_banned_token(jwt_token) +
+ +

Creates a token entry in the banned tokens table. It receives a jwt token in String format. +This function will extract the expiration time from the claims and store them in the Database

+
+ +
+
+
+ create_banned_token(token, expires) +
+ +

Creates a token entry in the banned tokens table. It receives the token in String format and the +expiration time as Integer

+
+ +
+
+
+ create_user(user_name, password, active \\ true) +
+ +

Registers a user in the system

+
+ +
+
+
+ deactivate_user(user) +
+ +

This function Deactivates a user, storing active: false in the database for the given user

+
+ +
+
+
+ generate_password() +
+ +

Generates a password randomply

+
+ +
+
+
+ generate_user_name() +
+ +

Generates a valid user name randomply

+
+ +
+
+
+ generate_user_name(user_name) +
+ +

This function is exported for testing purposes

+
+ +
+
+
+ get_user(user) +
+ +

Get a user from the database based in the user name

+
+ +
+
+
+ purge_banned_tokens() +
+ +

This function deletes the banned tokens which already expired

+
+ +
+
+
+ remove_user(user) +
+ +

Deletes a user from the database based in the given user

+
+ +
+
+
+ token_banned?(token) +
+ +

Checks if a token is banned or not

+
+ +
+
+
+ user_active?(user) +
+ +

Checks if a user is active

+
+ +
+
+
+ valid_token?(jwt_token) +
+ +

Validates if a JWT token is valid

+
+ +
+
+
+ valid_user_name?(user_name) +
+ +

Validates if a given user name is valid or not. It is valid if doesn’t exist a user +with that name in the database already

+
+ +
+ +
+ + + + +
+ + + + + +
+

+ + + Link to this section + + Functions +

+
+ + +
+ + + Link to this function + + activate_user(user) + + + + View Source + + + + +
+ + 
activate_user(POABackend.Auth.Models.User.t()) ::
+  {:ok, POABackend.Auth.Models.User.t()} | {:error, Ecto.Changeset.t()}
+ +
+ +
+
+

This function Activates a user, storing active: true in the database for the given user

+ +
+
+
+ + +
+ + + Link to this function + + authenticate_admin(admin_name, password) + + + + View Source + + + + +
+ + 
authenticate_admin(String.t(), String.t()) ::
+  {:ok, :valid} | {:error, :notvalid}
+ +
+ +
+
+

Authenticates an Admin

+ +
+
+
+ + +
+ + + Link to this function + + authenticate_user(user_name, password) + + + + View Source + + + + +
+ + 
authenticate_user(String.t(), String.t()) ::
+  {:ok, POABackend.Auth.Models.User.t()} | {:error, :notvalid}
+ +
+ +
+
+

This function authenticates a user/password pair

+ +
+
+
+ + +
+ + + Link to this function + + create_banned_token(jwt_token) + + + + View Source + + + + +
+ + 
create_banned_token(String.t()) ::
+  {:ok, POABackend.Auth.Models.Token.t()} | {:error, any()}
+ +
+ +
+
+

Creates a token entry in the banned tokens table. It receives a jwt token in String format. +This function will extract the expiration time from the claims and store them in the Database.

+ +
+
+
+ + +
+ + + Link to this function + + create_banned_token(token, expires) + + + + View Source + + + + +
+ + 
create_banned_token(String.t(), integer()) ::
+  {:ok, POABackend.Auth.Models.Token.t()} | {:error, :already_exists}
+ +
+ +
+
+

Creates a token entry in the banned tokens table. It receives the token in String format and the +expiration time as Integer.

+ +
+
+
+ + + + +
+ + + Link to this function + + create_user(user_name, password, active \\ true) + + + + View Source + + + + +
+ + 
create_user(String.t(), String.t(), Boolean.t()) ::
+  {:ok, POABackend.Auth.Models.User.t()}
+  | {:error, :already_exists}
+  | {:error, Ecto.Changeset.t()}
+ +
+ +
+
+

Registers a user in the system.

+ +
+
+
+ + +
+ + + Link to this function + + deactivate_user(user) + + + + View Source + + + + +
+ + 
deactivate_user(POABackend.Auth.Models.User.t()) ::
+  {:ok, POABackend.Auth.Models.User.t()} | {:error, Ecto.Changeset.t()}
+ +
+ +
+
+

This function Deactivates a user, storing active: false in the database for the given user

+ +
+
+
+ + +
+ + + Link to this function + + generate_password() + + + + View Source + + + + +
+ + 
generate_password() :: String.t()
+ +
+ +
+
+

Generates a password randomply

+ +
+
+
+ + +
+ + + Link to this function + + generate_user_name() + + + + View Source + + + + +
+ + 
generate_user_name() :: String.t()
+ +
+ +
+
+

Generates a valid user name randomply

+ +
+
+
+ + +
+ + + Link to this function + + generate_user_name(user_name) + + + + View Source + + + + +
+ + 
generate_user_name(String.t()) :: String.t()
+ +
+ +
+
+

This function is exported for testing purposes

+ +
+
+
+ + +
+ + + Link to this function + + get_user(user) + + + + View Source + + + + +
+ + 
get_user(String.t()) :: POABackend.Auth.Models.User.t() | nil
+ +
+ +
+
+

Get a user from the database based in the user name

+ +
+
+
+ + +
+ + + Link to this function + + purge_banned_tokens() + + + + View Source + + + + +
+ + 
purge_banned_tokens() :: :ok
+ +
+ +
+
+

This function deletes the banned tokens which already expired

+ +
+
+
+ + +
+ + + Link to this function + + remove_user(user) + + + + View Source + + + + +
+ + 
remove_user(POABackend.Auth.Models.User.t()) :: :ok
+ +
+ +
+
+

Deletes a user from the database based in the given user

+ +
+
+
+ + +
+ + + Link to this function + + token_banned?(token) + + + + View Source + + + + +
+ + 
token_banned?(String.t()) :: Boolean.t()
+ +
+ +
+
+

Checks if a token is banned or not

+ +
+
+
+ + +
+ + + Link to this function + + user_active?(user) + + + + View Source + + + + +
+ + 
user_active?(POABackend.Auth.Models.User.t()) :: Boolean.t()
+ +
+ +
+
+

Checks if a user is active

+ +
+
+
+ + +
+ + + Link to this function + + valid_token?(jwt_token) + + + + View Source + + + + +
+ + 
valid_token?(String.t()) :: Boolean.t() | {:error, :token_expired}
+ +
+ +
+
+

Validates if a JWT token is valid.

+ +
+
+
+ + +
+ + + Link to this function + + valid_user_name?(user_name) + + + + View Source + + + + +
+ + 
valid_user_name?(String.t()) :: Boolean.t()
+ +
+ +
+
+

Validates if a given user name is valid or not. It is valid if doesn’t exist a user +with that name in the database already

+ +
+
+ +
+ + + + +
+
+
+
+ + + + + + + + diff --git a/doc/POABackend.CustomHandler.REST.html b/doc/POABackend.CustomHandler.REST.html index f588d1d..9a7d8a5 100644 --- a/doc/POABackend.CustomHandler.REST.html +++ b/doc/POABackend.CustomHandler.REST.html @@ -4,11 +4,11 @@ - + POABackend.CustomHandler.REST – poa_backend v0.1.0 - + @@ -29,7 +29,7 @@
- +

poa_backend @@ -102,20 +102,41 @@ dynamically MessagePack formats

+

+ + session endpoint +

+ +

In order to get valid access to the rest of the endpoint you will need a JWT token. In order to get it check here

ping endpoint 

POST /ping
-

request:

-
Headers: {"content-type", "application/json" or "application/msgpack"}
-payload:
-  JSON:
+
Headers:

+
++++
+
+
+
+
+
+
+
+
+
+
+
+




HTTP headerValues
content-typeapplication/json or application/msgpack
authorizationBearer jwtToken

+
payload:

+
  JSON:
 
   {
     id: String() # agent id
-    secret: String() # secret string for authentication/authorisation
   }
 
   MessagePack:
@@ -146,9 +167,13 @@ payload:
 
 
 
Example:

-
curl -v -d '{"id":"agentID", "secret":"mysecret"}' -H "Content-Type: application/json" -X POST http://localhost:4002/ping
+
curl -v -d '{"id":"agentID"}' -H "Content-Type: application/json" -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJwb2FfYmFja2VuZCIsImV4cCI6MTUzMzkyNDc4NCwiaWF0IjoxNTMzOTIxMTg0LCJpc3MiOiJwb2FfYmFja2VuZCIsImp0aSI6IjFlM2U0MTU0LWJiNDMtNDY0MS04ZGFmLTIxNjRlOTFmMTU4YiIsIm5iZiI6MTUzMzkyMTE4Mywic3ViIjoiUmp1YURzdi0iLCJ0eXAiOiJhY2Nlc3MifQ.SqE48FXKhN7Y7aAsipFwvIAqetyhVJGwARMEwNwCXSK-QnXZdu3f2xkHDrXBsf1L1IlhTwg78Y-RiKrgepV34Q" -X POST http://localhost:4002/ping
 
 Note: Unnecessary use of -X or --request, POST is already inferred.
+*   Trying ::1...
+* TCP_NODELAY set
+* Connection failed
+* connect to ::1 port 4002 failed: Connection refused
 *   Trying 127.0.0.1...
 * TCP_NODELAY set
 * Connected to localhost (127.0.0.1) port 4002 (#0)
@@ -157,12 +182,13 @@ Note: Unnecessary use of -X or --request, POST is already inferred.
 > User-Agent: curl/7.53.1
 > Accept: */*
 > Content-Type: application/json
-> Content-Length: 37
+> Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJwb2FfYmFja2VuZCIsImV4cCI6MTUzMzkyNDc4NCwiaWF0IjoxNTMzOTIxMTg0LCJpc3MiOiJwb2FfYmFja2VuZCIsImp0aSI6IjFlM2U0MTU0LWJiNDMtNDY0MS04ZGFmLTIxNjRlOTFmMTU4YiIsIm5iZiI6MTUzMzkyMTE4Mywic3ViIjoiUmp1YURzdi0iLCJ0eXAiOiJhY2Nlc3MifQ.SqE48FXKhN7Y7aAsipFwvIAqetyhVJGwARMEwNwCXSK-QnXZdu3f2xkHDrXBsf1L1IlhTwg78Y-RiKrgepV34Q
+> Content-Length: 16
 >
-* upload completely sent off: 37 out of 37 bytes
+* upload completely sent off: 16 out of 16 bytes
 < HTTP/1.1 200 OK
 < server: Cowboy
-< date: Fri, 08 Jun 2018 13:27:58 GMT
+< date: Fri, 10 Aug 2018 17:14:33 GMT
 < content-length: 20
 < cache-control: max-age=0, private, must-revalidate
 < content-type: application/json; charset=utf-8
@@ -175,14 +201,29 @@ Note: Unnecessary use of -X or --request, POST is already inferred.
 

POST /data
-

request:

-
Headers: {"content-type", "application/json" or "application/msgpack"}
-payload:
-  JSON:
+
Headers:

+
++++
+
+
+
+
+
+
+
+
+
+
+
+




HTTP headerValues
content-typeapplication/json or application/msgpack
authorizationBearer jwtToken

+
payload:

+
  JSON:
 
   {
     id: String() # agent id
-    secret: String() # secret string for authentication/authorisation
     type: String() # data type (for now only ethereum_metrics)
     data: Object() # metric data itself
   }
@@ -215,9 +256,13 @@ payload:
 
 
 
Example:

-
curl -v -d '{"id":"agentID", "secret":"mysecret", "type":"ethereum_metrics", "data":{"hello":"world"}}' -H "Content-Type: application/json" -X POST http://localhost:4002/data
+
curl -v -d '{"id":"agentID", "type":"ethereum_metrics", "data":{"hello":"world"}}' -H "Content-Type: application/json" -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJwb2FfYmFja2VuZCIsImV4cCI6MTUzMzkyNDc4NCwiaWF0IjoxNTMzOTIxMTg0LCJpc3MiOiJwb2FfYmFja2VuZCIsImp0aSI6IjFlM2U0MTU0LWJiNDMtNDY0MS04ZGFmLTIxNjRlOTFmMTU4YiIsIm5iZiI6MTUzMzkyMTE4Mywic3ViIjoiUmp1YURzdi0iLCJ0eXAiOiJhY2Nlc3MifQ.SqE48FXKhN7Y7aAsipFwvIAqetyhVJGwARMEwNwCXSK-QnXZdu3f2xkHDrXBsf1L1IlhTwg78Y-RiKrgepV34Q" -X POST http://localhost:4002/data
 
 Note: Unnecessary use of -X or --request, POST is already inferred.
+*   Trying ::1...
+* TCP_NODELAY set
+* Connection failed
+* connect to ::1 port 4002 failed: Connection refused
 *   Trying 127.0.0.1...
 * TCP_NODELAY set
 * Connected to localhost (127.0.0.1) port 4002 (#0)
@@ -226,12 +271,13 @@ Note: Unnecessary use of -X or --request, POST is already inferred.
 > User-Agent: curl/7.53.1
 > Accept: */*
 > Content-Type: application/json
-> Content-Length: 90
+> Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJwb2FfYmFja2VuZCIsImV4cCI6MTUzMzkyNDc4NCwiaWF0IjoxNTMzOTIxMTg0LCJpc3MiOiJwb2FfYmFja2VuZCIsImp0aSI6IjFlM2U0MTU0LWJiNDMtNDY0MS04ZGFmLTIxNjRlOTFmMTU4YiIsIm5iZiI6MTUzMzkyMTE4Mywic3ViIjoiUmp1YURzdi0iLCJ0eXAiOiJhY2Nlc3MifQ.SqE48FXKhN7Y7aAsipFwvIAqetyhVJGwARMEwNwCXSK-QnXZdu3f2xkHDrXBsf1L1IlhTwg78Y-RiKrgepV34Q
+> Content-Length: 69
 >
-* upload completely sent off: 90 out of 90 bytes
+* upload completely sent off: 69 out of 69 bytes
 < HTTP/1.1 200 OK
 < server: Cowboy
-< date: Fri, 08 Jun 2018 16:02:22 GMT
+< date: Fri, 10 Aug 2018 17:17:34 GMT
 < content-length: 20
 < cache-control: max-age=0, private, must-revalidate
 < content-type: application/json; charset=utf-8
@@ -244,14 +290,29 @@ Note: Unnecessary use of -X or --request, POST is already inferred.
 

POST /bye
-

request:

-
Headers: {"content-type", "application/json" or "application/msgpack"}
-payload:
-  JSON:
+
Headers:

+
++++
+
+
+
+
+
+
+
+
+
+
+
+




HTTP headerValues
content-typeapplication/json or application/msgpack
authorizationBearer jwtToken

+
payload:

+
  JSON:
 
   {
     id: String() # agent id
-    secret: String() # secret string for authentication/authorisation
   }
 
   MessagePack:
@@ -282,9 +343,13 @@ payload:
 
 
 
Example:

-
curl -v -d '{"id":"agentID", "secret":"mysecret"}' -H "Content-Type: application/json" -X POST http://localhost:4002/bye
+
curl -v -d '{"id":"agentID"}' -H "Content-Type: application/json" -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJwb2FfYmFja2VuZCIsImV4cCI6MTUzMzkyNDc4NCwiaWF0IjoxNTMzOTIxMTg0LCJpc3MiOiJwb2FfYmFja2VuZCIsImp0aSI6IjFlM2U0MTU0LWJiNDMtNDY0MS04ZGFmLTIxNjRlOTFmMTU4YiIsIm5iZiI6MTUzMzkyMTE4Mywic3ViIjoiUmp1YURzdi0iLCJ0eXAiOiJhY2Nlc3MifQ.SqE48FXKhN7Y7aAsipFwvIAqetyhVJGwARMEwNwCXSK-QnXZdu3f2xkHDrXBsf1L1IlhTwg78Y-RiKrgepV34Q" -X POST http://localhost:4002/bye
 
 Note: Unnecessary use of -X or --request, POST is already inferred.
+*   Trying ::1...
+* TCP_NODELAY set
+* Connection failed
+* connect to ::1 port 4002 failed: Connection refused
 *   Trying 127.0.0.1...
 * TCP_NODELAY set
 * Connected to localhost (127.0.0.1) port 4002 (#0)
@@ -293,12 +358,13 @@ Note: Unnecessary use of -X or --request, POST is already inferred.
 > User-Agent: curl/7.53.1
 > Accept: */*
 > Content-Type: application/json
-> Content-Length: 37
+> Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJwb2FfYmFja2VuZCIsImV4cCI6MTUzMzkyNDc4NCwiaWF0IjoxNTMzOTIxMTg0LCJpc3MiOiJwb2FfYmFja2VuZCIsImp0aSI6IjFlM2U0MTU0LWJiNDMtNDY0MS04ZGFmLTIxNjRlOTFmMTU4YiIsIm5iZiI6MTUzMzkyMTE4Mywic3ViIjoiUmp1YURzdi0iLCJ0eXAiOiJhY2Nlc3MifQ.SqE48FXKhN7Y7aAsipFwvIAqetyhVJGwARMEwNwCXSK-QnXZdu3f2xkHDrXBsf1L1IlhTwg78Y-RiKrgepV34Q
+> Content-Length: 16
 >
-* upload completely sent off: 37 out of 37 bytes
+* upload completely sent off: 16 out of 16 bytes
 < HTTP/1.1 200 OK
 < server: Cowboy
-< date: Fri, 08 Jun 2018 15:49:05 GMT
+< date: Fri, 10 Aug 2018 17:19:24 GMT
 < content-length: 20
 < cache-control: max-age=0, private, must-revalidate
 < content-type: application/json; charset=utf-8
@@ -367,7 +433,7 @@ restart the timeout countdown

     
     ping_monitor(agent_id)
     
-      
+      
        
        View Source
      
@@ -393,7 +459,7 @@ restart the timeout countdown.

         

           
             Built using
-            ExDoc (v0.18.3),
+            ExDoc (v0.18.4),
           
           
             designed by
diff --git a/doc/POABackend.CustomHandler.html b/doc/POABackend.CustomHandler.html
index 606cbe3..5c183ff 100644
--- a/doc/POABackend.CustomHandler.html
+++ b/doc/POABackend.CustomHandler.html
@@ -4,11 +4,11 @@
     
     
     
-    
+    
     POABackend.CustomHandler – poa_backend v0.1.0
     
     
-    
+    
     
     
     
@@ -29,7 +29,7 @@
 

 
   
-  
+  
     

       

         poa_backend
@@ -308,7 +308,7 @@ to get the child specification for start the custom handler process.

         

           
             Built using
-            ExDoc (v0.18.3),
+            ExDoc (v0.18.4),
           
           
             designed by
diff --git a/doc/POABackend.Protocol.DataType.html b/doc/POABackend.Protocol.DataType.html
index 97791a9..4eba283 100644
--- a/doc/POABackend.Protocol.DataType.html
+++ b/doc/POABackend.Protocol.DataType.html
@@ -4,11 +4,11 @@
     
     
     
-    
+    
     POABackend.Protocol.DataType – poa_backend v0.1.0
     
     
-    
+    
     
     
     
@@ -29,7 +29,7 @@
 

 
   
-  
+  
     

       

         poa_backend
@@ -172,7 +172,7 @@
         

           
             Built using
-            ExDoc (v0.18.3),
+            ExDoc (v0.18.4),
           
           
             designed by
diff --git a/doc/POABackend.Protocol.Message.html b/doc/POABackend.Protocol.Message.html
index 4b08a67..b2dd061 100644
--- a/doc/POABackend.Protocol.Message.html
+++ b/doc/POABackend.Protocol.Message.html
@@ -4,11 +4,11 @@
     
     
     
-    
+    
     POABackend.Protocol.Message – poa_backend v0.1.0
     
     
-    
+    
     
     
     
@@ -29,7 +29,7 @@
 

 
   
-  
+  
     

       

         poa_backend
@@ -348,7 +348,7 @@ The params in order are: agent_id, data_type, message_type and data

         

           
             Built using
-            ExDoc (v0.18.3),
+            ExDoc (v0.18.4),
           
           
             designed by
diff --git a/doc/POABackend.Protocol.MessageType.html b/doc/POABackend.Protocol.MessageType.html
index bdd70fe..db7eef2 100644
--- a/doc/POABackend.Protocol.MessageType.html
+++ b/doc/POABackend.Protocol.MessageType.html
@@ -4,11 +4,11 @@
     
     
     
-    
+    
     POABackend.Protocol.MessageType – poa_backend v0.1.0
     
     
-    
+    
     
     
     
@@ -29,7 +29,7 @@
 

 
   
-  
+  
     

       

         poa_backend
@@ -179,7 +179,7 @@
         

           
             Built using
-            ExDoc (v0.18.3),
+            ExDoc (v0.18.4),
           
           
             designed by
diff --git a/doc/POABackend.Protocol.html b/doc/POABackend.Protocol.html
index 66de3f7..b475403 100644
--- a/doc/POABackend.Protocol.html
+++ b/doc/POABackend.Protocol.html
@@ -4,11 +4,11 @@
     
     
     
-    
+    
     POABackend.Protocol – poa_backend v0.1.0
     
     
-    
+    
     
     
     
@@ -29,7 +29,7 @@
 

 
   
-  
+  
     

       

         poa_backend
@@ -95,7 +95,7 @@
 
 
Only those calls are allowed:

 
    
-
  • session (not implemented) - In future in order to add authentication / authorization
+
  • session - In order to generate a token/session for authentication/authorization
 
    • 
 
  • ping - Ping message
 
    • 
@@ -104,44 +104,70 @@
 
  • bye - Message sent when the Agent wants to close the communication explicitly
 
    • 
 

-
ping call

+
session call

+
This call is for generate a valid token/session in order to get access to the other calls

 
abstract request:

 
{
+  user: String() # user name
+  password: String()
+}
+
+response:
+

+
{
+  token: String()  # this token must be attached to each call
+}

+

+#### ping call
+
+abstract request:
+

+
{
   id: String() # agent id
-  secret: String() # secret string for authentication/authorisation
-}

-
response:

-

-{
+  token: String() # generated with a valid user/password calling the session call
+}

+

+response:
+

+
{
   result: String()  # “success” or “error”
   payload: String() # optional payload
-}

-
data call

-
abstract request:

-
{
+}

+

+#### data call
+
+abstract request:
+

+
{
   id: String() # agent id
-  secret: String() # secret string for authentication/authorisation
+  token: String() # generated with a valid user/password calling the session call
   type: String() # data type (for now only ethereum_metrics)
   data: Object() # metric data itself
-}

-
response:

-

-{
+}

+

+response:
+

+
{
   result: String()  # “success” or “error”
   payload: String() # optional payload
-}

-
bye call

-
abstract request:

-
{
+}

+

+#### bye call
+
+abstract request:
+

+
{
   id: String() # agent id
-  secret: String() # secret string for authentication/authorisation
-}

-
response:

-

-{
+  token: String() # generated with a valid user/password calling the session call
+}

+

+response:
+

+
{
   result: String()  # “success” or “error”
   payload: String() # optional payload
-}

+}

+
@@ -157,7 +183,7 @@

Built using - ExDoc (v0.18.3), + ExDoc (v0.18.4), designed by diff --git a/doc/POABackend.Receiver.html b/doc/POABackend.Receiver.html index 69b8bd6..44a1049 100644 --- a/doc/POABackend.Receiver.html +++ b/doc/POABackend.Receiver.html @@ -4,11 +4,11 @@ - + POABackend.Receiver – poa_backend v0.1.0 - + @@ -29,7 +29,7 @@

- +

poa_backend @@ -423,7 +423,7 @@ end

Built using - ExDoc (v0.18.3), + ExDoc (v0.18.4), designed by diff --git a/doc/POABackend.Receivers.Dashboard.html b/doc/POABackend.Receivers.Dashboard.html index 4c039a6..22bbb83 100644 --- a/doc/POABackend.Receivers.Dashboard.html +++ b/doc/POABackend.Receivers.Dashboard.html @@ -4,11 +4,11 @@ - + POABackend.Receivers.Dashboard – poa_backend v0.1.0 - + @@ -29,7 +29,7 @@

- +

poa_backend @@ -199,7 +199,7 @@ handle_inactive(agent_id, state) - + View Source @@ -225,7 +225,7 @@ handle_message(arg, state) - + View Source @@ -250,7 +250,7 @@ init_receiver(opts) - + View Source @@ -277,7 +277,7 @@ metrics_received(metrics, from, state) - + View Source @@ -302,7 +302,7 @@ terminate(_) - + View Source @@ -325,7 +325,7 @@

Built using - ExDoc (v0.18.3), + ExDoc (v0.18.4), designed by diff --git a/doc/POABackend.Receivers.DynamoDB.html b/doc/POABackend.Receivers.DynamoDB.html index 845a47f..3c2ab40 100644 --- a/doc/POABackend.Receivers.DynamoDB.html +++ b/doc/POABackend.Receivers.DynamoDB.html @@ -4,11 +4,11 @@ - + POABackend.Receivers.DynamoDB – poa_backend v0.1.0 - + @@ -29,7 +29,7 @@

- +

poa_backend @@ -331,7 +331,7 @@

Built using - ExDoc (v0.18.3), + ExDoc (v0.18.4), designed by diff --git a/doc/POABackend.html b/doc/POABackend.html index d9eb7f2..eaee582 100644 --- a/doc/POABackend.html +++ b/doc/POABackend.html @@ -4,11 +4,11 @@ - + POABackend – poa_backend v0.1.0 - + @@ -29,7 +29,7 @@

- +

poa_backend @@ -81,13 +81,22 @@
-

Storage and data-processing companion for the poa-netstats-agent

+

POABackend

+

Coverage Status +codecov

+

Storage and data-processing companion for the poa-netstats-agent

Documentation

-

In order to build the documentation run

+ +

Or you can build the documenation locally running

mix deps.get
 mix docs

That command will create a doc/ folder with the actual Documentation.

@@ -96,11 +105,38 @@ mix docs Run Tests

-

In order to run the tests we have to run the command

+

POABackend uses Mnesia as a local database with Ecto. In order to have this running we have to create a folder where Mnesia will store our data. In order to do that we have to define it in the config/test.exs file like this:

+
config :mnesia,
+  dir: 'your/local/path' # make sure this directory exists!
+

once we have the path defined we have to create the database (those commands must be run only once if you are going to use always this same path for testing). In your root folder run:

+
MIX_ENV=test mix ecto.create
+MIX_ENV=test mix ecto.migrate
+

Now the environment is set. We can run the tests with:

mix test

POABackend comes also with a code analysis tool Credo and a types checker tool Dialyxir. In order to run them we have to run

mix credo
 mix dialyzer
+

+ + Building & Deploying an Executable +

+ +

To build an executable you’ll need Elixir 1.6 (and Erlang/OTP 20).

+
    +
  1. Once you have a copy of this repository configure the backend for production in the file config/prod.exs. +
    2. +
  2. An example configuration can be found in the current config/prod.exs. +
    3. +
  3. Do a mix deps.get to fetch, among other dependencies, the tooling for building server executables. +
    4. +
  4. A env MIX_ENV=prod mix release --name=poa_backend --env=prod will assemble an executable. +
    5. +
+

A resulting artifact resides at _build/prod/rel/poa_backend/releases/0.1.0/poa_backend.tar.gz which you can move to a remote host. +Use tar xfz then bin/poa_agent start (bin/poa_agent stop will stop the server cleanly).

+

If you want to run it on the local host then the procedure is as simple as: _build/prod/rel/poa_backend/bin/poa_backend.

+

Note: executables must be built on the platform (OS and architecture) they are destined for under the project’s current configuration. +Other options are possible (see https://hexdocs.pm/distillery/getting-started.html).

@@ -116,7 +152,7 @@ mix dialyzer

Built using - ExDoc (v0.18.3), + ExDoc (v0.18.4), designed by diff --git a/doc/api-reference.html b/doc/api-reference.html index 8fc5035..8029746 100644 --- a/doc/api-reference.html +++ b/doc/api-reference.html @@ -4,11 +4,11 @@ - + API Reference – poa_backend v0.1.0 - + @@ -29,7 +29,7 @@

- +

poa_backend @@ -84,7 +84,48 @@
POABackend
-

Storage and data-processing companion for the poa-netstats-agent

+

POABackend

+
+ +
+
+
POABackend.Auth
+ +

This module defines the API for the Authorisation

+
+ +
+
+
POABackend.Auth.Guardian.Plug
+ +
+
+
POABackend.Auth.Models.Token
+ +

This module encapsulates the Token model. This is used in order to store banned tokens in Database

+
+ +
+
+
POABackend.Auth.Models.User
+ +

This module encapsulates the User model

+
+ +
+
+
POABackend.Auth.REST
+ +

Here we define the REST Endpoints for Authentication/Authorization features in poa_backend. +There are two types of users who will use this Endpoints.

+
    +
  • One is the standard user which is associated to one Agent. This user will call only the /session endpoint in order to retrieve a JWT token +needed for using the POA Protocol Endpoints. Those users are stored in a Database. +
    • +
  • The other kind of users are the POA administrators. This users can create normal users using the /user Endpoint, banning tokens, banning users… +Those Admins are defined in the Config (ie prod.exs) file and are loaded when the app starts. This is an example of how the Admins are defined +
    • +
@@ -168,7 +209,7 @@

Built using - ExDoc (v0.18.3), + ExDoc (v0.18.4), designed by diff --git a/doc/dist/sidebar_items-3739fd4c82.js b/doc/dist/sidebar_items-3739fd4c82.js new file mode 100644 index 0000000..f9f2f9a --- /dev/null +++ b/doc/dist/sidebar_items-3739fd4c82.js @@ -0,0 +1 @@ +sidebarNodes={"extras":[{"id":"api-reference","title":"API Reference","group":"","headers":[{"id":"Modules","anchor":"modules"},{"id":"POA Protocol","anchor":"poa-protocol"}]},{"id":"initial_architecture","title":"Initial Architecture","group":"","headers":[]}],"exceptions":[],"modules":[{"id":"POABackend","title":"POABackend","group":""},{"id":"POABackend.Auth","title":"POABackend.Auth","group":"POA Auth","functions":[{"id":"activate_user/1","anchor":"activate_user/1"},{"id":"authenticate_admin/2","anchor":"authenticate_admin/2"},{"id":"authenticate_user/2","anchor":"authenticate_user/2"},{"id":"create_banned_token/1","anchor":"create_banned_token/1"},{"id":"create_banned_token/2","anchor":"create_banned_token/2"},{"id":"create_user/3","anchor":"create_user/3"},{"id":"deactivate_user/1","anchor":"deactivate_user/1"},{"id":"generate_password/0","anchor":"generate_password/0"},{"id":"generate_user_name/0","anchor":"generate_user_name/0"},{"id":"generate_user_name/1","anchor":"generate_user_name/1"},{"id":"get_user/1","anchor":"get_user/1"},{"id":"purge_banned_tokens/0","anchor":"purge_banned_tokens/0"},{"id":"remove_user/1","anchor":"remove_user/1"},{"id":"token_banned?/1","anchor":"token_banned?/1"},{"id":"user_active?/1","anchor":"user_active?/1"},{"id":"valid_token?/1","anchor":"valid_token?/1"},{"id":"valid_user_name?/1","anchor":"valid_user_name?/1"}]},{"id":"POABackend.Auth.Guardian.Plug","title":"POABackend.Auth.Guardian.Plug","group":"POA Auth","functions":[{"id":"authenticated?/2","anchor":"authenticated?/2"},{"id":"current_claims/2","anchor":"current_claims/2"},{"id":"current_resource/2","anchor":"current_resource/2"},{"id":"current_token/2","anchor":"current_token/2"},{"id":"implementation/0","anchor":"implementation/0"},{"id":"put_current_claims/3","anchor":"put_current_claims/3"},{"id":"put_current_resource/3","anchor":"put_current_resource/3"},{"id":"put_current_token/3","anchor":"put_current_token/3"},{"id":"remember_me/4","anchor":"remember_me/4"},{"id":"remember_me_from_token/4","anchor":"remember_me_from_token/4"},{"id":"sign_in/4","anchor":"sign_in/4"},{"id":"sign_out/2","anchor":"sign_out/2"}]},{"id":"POABackend.Auth.Models.Token","title":"POABackend.Auth.Models.Token","group":"POA Auth","functions":[{"id":"new/2","anchor":"new/2"}],"types":[{"id":"t/0","anchor":"t:t/0"}]},{"id":"POABackend.Auth.Models.User","title":"POABackend.Auth.Models.User","group":"POA Auth","functions":[{"id":"changeset/2","anchor":"changeset/2"}],"types":[{"id":"t/0","anchor":"t:t/0"}]},{"id":"POABackend.Auth.REST","title":"POABackend.Auth.REST","group":"POA Auth"},{"id":"POABackend.Protocol","title":"POABackend.Protocol","group":"POA Protocol"},{"id":"POABackend.Protocol.DataType","title":"POABackend.Protocol.DataType","group":"POA Protocol","types":[{"id":"t/0","anchor":"t:t/0"}]},{"id":"POABackend.Protocol.Message","title":"POABackend.Protocol.Message","group":"POA Protocol","functions":[{"id":"assign/3","anchor":"assign/3"},{"id":"new/0","anchor":"new/0"},{"id":"new/4","anchor":"new/4"}],"types":[{"id":"t/0","anchor":"t:t/0"}]},{"id":"POABackend.Protocol.MessageType","title":"POABackend.Protocol.MessageType","group":"POA Protocol","types":[{"id":"t/0","anchor":"t:t/0"}]},{"id":"POABackend.CustomHandler","title":"POABackend.CustomHandler","group":"Custom Handler","callbacks":[{"id":"child_spec/1","anchor":"c:child_spec/1"}],"functions":[{"id":"publish_inactive/1","anchor":"publish_inactive/1"},{"id":"send_to_receivers/1","anchor":"send_to_receivers/1"}]},{"id":"POABackend.CustomHandler.REST","title":"POABackend.CustomHandler.REST","group":"Custom Handler","functions":[{"id":"ping_monitor/1","anchor":"ping_monitor/1"}]},{"id":"POABackend.Receiver","title":"POABackend.Receiver","group":"Receivers","callbacks":[{"id":"handle_inactive/2","anchor":"c:handle_inactive/2"},{"id":"handle_message/2","anchor":"c:handle_message/2"},{"id":"init_receiver/1","anchor":"c:init_receiver/1"},{"id":"metrics_received/3","anchor":"c:metrics_received/3"},{"id":"terminate/1","anchor":"c:terminate/1"}]},{"id":"POABackend.Receivers.Dashboard","title":"POABackend.Receivers.Dashboard","group":"Receivers","functions":[{"id":"handle_inactive/2","anchor":"handle_inactive/2"},{"id":"handle_message/2","anchor":"handle_message/2"},{"id":"init_receiver/1","anchor":"init_receiver/1"},{"id":"metrics_received/3","anchor":"metrics_received/3"},{"id":"terminate/1","anchor":"terminate/1"}]},{"id":"POABackend.Receivers.DynamoDB","title":"POABackend.Receivers.DynamoDB","group":"Receivers","functions":[{"id":"handle_inactive/2","anchor":"handle_inactive/2"},{"id":"handle_message/2","anchor":"handle_message/2"},{"id":"init_receiver/1","anchor":"init_receiver/1"},{"id":"metrics_received/3","anchor":"metrics_received/3"},{"id":"terminate/1","anchor":"terminate/1"}]}],"tasks":[]} \ No newline at end of file diff --git a/doc/dist/sidebar_items-ffeb4f1e51.js b/doc/dist/sidebar_items-ffeb4f1e51.js deleted file mode 100644 index 21f4162..0000000 --- a/doc/dist/sidebar_items-ffeb4f1e51.js +++ /dev/null @@ -1 +0,0 @@ -sidebarNodes={"extras":[{"id":"api-reference","title":"API Reference","group":"","headers":[{"id":"Modules","anchor":"modules"},{"id":"POA Protocol","anchor":"poa-protocol"}]},{"id":"initial_architecture","title":"Initial Architecture","group":"","headers":[]}],"exceptions":[],"modules":[{"id":"POABackend","title":"POABackend","group":""},{"id":"POABackend.Protocol","title":"POABackend.Protocol","group":"POA Protocol"},{"id":"POABackend.Protocol.DataType","title":"POABackend.Protocol.DataType","group":"POA Protocol","types":[{"id":"t/0","anchor":"t:t/0"}]},{"id":"POABackend.Protocol.Message","title":"POABackend.Protocol.Message","group":"POA Protocol","functions":[{"id":"assign/3","anchor":"assign/3"},{"id":"new/0","anchor":"new/0"},{"id":"new/4","anchor":"new/4"}],"types":[{"id":"t/0","anchor":"t:t/0"}]},{"id":"POABackend.Protocol.MessageType","title":"POABackend.Protocol.MessageType","group":"POA Protocol","types":[{"id":"t/0","anchor":"t:t/0"}]},{"id":"POABackend.CustomHandler","title":"POABackend.CustomHandler","group":"Custom Handler","callbacks":[{"id":"child_spec/1","anchor":"c:child_spec/1"}],"functions":[{"id":"publish_inactive/1","anchor":"publish_inactive/1"},{"id":"send_to_receivers/1","anchor":"send_to_receivers/1"}]},{"id":"POABackend.CustomHandler.REST","title":"POABackend.CustomHandler.REST","group":"Custom Handler","functions":[{"id":"ping_monitor/1","anchor":"ping_monitor/1"}]},{"id":"POABackend.Receiver","title":"POABackend.Receiver","group":"Receivers","callbacks":[{"id":"handle_inactive/2","anchor":"c:handle_inactive/2"},{"id":"handle_message/2","anchor":"c:handle_message/2"},{"id":"init_receiver/1","anchor":"c:init_receiver/1"},{"id":"metrics_received/3","anchor":"c:metrics_received/3"},{"id":"terminate/1","anchor":"c:terminate/1"}]},{"id":"POABackend.Receivers.Dashboard","title":"POABackend.Receivers.Dashboard","group":"Receivers","functions":[{"id":"handle_inactive/2","anchor":"handle_inactive/2"},{"id":"handle_message/2","anchor":"handle_message/2"},{"id":"init_receiver/1","anchor":"init_receiver/1"},{"id":"metrics_received/3","anchor":"metrics_received/3"},{"id":"terminate/1","anchor":"terminate/1"}]},{"id":"POABackend.Receivers.DynamoDB","title":"POABackend.Receivers.DynamoDB","group":"Receivers","functions":[{"id":"handle_inactive/2","anchor":"handle_inactive/2"},{"id":"handle_message/2","anchor":"handle_message/2"},{"id":"init_receiver/1","anchor":"init_receiver/1"},{"id":"metrics_received/3","anchor":"metrics_received/3"},{"id":"terminate/1","anchor":"terminate/1"}]}],"tasks":[]} \ No newline at end of file diff --git a/doc/index.html b/doc/index.html index ada0c24..1df5816 100644 --- a/doc/index.html +++ b/doc/index.html @@ -3,9 +3,9 @@ poa_backend v0.1.0 – Documentation - + - + diff --git a/doc/initial_architecture.html b/doc/initial_architecture.html index 2749e78..2381c92 100644 --- a/doc/initial_architecture.html +++ b/doc/initial_architecture.html @@ -4,11 +4,11 @@ - + Initial Architecture – poa_backend v0.1.0 - + @@ -29,7 +29,7 @@

- +

poa_backend @@ -110,7 +110,7 @@ The Dashboard UI (NodeJS) will be refactored and modified in order to speak dire

Built using - ExDoc (v0.18.3), + ExDoc (v0.18.4), designed by diff --git a/doc/search.html b/doc/search.html index c072c60..1c12f43 100644 --- a/doc/search.html +++ b/doc/search.html @@ -4,11 +4,11 @@ - + Search – poa_backend v0.1.0 - + @@ -29,7 +29,7 @@

- +

poa_backend @@ -74,7 +74,7 @@

Built using - ExDoc (v0.18.3), + ExDoc (v0.18.4), designed by diff --git a/lib/poa_backend.ex b/lib/poa_backend.ex index 1a6cd01..eb7f434 100644 --- a/lib/poa_backend.ex +++ b/lib/poa_backend.ex @@ -1,10 +1,18 @@ defmodule POABackend do @moduledoc """ + # POABackend + + [![Coverage Status](https://coveralls.io/repos/github/poanetwork/poa-netstats-warehouse/badge.svg?branch=master)](https://coveralls.io/github/poanetwork/poa-netstats-warehouse?branch=master) + [![codecov](https://codecov.io/gh/poanetwork/poa-netstats-warehouse/branch/master/graph/badge.svg)](https://codecov.io/gh/poanetwork/poa-netstats-warehouse) + Storage and data-processing companion for the [poa-netstats-agent](https://github.com/poanetwork/poa-netstats-agent) ## Documentation - In order to build the documentation run + - [Initial Architecture](pages/initial_architecture.md) + - You can find the online documentation [here](index.html) + + Or you can build the documenation locally running ``` mix deps.get @@ -15,7 +23,21 @@ defmodule POABackend do ## Run Tests - In order to run the tests we have to run the command + `POABackend` uses [Mnesia](http://erlang.org/doc/man/mnesia.html) as a local database with [Ecto](https://hexdocs.pm/ecto/Ecto.html). In order to have this running we have to create a folder where `Mnesia` will store our data. In order to do that we have to define it in the `config/test.exs` file like this: + + ``` + config :mnesia, + dir: 'your/local/path' # make sure this directory exists! + ``` + + once we have the path defined we have to create the database (those commands must be run only once if you are going to use always this same path for testing). In your root folder run: + + ``` + MIX_ENV=test mix ecto.create + MIX_ENV=test mix ecto.migrate + ``` + + Now the environment is set. We can run the tests with: ``` mix test @@ -27,5 +49,22 @@ defmodule POABackend do mix credo mix dialyzer ``` + + ## Building & Deploying an Executable + + To build an executable you'll need Elixir 1.6 (and Erlang/OTP 20). + + 1. Once you have a copy of this repository configure the backend for production in the file `config/prod.exs`. + 2. An example configuration can be found in the current `config/prod.exs`. + 3. Do a `mix deps.get` to fetch, among other dependencies, the tooling for building server executables. + 4. A `env MIX_ENV=prod mix release --name=poa_backend --env=prod` will assemble an executable. + + A resulting artifact resides at `_build/prod/rel/poa_backend/releases/0.1.0/poa_backend.tar.gz` which you can move to a remote host. + Use `tar xfz` then `bin/poa_agent start` (`bin/poa_agent stop` will stop the server cleanly). + + If you want to run it on the local host then the procedure is as simple as: `_build/prod/rel/poa_backend/bin/poa_backend`. + + **Note:** executables must be built on the platform (OS and architecture) they are destined for under the project's current configuration. + Other options are possible (see `https://hexdocs.pm/distillery/getting-started.html`). """ end diff --git a/lib/poa_backend/auth/models/token.ex b/lib/poa_backend/auth/models/token.ex index 08e7dba..9a2d37a 100644 --- a/lib/poa_backend/auth/models/token.ex +++ b/lib/poa_backend/auth/models/token.ex @@ -2,7 +2,7 @@ defmodule POABackend.Auth.Models.Token do use Ecto.Schema @moduledoc """ - This module encapsulates the _Token_ model + This module encapsulates the _Token_ model. This is used in order to store banned tokens in Database """ @primary_key {:token, :string, []} diff --git a/lib/poa_backend/auth/rest.ex b/lib/poa_backend/auth/rest.ex new file mode 100644 index 0000000..2e55b6b --- /dev/null +++ b/lib/poa_backend/auth/rest.ex @@ -0,0 +1,180 @@ +defmodule POABackend.Auth.REST do + @moduledoc """ + + Here we define the REST Endpoints for Authentication/Authorization features in `poa_backend`. + There are two types of users who will use this Endpoints. + - One is the standard user which is associated to one Agent. This user will call only the _/session_ endpoint in order to retrieve a [JWT](https://jwt.io) token + needed for using the _POA Protocol_ Endpoints. Those users are stored in a Database. + - The other kind of users are the POA administrators. This users can create _normal_ users using the _/user_ Endpoint, banning tokens, banning users... + Those Admins are defined in the Config (ie `prod.exs`) file and are loaded when the app starts. This is an example of how the Admins are defined + + ``` + config :poa_backend, + :admins, + [ + {"admin1", "password12345678"}, + {"admin2", "password87654321"} + ] + ``` + + Those Endpoints must run under *__https__* schema + + ## Session Endpoint + + This endpoint will be responsible of returning valid JWT tokens to the Agents if they use a valid user/password for authentication. The form of the endpoint is: + + `POST /session` + + HTTP header | Values + -- | -- + content-type | application/json or application/msgpack + authorization | Basic encodeBase64(username + “:” + password) + + Payload | Value + -- | -- + JSON | {“agent-id”:”theAgentID”} + MessagePack | Same as JSON but packed with MessagePack + + Response: + + CODE | Description + -- | -- + 200 | Success: {“token”:”NewToken”} + 401 | Authentication failed + 415 | Unsupported Media Type (only application/json and application/msgpack allowed) + + Example: + + ``` + curl -i -X POST -H "Authorization: Basic Ump1YURzdi06WHY3X0xvQ0FVZVduYmN5" -H "Content-Type: application/json" https://localhost:4003/session --insecure + + HTTP/1.1 200 OK + server: Cowboy + date: Fri, 10 Aug 2018 20:25:05 GMT + content-length: 362 + cache-control: max-age=0, private, must-revalidate + + {"token":"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJwb2FfYmFja2VuZCIsImV4cCI6MTUzMzkzNjMwNiwiaWF0IjoxNTMzOTMyNzA2LCJpc3MiOiJwb2FfYmFja2VuZCIsImp0aSI6ImI0MzBkNTMwLWExZDYtNDk1Yy1hMjYyLThjNTcxMmM1OTM4YSIsIm5iZiI6MTUzMzkzMjcwNSwic3ViIjoiUmp1YURzdi0iLCJ0eXAiOiJhY2Nlc3MifQ.E3gqpCxY5wAAhZwcr7vZVLcC7X-bSHcXfX6NgeJc-LMbpcDgJvZgcgYQ-VTIkulb2mWw_Fjc7sXVwYMeIIliMg"} + ``` + + ## User Endpoint + + This Endpoint is needed in order to add a new user. Only Admin people can do that. + + `POST /user` + + HTTP header | Values + -- | -- + content-type | application/json or application/msgpack + authorization | Basic encodeBase64(adminname + “:” + password) + + Payload | Value + -- | -- + JSON | {"agent-id": "AgentId", user-name”:”userName”, "password": "mypassword"} + MessagePack | Same as JSON but packed with MessagePack + + *_NOTE_* `user-name` and `password` field are optional. If we send only the `user-name` the server will create a random password. If we don't send any value the the server + will create both, `user-name` and `password` + + Response + + CODE | Description + -- | -- + 200 | Success: {“user”:”Username”, “password”:”mypassword”} + 401 | Authentication failed + 409 | The user already exists + 415 | Unsupported Media Type (only application/json and application/msgpack allowed) + + Example: + + ``` + curl -i -X POST -H "Authorization: Basic YWRtaW4xOnBhc3N3b3JkMTIzNDU2Nzg=" -H "Content-Type: application/json" https://localhost:4003/user --insecure + + HTTP/1.1 200 OK + server: Cowboy + date: Fri, 10 Aug 2018 20:40:04 GMT + content-length: 53 + cache-control: max-age=0, private, must-revalidate + + {"user-name":"vhuevkMy","password":"XkBCEJmuuEzPvy8"} + ``` + + ## Blacklist Token Endpoint + + This Endpoint is used when we want to ban a single JWT Token (not the entire user) and that will convert that Token invalid. This Endpoint is only called by Admins. + + In order to achive that we have to track the tokens in a Mnesia table. We also have to create a process which cleans the DB every day + + `POST /blacklist/token` + + HTTP header | Values + -- | -- + content-type | application/json or application/msgpack + authorization | Basic encodeBase64(adminname + “:” + password) + + Payload | Value + -- | -- + JSON | {“token”:”myJWTToken”} + MessagePack | Same as JSON but packed with MessagePack + + Response + + CODE | Description + -- | -- + 200 | Success + 401 | Authentication failed + 404 | The Token is not valid + 415 | Unsupported Media Type (only application/json and application/msgpack allowed) + + Example: + + ``` + curl -i -d '{"token":"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJwb2FfYmFja2VuZCIsImV4cCI6MTUzMzkzNjMwNiwiaWF0IjoxNTMzOTMyNzA2LCJpc3MiOiJwb2FfYmFja2VuZCIsImp0aSI6ImI0MzBkNTMwLWExZDYtNDk1Yy1hMjYyLThjNTcxMmM1OTM4YSIsIm5iZiI6MTUzMzkzMjcwNSwic3ViIjoiUmp1YURzdi0iLCJ0eXAiOiJhY2Nlc3MifQ.E3gqpCxY5wAAhZwcr7vZVLcC7X-bSHcXfX6NgeJc-LMbpcDgJvZgcgYQ-VTIkulb2mWw_Fjc7sXVwYMeIIliMg"}' -X POST -H "Authorization: Basic YWRtaW4xOnBhc3N3b3JkMTIzNDU2Nzg=" -H "Content-Type: application/json" https://localhost:4003/blacklist/token --insecure + + HTTP/1.1 200 OK + server: Cowboy + date: Fri, 10 Aug 2018 20:59:25 GMT + content-length: 0 + cache-control: max-age=0, private, must-revalidate + ``` + + ## Blacklist User Endpoint + + This Endpoint bans a User, that will invalidate its tokens. This Endpoint is only called by Admins. + + In order to achive that we have to track the tokens in a Mnesia table. We also have to create a process which cleans the DB every day + + `POST /blacklist/user` + + HTTP header | Values + -- | -- + content-type | application/json or application/msgpack + authorization | Basic encodeBase64(adminname + “:” + password) + + Payload | Value + -- | -- + JSON | {“user”:”theUserName”} + MessagePack | Same as JSON but packed with MessagePack + + Response + + CODE | Description + -- | -- + 200 | Success + 401 | Authentication failed + 404 | The user doesn't exist + 415 | Unsupported Media Type (only application/json and application/msgpack allowed) + + Example: + + ``` + curl -i -d '{"user":"vhuevkMy"}' -X POST -H "Authorization: Basic YWRtaW4xOnBhc3N3b3JkMTIzNDU2Nzg=" -H "Content-Type: application/json" https://localhost:4003/blacklist/user --insecure + + HTTP/1.1 200 OK + server: Cowboy + date: Fri, 10 Aug 2018 21:55:03 GMT + content-length: 0 + cache-control: max-age=0, private, must-revalidate + ``` + """ +end \ No newline at end of file diff --git a/lib/poa_backend/custom_handler/rest.ex b/lib/poa_backend/custom_handler/rest.ex index 13fbbf7..6536b9d 100644 --- a/lib/poa_backend/custom_handler/rest.ex +++ b/lib/poa_backend/custom_handler/rest.ex @@ -25,22 +25,30 @@ defmodule POABackend.CustomHandler.REST do __All the endpoints accept pure JSON or [MessagePack](https://msgpack.org/) formats__ + ## _session_ endpoint + + In order to get valid access to the rest of the endpoint you will need a JWT token. In order to get it check [here](POABackend.Auth.REST.html#module-session-endpoint) + ## _ping_ endpoint ``` POST /ping ``` - request: + Headers: + + HTTP header | Values + -- | -- + content-type | application/json or application/msgpack + authorization | Bearer jwtToken - ``` - Headers: {"content-type", "application/json" or "application/msgpack"} payload: + + ```json JSON: { id: String() # agent id - secret: String() # secret string for authentication/authorisation } MessagePack: @@ -60,9 +68,13 @@ defmodule POABackend.CustomHandler.REST do Example: ``` - curl -v -d '{"id":"agentID", "secret":"mysecret"}' -H "Content-Type: application/json" -X POST http://localhost:4002/ping + curl -v -d '{"id":"agentID"}' -H "Content-Type: application/json" -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJwb2FfYmFja2VuZCIsImV4cCI6MTUzMzkyNDc4NCwiaWF0IjoxNTMzOTIxMTg0LCJpc3MiOiJwb2FfYmFja2VuZCIsImp0aSI6IjFlM2U0MTU0LWJiNDMtNDY0MS04ZGFmLTIxNjRlOTFmMTU4YiIsIm5iZiI6MTUzMzkyMTE4Mywic3ViIjoiUmp1YURzdi0iLCJ0eXAiOiJhY2Nlc3MifQ.SqE48FXKhN7Y7aAsipFwvIAqetyhVJGwARMEwNwCXSK-QnXZdu3f2xkHDrXBsf1L1IlhTwg78Y-RiKrgepV34Q" -X POST http://localhost:4002/ping Note: Unnecessary use of -X or --request, POST is already inferred. + * Trying ::1... + * TCP_NODELAY set + * Connection failed + * connect to ::1 port 4002 failed: Connection refused * Trying 127.0.0.1... * TCP_NODELAY set * Connected to localhost (127.0.0.1) port 4002 (#0) @@ -71,12 +83,13 @@ defmodule POABackend.CustomHandler.REST do > User-Agent: curl/7.53.1 > Accept: */* > Content-Type: application/json - > Content-Length: 37 + > Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJwb2FfYmFja2VuZCIsImV4cCI6MTUzMzkyNDc4NCwiaWF0IjoxNTMzOTIxMTg0LCJpc3MiOiJwb2FfYmFja2VuZCIsImp0aSI6IjFlM2U0MTU0LWJiNDMtNDY0MS04ZGFmLTIxNjRlOTFmMTU4YiIsIm5iZiI6MTUzMzkyMTE4Mywic3ViIjoiUmp1YURzdi0iLCJ0eXAiOiJhY2Nlc3MifQ.SqE48FXKhN7Y7aAsipFwvIAqetyhVJGwARMEwNwCXSK-QnXZdu3f2xkHDrXBsf1L1IlhTwg78Y-RiKrgepV34Q + > Content-Length: 16 > - * upload completely sent off: 37 out of 37 bytes + * upload completely sent off: 16 out of 16 bytes < HTTP/1.1 200 OK < server: Cowboy - < date: Fri, 08 Jun 2018 13:27:58 GMT + < date: Fri, 10 Aug 2018 17:14:33 GMT < content-length: 20 < cache-control: max-age=0, private, must-revalidate < content-type: application/json; charset=utf-8 @@ -91,16 +104,20 @@ defmodule POABackend.CustomHandler.REST do POST /data ``` - request: + Headers: + + HTTP header | Values + -- | -- + content-type | application/json or application/msgpack + authorization | Bearer jwtToken - ``` - Headers: {"content-type", "application/json" or "application/msgpack"} payload: + + ```json JSON: { id: String() # agent id - secret: String() # secret string for authentication/authorisation type: String() # data type (for now only ethereum_metrics) data: Object() # metric data itself } @@ -122,9 +139,13 @@ defmodule POABackend.CustomHandler.REST do Example: ``` - curl -v -d '{"id":"agentID", "secret":"mysecret", "type":"ethereum_metrics", "data":{"hello":"world"}}' -H "Content-Type: application/json" -X POST http://localhost:4002/data + curl -v -d '{"id":"agentID", "type":"ethereum_metrics", "data":{"hello":"world"}}' -H "Content-Type: application/json" -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJwb2FfYmFja2VuZCIsImV4cCI6MTUzMzkyNDc4NCwiaWF0IjoxNTMzOTIxMTg0LCJpc3MiOiJwb2FfYmFja2VuZCIsImp0aSI6IjFlM2U0MTU0LWJiNDMtNDY0MS04ZGFmLTIxNjRlOTFmMTU4YiIsIm5iZiI6MTUzMzkyMTE4Mywic3ViIjoiUmp1YURzdi0iLCJ0eXAiOiJhY2Nlc3MifQ.SqE48FXKhN7Y7aAsipFwvIAqetyhVJGwARMEwNwCXSK-QnXZdu3f2xkHDrXBsf1L1IlhTwg78Y-RiKrgepV34Q" -X POST http://localhost:4002/data Note: Unnecessary use of -X or --request, POST is already inferred. + * Trying ::1... + * TCP_NODELAY set + * Connection failed + * connect to ::1 port 4002 failed: Connection refused * Trying 127.0.0.1... * TCP_NODELAY set * Connected to localhost (127.0.0.1) port 4002 (#0) @@ -133,12 +154,13 @@ defmodule POABackend.CustomHandler.REST do > User-Agent: curl/7.53.1 > Accept: */* > Content-Type: application/json - > Content-Length: 90 + > Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJwb2FfYmFja2VuZCIsImV4cCI6MTUzMzkyNDc4NCwiaWF0IjoxNTMzOTIxMTg0LCJpc3MiOiJwb2FfYmFja2VuZCIsImp0aSI6IjFlM2U0MTU0LWJiNDMtNDY0MS04ZGFmLTIxNjRlOTFmMTU4YiIsIm5iZiI6MTUzMzkyMTE4Mywic3ViIjoiUmp1YURzdi0iLCJ0eXAiOiJhY2Nlc3MifQ.SqE48FXKhN7Y7aAsipFwvIAqetyhVJGwARMEwNwCXSK-QnXZdu3f2xkHDrXBsf1L1IlhTwg78Y-RiKrgepV34Q + > Content-Length: 69 > - * upload completely sent off: 90 out of 90 bytes + * upload completely sent off: 69 out of 69 bytes < HTTP/1.1 200 OK < server: Cowboy - < date: Fri, 08 Jun 2018 16:02:22 GMT + < date: Fri, 10 Aug 2018 17:17:34 GMT < content-length: 20 < cache-control: max-age=0, private, must-revalidate < content-type: application/json; charset=utf-8 @@ -153,16 +175,20 @@ defmodule POABackend.CustomHandler.REST do POST /bye ``` - request: + Headers: + + HTTP header | Values + -- | -- + content-type | application/json or application/msgpack + authorization | Bearer jwtToken - ``` - Headers: {"content-type", "application/json" or "application/msgpack"} payload: + + ```json JSON: { id: String() # agent id - secret: String() # secret string for authentication/authorisation } MessagePack: @@ -182,9 +208,13 @@ defmodule POABackend.CustomHandler.REST do Example: ``` - curl -v -d '{"id":"agentID", "secret":"mysecret"}' -H "Content-Type: application/json" -X POST http://localhost:4002/bye - + curl -v -d '{"id":"agentID"}' -H "Content-Type: application/json" -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJwb2FfYmFja2VuZCIsImV4cCI6MTUzMzkyNDc4NCwiaWF0IjoxNTMzOTIxMTg0LCJpc3MiOiJwb2FfYmFja2VuZCIsImp0aSI6IjFlM2U0MTU0LWJiNDMtNDY0MS04ZGFmLTIxNjRlOTFmMTU4YiIsIm5iZiI6MTUzMzkyMTE4Mywic3ViIjoiUmp1YURzdi0iLCJ0eXAiOiJhY2Nlc3MifQ.SqE48FXKhN7Y7aAsipFwvIAqetyhVJGwARMEwNwCXSK-QnXZdu3f2xkHDrXBsf1L1IlhTwg78Y-RiKrgepV34Q" -X POST http://localhost:4002/bye + Note: Unnecessary use of -X or --request, POST is already inferred. + * Trying ::1... + * TCP_NODELAY set + * Connection failed + * connect to ::1 port 4002 failed: Connection refused * Trying 127.0.0.1... * TCP_NODELAY set * Connected to localhost (127.0.0.1) port 4002 (#0) @@ -193,12 +223,13 @@ defmodule POABackend.CustomHandler.REST do > User-Agent: curl/7.53.1 > Accept: */* > Content-Type: application/json - > Content-Length: 37 + > Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJwb2FfYmFja2VuZCIsImV4cCI6MTUzMzkyNDc4NCwiaWF0IjoxNTMzOTIxMTg0LCJpc3MiOiJwb2FfYmFja2VuZCIsImp0aSI6IjFlM2U0MTU0LWJiNDMtNDY0MS04ZGFmLTIxNjRlOTFmMTU4YiIsIm5iZiI6MTUzMzkyMTE4Mywic3ViIjoiUmp1YURzdi0iLCJ0eXAiOiJhY2Nlc3MifQ.SqE48FXKhN7Y7aAsipFwvIAqetyhVJGwARMEwNwCXSK-QnXZdu3f2xkHDrXBsf1L1IlhTwg78Y-RiKrgepV34Q + > Content-Length: 16 > - * upload completely sent off: 37 out of 37 bytes + * upload completely sent off: 16 out of 16 bytes < HTTP/1.1 200 OK < server: Cowboy - < date: Fri, 08 Jun 2018 15:49:05 GMT + < date: Fri, 10 Aug 2018 17:19:24 GMT < content-length: 20 < cache-control: max-age=0, private, must-revalidate < content-type: application/json; charset=utf-8 diff --git a/lib/poa_backend/protocol.ex b/lib/poa_backend/protocol.ex index 0c1be56..ed8258f 100644 --- a/lib/poa_backend/protocol.ex +++ b/lib/poa_backend/protocol.ex @@ -11,11 +11,32 @@ defmodule POABackend.Protocol do Only those calls are allowed: - * session (*not implemented*) - In future in order to add authentication / authorization + * session - In order to generate a token/session for authentication/authorization * ping - Ping message * data - Specific message for a given receiver. It can be a metric itself or something else * bye - Message sent when the Agent wants to close the communication explicitly + #### session call + + This call is for generate a valid token/session in order to get access to the other calls + + abstract request: + + ```json + { + user: String() # user name + password: String() + } + + response: + + ```json + + { + token: String() # this token must be attached to each call + } + ``` + #### ping call abstract request: @@ -23,7 +44,7 @@ defmodule POABackend.Protocol do ```json { id: String() # agent id - secret: String() # secret string for authentication/authorisation + token: String() # generated with a valid user/password calling the _session call_ } ``` @@ -44,7 +65,7 @@ defmodule POABackend.Protocol do ```json { id: String() # agent id - secret: String() # secret string for authentication/authorisation + token: String() # generated with a valid user/password calling the _session call_ type: String() # data type (for now only ethereum_metrics) data: Object() # metric data itself } @@ -67,7 +88,7 @@ defmodule POABackend.Protocol do ```json { id: String() # agent id - secret: String() # secret string for authentication/authorisation + token: String() # generated with a valid user/password calling the _session call_ } ``` diff --git a/mix.exs b/mix.exs index 64908e5..b5eb162 100644 --- a/mix.exs +++ b/mix.exs @@ -62,10 +62,18 @@ defmodule POABackend.MixProject do defp docs do [ + main: POABackend, source_ref: "v#{@version}", source_url: "https://github.com/poanetwork/poa-netstats-wharehouse", extras: ["pages/initial_architecture.md": [filename: "initial_architecture", title: "Initial Architecture"]], groups_for_modules: [ + "POA Auth": [ + POABackend.Auth.REST, + POABackend.Auth, + POABackend.Auth.Guardian.Plug, + POABackend.Auth.Models.Token, + POABackend.Auth.Models.User + ], "POA Protocol": [ POABackend.Protocol, POABackend.Protocol.Message, diff --git a/test/auth/api_test.exs b/test/auth/api_test.exs index 94d65d0..f72eadf 100644 --- a/test/auth/api_test.exs +++ b/test/auth/api_test.exs @@ -286,7 +286,7 @@ defmodule Auth.APITest do end # ---------------------------------------- - # /blackmail/user Endpoint Tests + # /blacklist/user Endpoint Tests # ---------------------------------------- test "Ban a user correctly [JSON]" do @@ -435,7 +435,7 @@ defmodule Auth.APITest do end # ---------------------------------------- - # /blackmail/token Endpoint Tests + # /blacklist/token Endpoint Tests # ---------------------------------------- test "Ban a token correctly [JSON]" do