The purpose of ezBastion is to allow you to provide your administrative tasks via REST requests. Once the nodes have been installed, you will be able to import your system administrators’s scripts and assign them an HTTPS URL. To finish, declare the users and delegate the apis.

In general, to administer a system, you need 4 elements:

An administrator account.
The knowledge of the product.
Access rights and flow opening.
Consoles or administrative clients.

Just one question: Do you have any actions that could be delegated, if there were not the above points?

Overview¶

The purpose of ezBastion is to allow you to provide your administrative tasks via REST requests. Once the nodes have been installed, you will be able to import your system administrators’s scripts and assign them an HTTPS URL. To finish, declare the users and delegate the apis.

In general, to administer a system, you need 4 elements:

An administrator account.
The knowledge of the product.
Access rights and flow opening.
Consoles or administrative clients.

Just one question: Do you have any actions that could be delegated, if there were not the above points?

Architecture¶

ezBastion architecture is split in three zones, public, infrastructure and business and six microservices.

Public zone¶

This area is accessible by clients (users, services, computers) and must use corporate certificates. It is recommended to use multiple bastion (ezb_srv) and security token authority (ezb_sta) behind a load balancing system.

ezb_sta¶

Secure Token Authority (sta), provide authentication. It accept Basic, HTTP form and SSPI requests. Authenticated Accounts can be store in ezbastion database or use Microsoft accounts management (Builtin and domain accounts). It return a signed token in JWT format. This token is used as Bearer authentication, when login to admin console or request an api.

features:

authentication
bearer generator

ezb_srv¶

This node, called Bastion, is the front part of ezBastion architecture. It receive all clients requests and serves as api gateway. By default the listening don’t use TLS, you must put a load balancer in front of a pair of ezb_srv services (with ssl offload).

features:

authorization
cache (l1)
logging
workers’s load balancer

Infrastructure zone¶

This area is dedicated to ezBastion management team.

ezb_pki¶

This node provide ECDSA certificates, used by all ezBastion’s node to communicate.

feature:

Public key infrastructure

ezb_db¶

The database is used to store ezBastion configuration and clients access rules.

ezBastion configuration
API configuration
Access log

ezb_admin¶

All managment and configutaion, are made from a centralized web console.

Web console

business zone¶

The services running in this area are business dependent. You can provide API to different business line, using dedicated workers.

ezb_worker¶

The workers are the infrastructure backend. There are in charge to execute business tasks and return result to the bastion.

Task execution

ezb_vault¶

Some time we need user/password inside a script, and clear password is evil ! Vault node, will store key/value inside an AES dedicated DB.

key/value secure store

License¶

Download ezBastion free today and start deliver API in less a hour.

AGPL

GNU Affero General Public License v3.0

Permissions of this strongest copyleft license are conditioned on making available complete source code of licensed works and modifications, which include larger works using a licensed work, under the same license. Copyright and license notices must be preserved. Contributors provide an express grant of patent rights. When a modified version is used to provide a service over a network, the complete source code of the modified version must be made available.

Community¶

For students and Opensource projects, registration is not mandatory, you can use ezBastion freely. You can add a star on Github at ezBastion project, it help us to be more visible and it’s always a pleasure. If you want to participate (server hosting, advertising ), please register your Bastion.

Enterprise¶

Companies that want to use ezBastion, must register their deployments with a symbolic payment. This registration is valid for all updates of this bastion for one year.

ex: If two teams use ezBastion, but don’t want to share the admin console (the database). They must register both installations.

Setup mode¶

Simple architecture¶

Install all services on the same machine with a unique setup. Ideal for proof of concept. Download the “setup_win64.zip” package here https://github.com/ezBastion/ezBastion/releases/latest, unzip the setup file and follow the “next, next, next, finish” install. You need a windows server with 200Mo free space and 5 minutes.

Expert architecture¶

For stronger architecture, you can use as much server as you need. Use load balancing for microservices except workers that use their own system. Download latest binaries from https://github.com/ezBastion/ezBastion/releases/latest asset and follow the dedicated microservice documentation. You can use your own web servers, ezBastion just need a web server ready for static files like nginX, IIS or Apache.

