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

Response:

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"}

Create User Endpoint

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

POST /user

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

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"}

List User Endpoint

This Endpoint is needed in order to list the users in the system. Only Admin people can do that.

GET /user

Response

Example:

curl -i -X GET -H "Authorization: Basic YWRtaW4xOnBhc3N3b3JkMTIzNDU2Nzg=" https://localhost:4003/user --insecure

HTTP/1.1 200 OK
server: Cowboy
date: Mon, 03 Sep 2018 16:02:29 GMT
content-length: 153
cache-control: max-age=0, private, must-revalidate

[{"user":"HeeV-EmU","created_at":"2018-09-03T16:02:25.210308","active":true},{"user":"W75AcY8Z","created_at":"2018-09-03T16:02:13.763003","active":true}]

The JSON format for a user is:

{
  "user":"Username",
  "active":true, # active means it is not banned
  "created_at":"2018-09-03T16:02:25.210308"
}

Delete User Endpoint

This Endpoint is needed in order to delete a user from the system.

DELETE /user/:username

Response

Example:

curl -i -X DELETE -H "Authorization: Basic YWRtaW4xOnBhc3N3b3JkMTIzNDU2Nzg=" https://localhost:4003/user/4uVIqWSf --insecure

HTTP/1.1 204 No Content
server: Cowboy
date: Tue, 04 Sep 2018 13:49:45 GMT
content-length: 0
cache-control: max-age=0, private, must-revalidate

Update User Endpoint

This Endpoint is needed in order to update a user. Currently only the active property can be updated. If a user is set to active: false means it was banned. We can use this enpoint in order to ban or unban users too.

PATCH /user/:username

Response

Example:

curl -i -X PATCH -H "Authorization: Basic YWRtaW4xOnBhc3N3b3JkMTIzNDU2Nzg=" -H "Content-Type: application/json" -d '{"active":false}' https://localhost:4003/user/cZFxFfNT --insecure

HTTP/1.1 204 No Content
server: Cowboy
date: Wed, 05 Sep 2018 13:38:32 GMT
content-length: 0
cache-control: max-age=0, private, must-revalidate

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

Response

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

Response

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