SPC-SERVER - Security and Privacy Component
The SPC-SERVER secures REST API, handles authentication (also 2FA) and is optimized for distributed web-systems. This project is an application based on Angular Fullstack Usually other web components provides a Login UI, like the SPC-WEB-CLIENT for authenticating users. The Server based on PassportJS and makes use of different authentication strategies:
- Username / Password
- Google Sign-In
- LDAP Login
- Second Factor with TOTP
Once the setup configurations has been made, a user is able to login with a second factor (TOTP - Google Authenticator). After successfully logging in with their credentials, the web client (SPC-WEB-CLIENT) will store an access token (in the web browser within a cookie). For further access this token wil be transmitted with the requests. Components use this token to authenticate and authorise the user by calling the SPC’s Security API. For this the components have to transmit an API Key for every call to the SPC. The response contains the logged in status of the user and also data associated with the user. This data is comprised of two parts:
- Public data that all components may access, containing a unique ID, and data like the user’s name
- Private data, which is data only visible in the context of the calling component
There is also another component written in JAVA, the SPC-JAVA-CLIENT for communicating with the SPC-SERVER.
Getting Started
To get you started you can simply clone the SPC-SERVER repository install [node][node] and the dependencies:
Prerequisites
MongoDB - Download and Install MongoDB -
you'll need mongoDB to be installed and have the mongod process running.
You need git to clone the spc-server repository. You can get git from http://git-scm.com/.
There are also a number of node.js tools to initialize and test SPC-SERVER. You must have node.js and its package manager (npm) installed. You can get them from http://nodejs.org/. The Build Framework Grunt manages the initialization and testing of the app.
npm install -g grunt-cli
Clone SPC-SERVER
Clone the spc-server repository using [git][git]:
git clone https://github.com/tobistw/spc-server.git
cd spc-server
If you just want to start a new project without the SPC-SERVER commit history then you can do:
git clone --depth=1 https://github.com/tobistw/spc-server.git <your-project-name>
The depth=1
tells git to only pull down one commit worth of historical data.
Install Dependencies
Install the dependecies with via npm
, the [node package manager][npm].
npm install
node_modules
- contains the npm packages for the tools
Configuring for SPC-SERVER
There is a config directory including following files:
environment
- this directory contains general options and specific options for development, production and test environmentaudit
- options for logging tool winstonexpress
- configuration for express framework and possible options for the environment.local.env.sample
- use this file to define local environment variables and to put secrets (Google Secret etc). Should not be version controlled.seed
- for populating the DB with sample data.
First Step
Rename the local.env.sample
to local.env
and define the values for your environment. If you want to use the Google Login
you must have a Google Account for accessing the Google Developers Console and creating a new project.
Furthermore you have to set the callback url for the client. You also define your project name and id in this file.
Second Step
The index
file in the environment directory defines an 'all' config object of default properties that will be included in all environments.
These default properties are used by among other things like in the express
file. Set the seedDB value to true
for populating the DB.
If you running a LDAP-Server you have to define the ldapServer
object. There is already a configuration for an example LDAP Server.
Third Step
There a different files for each environment, i. e. development to define specific configuration. In the ´./server/app.js´ file
the first line process.env.NODE_ENV = process.env.NODE_ENV || 'development';
tells the app which environment it is in.
Fourth Step
If you like to enable two factor authentication for the user you have to set the value for secondFactor
to true
.
Simply use the seed
file to configure the users option.
Running SPC-SERVER
You can run the app simply by typing grunt serve
in the console. There are also other tasks like grunt test
that will
run the unit tests.
Testing
There is an API Access Test including a number of unit tests.
Running Unit Tests
The easiest way to run the unit tests is to use the grunt task:
grunt test
Extending the SPC-SERVER
Note that this application is only a prototype and should not be used in productive environment. There are still some missing functionalities and security issues, see the 'TODO' section.
Adding new Projects
Creating a new project means adding a new endpoint in your project. Open the directory ./server/api/
and you will recognize
two folders the auth
folder for managing general authentication and the crema
folder, this is an example project.
The easiest way is to copy and paste the index
file and create a new directory naming it with your project. Dont forget to
update the project name environment variable in auth.isAuthenticatedForProject(process.env.PROJECT_NAME_YOUR_PROJECT)
.
After this add a new endpoint in the ./server/api/index
file, i. e.
router.use('/auth/' + process.env.PROJECT_YOUR_ID, require('./project/index'));
New Authentication Strategies
If you like to have more authentication methods like login with OpenID you have to edit following files:
./server/api/auth/auth.service
- define a new function using a passport strategy./server/api/auth/passport
- define your passport configuration./server/api/auth/index
- add a new endpoint with the new authentication strategy
Security requirements in productive environment
Ensuring Endpoint Authenticity
- Prevent man-in-the-middle attacks
- Use of TLS
- Client must validate server´s TLS certificate
Encrypting Identity Information
- Use of JSON Web Token (ID Token) with public/private Keypair
Cross Site Request Forgery (XSRF)
- State Parameter in the response for the Client
- Hash of the session cookie or random value that the client can verify
TODO
- asymmetric encryption of tokens
- storing sensitive information (public and private payload) in an ID-Token (JWT)
- OpenID Strategy
- FIDO - Ready (new Strategy for Passport)
- Management UI - managing tokens, clients and users