Setup prerequisite¶

ezBastion try to be lighter as possible, the setup is fast and can be fully automatised. You need at least:

Any edition of Windows servers 64b.
~20Mo free space by service.
30Mo memory by service.
Admin right to install service.
30 minutes.

Network¶

Each ezBastion microservices are independent, you can put them on the same server (like for a POC) or split installation on different server for heavy-duty. You must choose a TCP port by service and open dedicated routes/port.

Your api customers need: - public -> ezb_sta - public -> ezb_srv

Your api administrators need: - ezb_admin -> ezb_db - ezb_admin -> ezb_sta - ezb_admin -> ezb_srv

microservices communication: - ezb_sta -> ezb_pki - ezb_sta -> ezb_db - ezb_srv -> ezb_pki - ezb_srv -> ezb_sta - ezb_srv -> ezb_db - ezb_srv -> ezb_wks - ezb_wks -> ezb_pki - ezb_db -> ezb_pki

SSL/TLS¶

Internal ezBastion communication use rest over tls 1.2 with ECDSA certificate. For external access, you must provide your own certificates for ezb_srv and ezb_sta.

PKI (ezb_pki)¶

The PKI (Public Key Infrastructure) is the first node to be installed. It will be in charge to create and deploy the ECDSA pair key, used by all ezBastion’s node to communicate. The certificates are used to sign JWT too.

1. Download ezb_pki from GitHub .¶

2. Open a admin command prompte, like CMD or Powershell.¶

3. Run ezb_pki.exe with init option.¶

name: This is the name used as Windows service and as certificates root name.
fullname:The Windows service description.
listen: The TCP/IP port used by ezb_pki to respond at nodes request. This port MUST BE reachable by all ezBastion’s node.

4. Install Windows service and start it.¶

ezb_pki install
ezb_pki start

security consideration¶

ezb_pki is an auto-enrolment system, if you do not add nodes, stop the service or don’t install it and use debug mode instead.
Protect cert folder.
Backup the private/public key.

DB (ezb_db)¶

This service manages communications to the database. It has two listeners, one for the admin console and one for the bastion (ezb_srv). The admin console listerner use JWT authentication while bastion’s one use PKI. You must declare the first (default) STA service and copy his public certificat, in the cert folder.

Windows¶

1. Download ezb_db from GitHub .¶

2. Open a admin command prompte, like CMD or Powershell.¶

3. Run ezb_db.exe with init option.¶

ezb_pki: tcp address and port of ezb_pki.
SAN: (Subject Alternative Name) Valid FQDN comma separated list for this certificate.

4. Edit config.json¶

Set service name and description.
Change if need, JWT & PKI port numbers.
Add the first STA address.

{
    "listenjwt": ":8443",
    "listenpki": ":8444",
    "privatekey": "cert/ezb_db.key",
    "publiccert": "cert/ezb_db.crt",
    "cacert": "cert/ca.crt",
    "db": "sqlite",
    "sqlite": {
        "dbpath": "db/ezb_db.db"
    },
    "servicename": "ezb_db",
    "servicefullname": "ezBastion Database",
    "loglevel": "warning",
    "ezb_pki": "ezb_pki.fqdn:5000",
    "san": [
        "mydbserver",
        "mydbserver.fqdn"
    ],
    "default_sta": "https://ezb_sta.fqdn:5001/token"
}

5. Install Windows service and start it.¶

ezb_db install
ezb_db start

STA (ezb_sta)¶

The STA (Secure Token Authority) is the second node to install. It create JWT token after account authentication. The JWT was signed with ECDSA key provided by ezb_pki, you must copy ezb_sta public key in all other nodes cert folder.

Windows¶

1. Download ezb_sta from GitHub ¶

2. Download latest 9.X node.js with npm from official node.js site ¶

3. Install nodes.js¶

4. Unzip ezb_sta package into the final Windows service folder¶

5. Open a admin command prompte, like CMD or Powershell.¶

6. From ezb_sta folder, install module with npm¶

PS E:\ezbastion\ezb_sta> npm install

