Harbourmaster

About

The Harbourmaster application is the backbone of the Harbourmaster SSO. It provides the API which powers all other applications.
https://hub.docker.com/r/valiton/harbourmaster/

Its main API is the REST API, which contains a full documentation with Swagger: http://YOUR_HARBOURMASTER_URL/docs

As well as the Rest API, it provides a change notification mechanism that allows notifications to be received for example, when a user changes their profile data (not included in the Freemium version).

The Harbourmaster stores data in a MongoDB.

Modular Architecture

The Harbourmaster comprises a core module and a couple of feature extending modules listed. Not all modules are include in the Freemium version.

License

The Harbourmaster Freemium is licensed under the attached LICENSE.

To start the Harbourmaster you need to accept the license by passing the LICENSE=accept, to display the license pass LICENSE=view

LICENSE=<accept|view>

Simple command to view just the license and dont run all the containers

docker run -e LICENSE=view valiton/harbourmaster

Configuration

The necessary configuration of the Harbourmaster is defined with environment variables.

LICENSE=<accept|view>

REDIS_PORT_6379_TCP_ADDR=<ip of redis>  #compatible with docker link redis
REDIS_PORT_6379_TCP_PORT=<prot of redis> #compatible with docker link redis

MONGO_PORT_27017_TCP_ADDR=<ip of mongodb> #compatible with docker link mongo
MONGO_PORT_27017_TCP_PORT=<prot of mongodb> #compatible with docker link mongo 


# used for seed script run, shared values with usermanger 
HARBOURMASTER_TENANT=<teante name > e.g. thunder
USERMANAGER_HMS_USER_KEY=<usermanager key| 20 char hex format> e.g.  32be04fb9495229f3e4f
USERMANAGER_HMS_USER_SECRET_KEY=<usermanager secret key random string> e.g. 58c94af9f955eebebaf81195d57f774fe7a9d834efd519c8588d184914ff

Docker run

Start a mongodb and redis as a container:

docker run -d --name=mongo mongo:3.2
docker run -d --name=redis redis

Start the Harbourmaster server:

docker run --name=thunder-harbourmaster -it -e LICENSE=accept --link mongo:mongo --link redis:redis valiton/harbourmaster

Seed the mongodb with an initial data set; this is necessary because all API endpoints need a logged in user. The seedscript creates the initial user.

docker exec -it thunder-harbourmaster bash -c "node /app/scripts/seed-create-thunder-tenant.js"

Backup

The Quick Start Guide repository contains a backup script which can be used as a starting point to create an automated backup process for the MongoDB. It is recommended to use a Cron job to automate and schedule the backup prodecure.

API

The Harbourmaster provides a HTTP REST API. Its main API is the REST API, which is full documents with swagger. http://YOUR_HARBOURMASTER_URL/docs

The basic API structure example:

<server> domain where the harbourmaster is deployed to.
<TENANT> placeholder for the tenant to be used.
<resource> placeholder for the resource to be used.
<nestedResource> placeholder for a nested resource.

http://<server>/v1/<TENANT>/<resource>
http://<server>/v1/<TENANT>/<resource>/<ID>
http://<server>/v1/<TENANT>/<resource>/<ID>/<nestedResource>

API responses

Positive response

All positive responses have this general JSON structure:

{
 "status": 1,
 "responseCode":  <HTTP_RESPONSE_CODE>,
 "data": { <DATA> }
}

Error response

All error responses have this general JSON structure:

{
 "status": 0,
 "message": "<MESSAGE>",
 "responseCode": <HTTP_RESPONSE_CODE>
}

Policies

Policies in the Harbourmaster are a very flexible way to grant access to resources in the Harbourmaster. The policy system is loosely inspired by the Amazon AWS IAM policies.

All Harbourmaster API endpoints verify access based on the policy of the requesting user.

The API endpoint is represented as action and the resource, depending on the context of the created/updated/shown/deleted data.

The actions and resources involved in the Harbourmaster API are listed in the swagger documentation.

A Policy consists of one or many statements, which are structured as follows:

• Effect: can be Allow or Deny
• Tenant: the tenant where the policy should apply; gets converted in a regular expression
• Action: represents an API endpoint action; gets converted in a regular expression
• Resource: the resource which is affected by the action; get converted in a regular expression
  • Special Resource [currentUser] access is only granted to the resource owned by the accessing user

Policy Example

Full access to all actions on all resource in all tenants:

{"Statement":[
 {"Tenant":"*", "Effect":"Allow","Action":"*","Resource":"*"}
]}

currentUser User can read and edit his own data

{ "Statement": [
 { "Tenant": "thunder", "Effect": "Allow", "Action": "hms:login", "Resource": "[currentUser]" },
 { "Tenant": "thunder", "Effect": "Allow", "Action": "hms:updateUserPassword", "Resource": "[currentUser]" },
 { "Tenant": "thunder", "Effect": "Allow", "Action": "hms:getUserServices", "Resource": "[currentUser]" },
 { "Tenant": "thunder", "Effect": "Allow", "Action": "hms:getUser", "Resource": "[currentUser]" },
 { "Tenant": "thunder", "Effect": "Allow", "Action": "hms:updateUser", "Resource": "[currentUser]" },
 { "Tenant": "thunder", "Effect": "Allow", "Action": "hms:listUserEntitlements", "Resource": "[currentUser]" },
 { "Tenant": "thunder", "Effect": "Allow", "Action": "hms:listAllowedTenants", "Resource": "[currentUser]" }
]}