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

Note

  • It is not possible to remove the user that is currently logged in to the system.

  • Only Admin can delete the user.

  • Super Admin cannot be deleted.

Example

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