7. Use ezb_sta.exe to generate config.json and certificat key pair¶

8. Edit config.json¶

externalkey: private PEM certificat filename, used for https access to this STA.
externalcert: public PEM certificat filename, used for https access to this STA.

{
    "externalkey": "",
    "externalcert": "",
    "privatekey": "ezb_sta.key",
    "publiccert": "ezb_sta.crt",
    "cacert": "ca.crt",
    "issuer": "ezb_sta",
    "audience": "ezBastion",
    "jwtttl": 1200,
    "ezbdb": "https://ezb_db.fqdn:8444/",
    "port": 5001
}

publiccert must be the same than issuer name.

9. Deploy certificat¶

Copy publiccert into ezb_db and ezb_srv cert folder.

10. Install windows service¶

PS E:\ezbastion\ezb_sta> node installService.js

Front server (ezb_srv)¶

this is the service that is responsible for routing and validating authorizations. It receive the requests and give them to the workers. It is advisable to have at least two servers behind a load balancer. You must copy all public certificat from STA services to cert folder.

Windows¶

1. Download ezb_srv from GitHub .¶

2. Open a admin command prompte, like CMD or Powershell.¶

3. Run ezb_srv.exe with init option.¶

ezb_pki: tpc address and port of ezb_pki.
SAN: (Subject Alternative Name) Valid FQDN comma separated list for this certificate.

4. Edit config.json¶

Set service name and description.
Change if need, listener address and port [1].
Add the first STA address.
Set cacheL1 duration in second [2].

{
    "listen": "0.0.0.0:5002",
    "ezb_db": "https://ezb_db.fqdn:8444/",
    "loglevel": "info",
    "cacheL1": 60,
    "privatekey": "cert/ezb_srv.key",
    "publiccert": "cert/ezb_srv.crt",
    "cacert": "cert/ca.crt",
    "servicename": "ezb_srv",
    "servicefullname": "ezBastion front",
    "ezb_pki": "ezb_pki.fqdn:5000",
    "san": [
        "mydbserver",
        "mydbserver.fqdn"
    ]
}

5. Install Windows service and start it.¶

ezb_srv install
ezb_srv start

[1]	:port for all interfaces, 1.2.3.4:port for IPv4, 0.0.0.0:port for all IPv4 interfaces, address.fqdn:port for DNS resolution.

[2]	The cacheL1 is the retention time for information comming from the database.

Worker (ezb_wks)¶

This service is in charge of executing your scripts. It must be started with an account with the appropriate rights. You must install as much workers as you have service account to use.

Windows¶

1. Download ezb_wks from GitHub .¶

2. Open a admin command prompte, like CMD or Powershell.¶

3. Run ezb_wks.exe with init option.¶

ezb_pki: tpc address and port of ezb_pki.
SAN: (Subject Alternative Name) Valid FQDN comma separated list for this certificate.

4. Edit config.json¶

Set service name and description.
Change if need, listener address and port [1].

{
    "listen": ":5003",
    "scriptpath": "E:\\ezbastion\\ezb_worker/script",
    "jobpath": "E:\\ezbastion\\ezb_worker/job",
    "loglevel": "info",
    "privatekey": "cert/ezb_wks.key",
    "publiccert": "cert/ezb_wks.crt",
    "cacert": "cert/ca.crt",
    "servicename": "ezb_wks",
    "servicefullname": "ezBastion worker",
    "ezb_pki": "ezb_pki.fqdn:5000",
    "san": [
        "mydbserver",
        "mydbserver.fqdn"
    ],
    "limitwarning": 20,
    "limitmax": 50
}

5. Install Windows service and start it.¶

ezb_wks install
ezb_wks start

[1]	:port for all interfaces, 1.2.3.4:port for IPv4, 0.0.0.0:port for all IPv4 interfaces, address.fqdn:port for DNS resolution.

Admin console (ezb_admin)¶

The ezBastion console is dedicated to API administrator. With this web console you can declare some account, api and link them together. A dashboard provide ezBastion statistic. ezb_admin is a pure javascript application, running 100% on the administrator browser (HTML5 mandatyory).

