Authorizations server

This application is simple authorizations server written in node.js. It utilizes node-oidc-provider package under the hood, which creates oauth service to log in. This project is written in DDD and uses extremally strict eslint, which will force you to write code with my style. If you are planning on working with this app, please make sure if current eslint rules are good for you.

TLDR: 0. Key packages

1. How to install
2. How to build
3. Useful information
4. Docs
5. Examples
6. Tips

0. Key packages

• Express - server
• Helmet - security
• Swagger - docs
• Node-oidc - oauth service
• Mongo - database
• Redis - cache

1. How to start

Install dependencies

npm install / yarn

Prepare environment

This project uses 3 config files, which are located in /config folder. This project includes exampleConfig, which you can replicate

• devConfig.json
• prodConfig.json
• testConfig.json

DevConfig will be used, if you run your application with NODE_ENV=development. This config should be used while working on this application

ProdConfig will be used, if you run your application with NODE_ENV=production. This should be used in production env

TestConfig will be used, if you run your application on dev servers. This config only differs from production, that in code it will log debug logs and should connect to dev database.

Example dev config:

{
  "port": 5003,
  "mongoURL": "mongodb://login:[email protected]:27017",
  "redisURL": "redis://:password@localhost:6379",
  "myAddress": "http://localhost:5003",
  "corsOrigin": ["http://localhost:5004"],
  "frontUrl": "http://localhost:3005",
  "session": {
    "secret": "secret",
    "secured": true
  }
}

In this example, I am running frontend client on 3005, backend on 5004 and this server on 5003. Those adrees are used by helmet for security and cors related stuff. Make sure, that they are correct, otherwise login system might not work, or you'll have tons of cors related problems.

frontUrl is a frontend address, used to correctly move users around

Initialize database and migrate data

This project uses mongoDB, which will create databases by itself, but in order to start, you need basic data in mentioned database. While running dockerized version of this app for the first time. It will run migrations on its own. If you are planning on using this project as is, you need to migrate data on your own. Make sure that config files are correct and run:

npm run migrate:dev / yarn migrate:dev

This will trigger migrations, which will create basic oidc client. This client will have basic password and example information. In order to make this application work, you need to edit those connections.

Default user is:

{
  "client_id": "oidcClient",
  "client_secret": "randomlyGeneratedPassword",
  "grant_types": [ "authorization_code", "refresh_token" ],
  "scope": "openid",
  "redirect_uris": [ "http://localhost/login" ],
  "post_logout_redirect_uris": [ "http://localhost" ]
}

I'll assume that you already know how oauth works. Make sure to change:

• client_secret = This is super basic password and this NEED to be replaced
• scope = Scope will only allow you to log in. Another scoped and grants are already included in claims. Make sure that you modify this to you needs
• redirect_uris = This is an url, where you want your user to be redirected after login in.
• post_logout_redirect_uris = This is an url, there you want your user to be redirected after logging out

Example data, that I use on dev server

{
  "client_id": "oidcClient",
  "client_secret": "randomlyGeneratedPassword",
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ],
  "scope": "openid profile",
  "redirect_uris": [
    "http://localhost:3005/login"
  ],
  "post_logout_redirect_uris": [
    "http://localhost:3005"
  ],
  "__v": 0
}

2. How to build

npm run build / yarn build

If you even encounter strange build behavior, tsconfig is set to create build with cache. Set option incremental in tsConfig to false

Makefile already includes command to build docker

3. Useful information

3.1 Logs folder

Linux

~/.cache/"package.json -> productName"/logs

Windows

~/AppData/Roaming/"package.json -> productName"/logs

3.2 Testing

All test currently are written using jest. You can run all tests or just type specific tests

Available targets

yarn tests = run all tests
yarn tests:e2e = run 'end to end' tests
yarn tests:db = run 'database' tests
yarn tests:unit = run 'unit' tests
yarn test:watch = run tests in 'watch' mode

At the time of writing, tons of tests are missing. This application does not include tests for logging in, because I do not have time to learn cypress/pupettier to test it, its not done. You can contribute to this project by adding your code. There should be open issue related to this.

3.4 Probes

This project includes readliness probe and liveness probe. They can be used by k8s, or other software. One probe creates files called .livenessProbe and updates it every 10 seconds, while other probe, utilizes /health route.

4. Docs

This project is using swagger docs. You can access them by route http://localhost:{port}/docs.

Additional docs can be found here

5. Examples

Your can find sample websites in /public. Their styling is extremally basic, but add data is included

6. Tips

• Keys rotation

Important

Keys rotation in this project should be run once per 2 weeks. AddPrivateKey method in redis is expecting only 2 keys in redis without TTL on them. Keep this in mind if you plan on rotating keys. Otherwise, just ignore this message