AUTHENTICATION MICROSERVICE
A microservice for session based authentication using JSON web tokens and a Neo4j database for session based management.
Intended usage
This service is intended to be accessed by the API to authenticate RESTless API requests. It is advised that you run this inside a docker container (or similar) to control access. Do not run this API publicly.
To effectively use this microservice, ensure your API does the following:
-
Call 'verify token' before allowing privileged API functionality
-
Check token expiry and 'PATCH' token if expiry date is nearing
-
Invalidate token when user logs out
User and session tracking
Users and sessions are stored in a Neo4j database. As of present, expired sessions are not automatically deleted from the database. Sessions have been abstracted from the API for simplicity. Tokens are seen as being either valid, invalid, blacklisted or expired.
Configuration
See private/config.js to configure JSON web token and Neo4j settings.
API FUNCTIONS
CREATE USER
Create a new user for authentication purposes.
Url
/auth/user
Method
POST
Parameters
Required
-
username=[String] -
password=[String]
Success responses
-
Status:
201 -
Message:
Success
Failure responses
-
Status:
400 -
Message:
Username validation failed
or
-
Status:
400 -
Message:
Password validation failed
or
-
Status:
409 -
Message:
User already exists
or
-
Status:
500 -
Message:
Unknown server error
CHANGE USER PASSWORD
Change the password of an existing user.
Url
/auth/user
Method
PATCH
Parameters
Required
-
username=[String] -
password=[String]
Success responses
-
Status:
201 -
Message:
Success
Failure responses
-
Status:
400 -
Message:
Username validation failed
or
-
Status:
400 -
Message:
Password validation failed
or
-
Status:
500 -
Message:
Unknown server error
CREATE TOKEN
Validate user credentials and return token.
Url
/auth
Method
POST
Parameters
Required
-
username=[String] -
password=[String]
Success Response
-
Status:
200 -
Message:
Success
Failure responses
-
Status:
400 -
Message:
User does not exist
or
-
Status:
401 -
Message:
Bad credentials
or
-
Status:
500 -
Message:
Unknown server error
VERIFY TOKEN
Verify token is valid and, if so, return username of token owner.
Url
/auth
Method
GET
Parameters
Required
token=[String]
Success Response
-
Status:
200 -
Username:
[username]
Failure responses
-
Status:
400 -
Message:
Token must be provided
or
-
Status:
400 -
Message:
Token is invalid
or
-
Status:
401 -
Message:
Token is expired
or
-
Status:
401 -
Message:
Token is blacklisted
or
-
Status:
500 -
Message:
Unknown server error
UPDATE TOKEN
Create new token from existing valid token
Url
/auth
Method
PATCH
Parameters
Required
token=[String]
Success Response
-
Status:
200 -
Token:
[token string]
Failure responses
-
Status:
400 -
Message:
Token must be provided
or
-
Status:
400 -
Message:
Token is invalid
or
-
Status:
401 -
Message:
Token is expired
or
-
Status:
401 -
Message:
Token is blacklisted
or
-
Status:
500 -
Message:
Unknown server error
INVALIDATE TOKEN
Blacklist token
Url
/auth
Method
DELETE
Parameters
Required
token=[String]
Success Response
-
Status:
200 -
Message:
Success
Failure responses
-
Status:
400 -
Message:
Token must be provided
or
-
Status:
400 -
Message:
Token is invalid
or
-
Status:
401 -
Message:
Token is expired
or
-
Status:
401 -
Message:
Token is blacklisted
or
-
Status:
500 -
Message:
Unknown server error