1. Http server¶

Any OS, any http server without module. Just prepare a server for static file.

2. Download¶

download ezb_admin from GitHub into your web server root folder.

3. Edit config.json¶

ezb_db: The ezb_db address with JWT/token port.
ezb_srv: The ezb_srv front address and port.

Don’t forget the trailing end slash.

{
    "ezb_db":"https://ezb_db.fqdn:8443/",
    "ezb_srv":"http://esb_srv.fqdn:5100/"
}

4. Connect¶

With your preferred HTML5 browser, login with admin/ezBastion as default account and start converting your scripts into API. Like ezb_DB use a internale certificat, you must install ezBastion root certificat (ca.crt) on all admin workstation.

Make your first api¶

Hello World step by step

Perequisite¶

ezBastion up and running
An automation powershell script
A youtube access to read this page.

Automation script adaptation¶

A incredible “hello world” in powershell, will be our automation script who need api

Input¶

By defaut ezBastion push routing information to the script. You can use this information, using some variables:

[CmdletBinding()]
param (
    $tokenid,
    $methode,
    $tag,
    $path,
    $version,
    $query,
    $constant,
    $xtrack,
    $body
)

Variables, tags, path, query, constant and body, are json string. You must unserialize it befor use.

Output¶

ezBastion worker waiting for script output, a json or empty string or error on stderr channel. Json produce a http 200 code, empty output a http 204 (no content) and a error produce a http 500.

If $out exist return a json (http 200) or nothing (http 204)

try {
    your code here
}
catch {
    write-error $_
}
finally{
  if ($out) {
      $out | convertto-Json -Compress 
  }
}

Admin console¶

Declare your script.
Test Bastion and STA (only for the fist api ^^ ).
Register your first worker.
Create an end point.
Link this endpoint to user account.

1 Job¶

A simple declaration, but don’t forget to activate it.

Add test1.ps1 as a job

2 Bastion / STA¶

The easy way to test ezBastion front and authentication service, it’s to use the authorize end point. If you receive a jwt in access_token, it smells good. You can decode this jwt, using https://jwt.io/

PS C:\> Invoke-RestMethod https://ezbastion.company.ltd/authorize -UseDefaultCredentials


expire_in    : 3600
expire_at    : 1471825528
access_token : slfghqsfjkihgq.swgfsqfdgsfdghsf.sfghsfgqf
token_type   : bearer

3 Workers¶

As worker is the service they run your script. Be sure to install all needed sdk on the machine and run the service with a account granted. Add one or more tag, we will need it after.

Add “pocworker1” worker and create “poc” tag

4 End point¶

Where we link all. We will generate a unique URL for this api. But first, take a look at ezBastion end point format:

we can split this url in seven parts, ezBastion use it to route the api.

GET: REST methode used.
https: scheme or protocol used.
api.ezbastion.com: bastion dns name.
v1: api version.
controller: name use in routing system.
action: same as controller, it’s a legacy of MVC model.
path: some static or variables items need by the script.
query: a other way to provide items to script.

Add an api end point https://api.ezbastion.com/v1/poc/test

5 Grant an account¶

Add a Windows account and link the api

Test it¶

call authorization endpoint to get a bearer token, with basic or NTLM auth
call our api using this token as bearer authentication

With Postman¶

Postman is a very popular rest (http) client based on chrome. http://www.getpostman.com/

With Powershell¶

The same using 4 lines of powershell:

PS C:\> $bastion = "http://CHAVERS-DESK:5505"
PS C:\> $b = Invoke-RestMethod "$bastion/authorize"  -UseDefaultCredentials 
PS C:\> $h = @{authorization = $b.token_type + " " + $b.access_token}
PS C:\> Invoke-RestMethod -Headers $h -Uri "$bastion/v1/poc/test"
hello world!

PS C:\> 

Debug¶

If you have some issue to integrate your existing powershell scripts.

Runas¶

On the worker machine, start a powershell using the service account used by ezb_wks service. And try to run the script manually.

Log¶

Have a look in the worker log folder. Do the same with bastion (ezb_srv) log.

