<img align="right" src="img/beame.png">

# Beame Gatekeeper
[![Build Status](https://build.beame.io/buildStatus/icon?job=beame-gatekeeper/master)](https://build.beame.io/job/beame-gatekeeper/job/master/) [![npm version](https://badge.fury.io/js/beame-gatekeeper.svg)](https://www.npmjs.com/package/beame-gatekeeper) [![HitCount](http://hits.dwyl.io/beameio/beame-gatekeeper.svg)](https://github.com/beameio/beame-gatekeeper)

## What is Beame Gatekeeper?

Beame-Gatekeeper is a framework that provides services/tools:
* To create and manage X.509 digital certificates in public domain
* HTTPS tunnels to expose applications running on local network to global internet 
* Crypto library to create/manage keys, encrypt/decrypt sign/verify data, create/validate authentication tokens
* X.509 based identity manager for custom MFA
* SSO SAML Identity Provider (IDP)
* User management (invite/create/delete user) with trust-groups capability
* Administrating tools for full Gatekeeper managemnt (html-based console)

Here's a typical usecase for the Gatekeeper (Web-camera connected on local network is accessed from arbitrary laptop through Browser, with mobile authentication & control):

![Use-case](https://github.com/beameio/beame-gatekeeper/raw/master/img/IoT.png)

How is it different? We created a new breed of ID - _cryptographic identity_ that lives on a mobile ([get Beame Authenticator to your iOS device](https://itunes.apple.com/il/app/beame-authenticator/id1214704177?mt=8)). Now it's easy to put a super-secure cryptographic identity on mobile and IoT devices. So the device can prove your identity by providing proof of possession of a secret key through the Gatekeeper framework. Keys created and stored on target. The Gatekeeper does not hold databases with sensitive data.

_Click on the link below, to see Beame Gatekeeper demo on Youtube_  
[![Alt Beame Gatekeeper demo #1](https://github.com/beameio/beame-gatekeeper/raw/master/img/GKdemo.png)](https://www.youtube.com/watch?v=K_XNFKzJV_M)

[More details (PDF)](doc/beame-gatekeeper.pdf) - The purpose of this paper is to describe the particular beame-gatekeeper use case as a tool for remote access to enterprise networks or IoT devices with mobile authentication. It provides an overview of possible product integration options. The document contains technical overview and description of provisioning and login processes.

[User guide (PDF)](doc/BeameGatekeeperManual.pdf) - how to operate the Gatekeeper.

Continue with instructions below, to get your own Gatekeeper. Install it as a system service to keep your applications accessible. Or, if you want to just try it out first, install it as a standalone application. Go with the guide and in fast and easy process your Gatekeeper will be up and running.  

## Installing Beame Gatekeeper

* [Installing Beame Gatekeeper on Linux, Mac OS or Raspberry Pi](doc/install-unix.md)
* [Installing Beame Gatekeeper on Windows](doc/install-windows.md)

## Managing StrongSwan VPN using Beame Gatekeeper

[Managing StrongSwan VPN using Beame Gatekeeper](doc/strongswan.md)

## What to do next?

Please read [User guide (PDF)](https://www.beame.io/pdf/Beame+Gatekeeper+Technical+Presentation.pdf). It describes what and how you can do with Beame-Gatekeeper.


## Beame Gatekeeper environment variables

* `BEAME_AUTH_SERVER_PORT` - auth server local port, default 65000
* `BEAME_BASE_URL`
* `BEAME_DATA_FOLDER`  - name of beame-gatekeeper data folder , default .beame_data
* `BEAME_DISABLE_DEMO_SERVERS` - disable demo apps on server start, default false
* `BEAME_DISABLE_SNS_VALIDATION` - set to `INSECURE` to skip SNS messages validation.
* `BEAME_EMAIL_URL`
* `BEAME_ENV` - Defines the environment profile to run in: `prod` or `dev`
* `BEAME_EXTERNAL_MATCHING_FQDN`
* `BEAME_FQDN_PATTERN`
* `BEAME_GATEKEEPER_DIR` -  defines the base directory relative to which beame-gatekeeper files should be stored, default `os.homedir()`
* `BEAME_LOAD_BALANCER_URL` - Load balancer url
* `BEAME_LOGIN_URL`
* `BEAME_LOG_LEVEL` - Can be set to DEBUG or other beame log levels
* `BEAME_LOG_TO_FILE` - Activates log console to file. Can be true or false. 
* `BEAME_OCSP_CACHE_PERIOD` - OCSP result cashing period , default 24 hours
* `BEAME_SEND_SMS` - When set to `0`, disables sending SMS. Useful for debugging SMS invitation flow.
* `BEAME_SERVER_FOLDER`  - name of beame-gatekeeper config folder , default .beame_server
* `BEAME_UNIVERSAL_LINK_URL`
* `BEAME_OIDC_BLOCK_SOCKETIO` - block all socket.io connections as if the client is not authorized. Useful for debugging.
* `BEAME_AUTO_RENEWER` - When set to `0`, disables the start of the auto renewer job.

* `DEBUG=*` - Show all debug from node
* `NODE_TLS_REJECT_UNAUTHORIZED=0` - disables all tls checks (usefull in some proxy scenarios). If we only need it for one app, then we should configure that one app with the isSecure = false instead.


## Developer notes
* xml-encryption is not a dependency of the beame-gatekeeper, but of samlp. Since samlp is not adding it as its own dependency this was temporarely added to package.json of beame-gatekeeper. Remove it or find a better way to handle this in the future
* for applications that are not hosted on the root of the service url ex: https://site.company.com/folder/page.html?param=value, the service needs to be configured as following in the gatekeeper https://site.company.com***/folder/page.html?param=value . The *** will let the app know that is the base url so that proxying can be applied correctly.
* Services "Secure" option means disable TLS check

## Flows

[Flows](flows.md)
