Authentication Service for the SCEPTER project
We recommend forking this repository.
If you are using the SCEPTER framework you can install this service using the following command from your project folder:
node bin/scepter.js service:add <your-fork-repo> [email protected]:source4societyorg/SCEPTER-AuthenticationService.git AuthenticationService
This will clone the service into your services folder as a submodule, and run yarn install
as well as yarn test
. We are currently working on initialization scripts that will help setup configuration files after running this command.
Alternatively if you are running this as a standalone service, you can simply git clone
this repository or it's fork, and setup the configuration files locally.
This service expects SCEPTER credentials.json, parameters.json, and services.json configuration files within the root service directory. If you are using SCEPTER then these files will automatically be copied to the directory when executing the service:deploy
command for this service. If you are using this service as a standalone service, then you must add these files to the project manually.
Currently the library only supports the aws
provider with a dynamoDB
backend, but we hope to support others in the future.
Your configuration should have the jwtKeySecret
, tokenDuration
, and userTable
properties in addition to the standard provider configuration. The initialize.js
script in the config directory can generate your jwtKeySecret and place these in your credentials.json for you if you are using SCEPTER. The rest must be entered into the parameters.json file manually. Here is an example entry:
"environments": {
"development": {
"userTable":"users",
"tokenDuration":"2h"
}
This service currently relies on AWS DynamoDB to store the user records. Future releases will abstract this dependence away and allow for greater flexibility with regards to how the data can be stored and accessed.
There are two types of records to be stored in the user table for this service to work. They must each have recordType
properties of user-name
and user-data
. The user-name
record consist of two properties, a recordId
used for enforcing a unique constraint for the username lookup, and a userName
property that matches the recordId. This record also has a userId
property which is the unique recordId
of the user-data
record (uuid recommended). The user-data
record will also contain a copy of the userName
property so that they can both be pulled together via a DynamoDB query. This record should also contain the passwordHash
property which consists of a bcrypt hash of the users password. These two records are combined and stored within the users JWT that is created by the service upon authentication. Optionally, an enabled
property can be created on the user-name
record. If set to false, the username will not be authenticated.
See SCEPTER-command-service and Serverless.com for information on how to deploy services to various cloud providers.
This service is intended to be used to authenticate user credentials and return a json web token signed by the service that can be used for stateless authentication.
A payload is passed to the service containing the users username and password credentials. If the username exists, the service will attempt to compare the password with the stored password hash and validate if there is a match or not. If the password hash matches, then the response consists of a newly minted and signed json web token with the users id, username, and roles stored within the token. Furthermore, the expiration time for the token is set and configurable using the tokenDuration
key in credentials.json. See Json Web Tokens RFC 7519 for information about JWT's. A mismatch of either the username or the password will return an error message with a false status
key.
Two tables are used in DynamoDb to ensure a unique constraint on the username and userId properties.
Data passed to the service should resemble the following format:
{
"username": "someuser",
"password": "theirpass"
}
If you are using SCEPTER-GatewayService for your API Gateway, this would go in the payload
key of your gateway body. A successful authentication result is as follows:
{
"status": true,
"result": {
"jwt": "eyJhbGciOiJIUzI1NiIsnR5cCI6IkpXVCJ9.eyJwYXNzd29yZEhhc2giOiIkMmEkMDgkb3Bsa28yZW9FQTFLNTZZa2lkQzJ6LkRReHI0YnFjR201V3dIcHh4MW0va3J1Li9UVFhFLjYiLCJ1c2VybmFtZSI6Im5yYWNhZG1pbiIsInJvbGVzIjpbIk5SQUNfQURNSU4iXSwidXNlcklkIjoiMzRjMmJkZDItYTg2My00NDg5LTkyNzQtZmY4Y2JkYjkxZGM2IiwiaWF0IjoxNTEyOTkxNjY2LCJleHAiOjE1MTU1ODM2NjZ9.QDDvZXqO77BvHwX80tdZn4o5IHlS9FD3BwxYqbpxrw"
}
}
To run tests and eslint, run yarn test
.
Before running tests, you need to be sure that you have a test
environment and parameters credential configuration set created. These are provided by default in the test folder and are automaticaly referenced by the test library.