DB browser¶

You can refer to “log” table where all api request information are logged. with:

date
status
client ip address
token (user accoçunt)
controller/action
full url
bastion and worker used
duration
error message normally null ;-)

Polling¶

What WikipediA say about “polling”

<< Polling, or polled operation, in computer science, refers to actively sampling the status of an external device by a client program as a synchronous activity. Polling is most often used in terms of input/output (I/O), and is also referred to as polled I/O or software-driven I/O. >>

Well … Let’s take an example.

You use a Powershell script for provisioning your’s VDI and this script takes 15 minutes. We will use polling to avoid any client timeout. If API polling option is checked, ezBastion will return task status link instead of waiting task end. The client will call this link to have the progress of the task and finally get the result.

Configuration¶

Activate “Asynchronous polling” in a POST api. Nothing else change (in your script to), just one click.

on the client¶

A polling api return a json structure with three url:

statusurl: This json, updated at script end. This link provide the task status (“PENDING”, “RUNNING”, “FAILED”, “FINISH”)
logurl: text file with raw script output (stdout + error + warning …)
resulturl: Link used to receive script json output when status is “FINISH”

on the worker¶

On the worker, inside jobpath folder (see install/worker) a directory tree will be created, with /year/month/day format. You will found three file inside a folder named with the task UUID. One for the log, one for the status and the last for the result.

Require mini:¶

ezb_admin v0.1.3
ezb_db v0.2.0
ezb_srv v0.2.0
ezb_wks v0.2.0
API should use POST methode.

Overview¶

Architecture¶

Public zone¶

ezb_sta¶

ezb_srv¶

Infrastructure zone¶

ezb_pki¶

ezb_db¶

ezb_admin¶

business zone¶

ezb_worker¶

ezb_vault¶

License¶

Community¶

Enterprise¶

Setup mode¶

Simple architecture¶

Expert architecture¶

Setup prerequisite¶

Network¶

SSL/TLS¶

PKI (ezb_pki)¶

1. Download ezb_pki from GitHub .¶

2. Open a admin command prompte, like CMD or Powershell.¶

3. Run ezb_pki.exe with init option.¶

4. Install Windows service and start it.¶

security consideration¶

DB (ezb_db)¶

Windows¶

1. Download ezb_db from GitHub .¶

2. Open a admin command prompte, like CMD or Powershell.¶

3. Run ezb_db.exe with init option.¶

4. Edit config.json¶

5. Install Windows service and start it.¶

STA (ezb_sta)¶

Windows¶

1. Download ezb_sta from GitHub¶

2. Download latest 9.X node.js with npm from official node.js site¶

3. Install nodes.js¶

4. Unzip ezb_sta package into the final Windows service folder¶

5. Open a admin command prompte, like CMD or Powershell.¶

6. From ezb_sta folder, install module with npm¶

7. Use ezb_sta.exe to generate config.json and certificat key pair¶

8. Edit config.json¶

9. Deploy certificat¶

10. Install windows service¶

Front server (ezb_srv)¶

Windows¶

1. Download ezb_srv from GitHub .¶

2. Open a admin command prompte, like CMD or Powershell.¶

3. Run ezb_srv.exe with init option.¶

4. Edit config.json¶

5. Install Windows service and start it.¶

Worker (ezb_wks)¶

Windows¶

1. Download ezb_wks from GitHub .¶

2. Open a admin command prompte, like CMD or Powershell.¶

3. Run ezb_wks.exe with init option.¶

4. Edit config.json¶

5. Install Windows service and start it.¶

Admin console (ezb_admin)¶

1. Http server¶

2. Download¶

3. Edit config.json¶

4. Connect¶

Make your first api¶

Perequisite¶

Automation script adaptation¶

Input¶

Output¶

Admin console¶

1 Job¶

2 Bastion / STA¶

3 Workers¶

4 End point¶

5 Grant an account¶

Test it¶

With Postman¶

With Powershell¶

Debug¶

1. Download ezb_sta from GitHub ¶

2. Download latest 9.X node.js with npm from official node.js site ¶