REST API Users & Authentication¶

FogLAMP supports a number of different authentication schemes for use of the REST API

Unauthenticated or Optional authentication. There is no requirement for any authentication to occur with the FogLAMP system to use the API. A user may authenticate if they desire, but it is not required.

Username/Password authentication. Authentication is required and the user chooses to authenticate using a username and password.

Certificate based authentication. Authentication is required and the user presents a token issued using a certificate in order to authenticate.

Authentication API¶

Login¶

POST /foglamp/login - Create a login session token that can be used for future calls to the API

Request Payload

If the user is connecting with a user name and a password then a JSON structure should be passed as the payload providing the following key/value pairs.

Key Name	Type	Description	Example
username	string	The username of the user attempting to login	admin
password	string	The plain text password of the user attempting to login	foglamp

Response Payload

The response payload is an authentication token that should be included in all future calls to the API. This token will be included in the header of the subsequent requests as the value of the property authorization.

Example

Assuming the authentication provider is a username and password provider.

curl -X POST http://localhost:8081/foglamp/login -d'
{
  "username" : "admin",
  "password" : "foglamp"
}'

Would return an authentication token

{
  "message": "Logged in successfully",
  "uid": 1,
  "token": "********************",
  "admin": true
}

Subsequent calls should carry an HTTP header with the authorization token given in this response.

curl -H "authorization: <token>" http://localhost:8081/foglamp/ping

Alternatively a certificate based authentication can be used with the user presenting a certificate instead of the JSON payload shown above to the /foglamp/login endpoint.

curl -T user.cert -X POST http://localhost:8081/foglamp/login --insecure

The payload returned is the same as for username and password based authentication.

Note

The examples above have been shown using HTTP as the transport, however if authentication is in use then it would normally be expected to use HTTPS to encrypt the communication.

Logout¶

PUT /foglamp/logout - Terminate the current login session and invalidate the authentication token

Ends to login session for the current user and invalidates the token given in the header.

PUT /foglamp/{user_id}/logout - Terminate the login session for user’s all active sessions.

The administrator may terminate the login session of another user.

curl -H "authorization: <token>" -X PUT http://localhost:8081/foglamp/{user_id}/logout

Users¶

FogLAMP supports two levels of user, administration users and normal users. A set of API calls exists to allow users to be created, queried, modified and destroyed.

Add User¶

POST /foglamp/admin/user - add a new user to FogLAMP’s user database

Note

Only admin users are able to create other users.

Request Payload

A JSON document which describes the user to add.

Key Name	Type	Description	Example
username	string	The username of the new user to add. It is a required field.	david
password	string	The password to assign to the new user. It is a required field.	Inv1nc!ble
access_method	string	Access of a user. It is an optional field.	Possible values are cert, any, cert.
real_name	string	The real name of the user. This is used for display purposes only. It is an optional field.	David Brent
role_id	integer	The role id of the new user. It is an optional field.	1 for Admin user and 2 for normal user. If not given it will be treated as normal user.
description	string	Description of the user. It is an optional field.	1 for Admin and 2 for normal user. If not given it will be treated as normal user.

Response Payload

The response payload is a JSON document containing the full details of the newly created user.

Errors

The following error responses may be returned

HTTP Code	Reason
400	Incomplete or badly formed request payload
403	A user without admin permissions tried to add a new user
409	The username is already in use

Example

curl -H "authorization: <token>" -X POST -d '{"username": "david", "password": "Inv1nc!ble", "role_id": 1, "real_name": "David Brent"}' http://localhost:8081/foglamp/admin/user

Get All Users¶

GET /foglamp/user - Retrieve data on all users

Response Payload

A JSON document which all users in a JSON array.

JSON Key	Type	Description	Example
.users[].userName	string	The username of the user	david
.users[].roleId	integer	The permissions level of the user	1
.users[].realName	string	The real name of the user. This is used for display purposes only.	David Brent
.users[].description	string	The description of the user.	This is an admin user.

Note

This payload does not include the password of the user.

Example

curl -H "authorization: <token>" -X GET http://localhost:8081/foglamp/user

Returns the response payload

{
    "users" : [
                {
                   "userId"       : 1,
                   "userName"     : "admin",
                   "roleId"       : 1,
                   "accessMethod" : "any",
                   "realName"     : "Admin user",
                   "description"  : "admin user"
                },
                {
                   "userId"       : 2,
                   "userName"     : "david",
                   "realName"     : "David Brent",
                   "accessMethod" : "any",
                   "roleId"       : 1,
                   "description"  : "OT Department Head"
                },
                {
                   "userId"       : 3,
                   "userName"     : "paul",
                   "realName"     : "Paul Smith"
                   "roleId"       : 2,
                   "accessMethod" : "any",
                   "description"  : "OT Supervisor"
                }
              ]
}

Update User¶

PUT /foglamp/user - Allows a user to update their own user information

Request Payload

A JSON document which describes the updates to the user record.

Key Name	string	description	Example
real_name	string	The real name of the user. This is used for display purposes only.	David Brent

Note

A user can only update their own real name, other information must be updated by an admin user.

Response Payload

The response payload is a JSON document containing a message as to the success of the operation.

Errors

The following error responses may be returned

HTTP Code	Reason
400	Incomplete or badly formed request payload

Example

curl -H "authorization: <token>" -X PUT /foglamp/user -d '{"real_name": "Dave Brent"}'

Change Password¶

PUT /foglamp/user/{userid}/password - change the password for the current user

Request Payload

A JSON document that contains the old and new passwords.

Key Name	string	description	Example
current_password	string	The current password of the user	Inv1nc!ble
new_password	string	The new password of the user	F0gl!mp1

Response Payload

A message as to the success of the operation

Example

curl -X PUT -d '{"current_password": "Inv1nc!ble", "new_password": "F0gl!mp1"}' http://localhost:8081/foglamp/user/{user_id}/password

Admin Update User¶

PUT /foglamp/admin/user - An admin user can update any user’s information

Request Payload

A JSON document which describes the updates to the user record.

Name	Type	Description	Example
description	string	The description of a user	david
access_method	string	The permissions that new user should be given	Possible values are cert, any, cert.
real_name	string	The real name of the user. This is used for display purposes only.	David Brent

Response Payload

The response payload is a JSON document containing the user information.

Errors

The following error responses may be returned

HTTP Code	Reason
400	Incomplete or badly formed request payload
403	A user without admin permissions tried to add a new user
409	The username is already in use

Example

curl -H "authorization: <token>" -X PUT -d '{"description": "OT Department Head", "real_name": "David Brent", "access_method": "pwd"}' http://localhost:8081/foglamp/admin/{user_id}

Delete User¶

DELETE /foglamp/admin/user/{userID}/delete - delete a user

The delete user call can only be made by users with administrator privileges. If a user that is currently logged in is removed then that user will be forcibly logged out of the system.

Note

The user with the user name admin can not be removed from the system.

Example

curl -H "authorization: <token>" -X DELETE  http://localhost:8081/foglamp/admin/{user_id}/delete