Skip to content

Latest commit

 

History

History
239 lines (171 loc) · 12.5 KB

README.md

File metadata and controls

239 lines (171 loc) · 12.5 KB

logo-yellow

Boruta is a standalone authorization server implementing OAuth 2.0 and Openid Connect specifications. It provides administration tools and a customizable identity provider out of the box to manage authorization, but also a gateway to apply access rules to incoming traffic.

Status

This server is on an ongoing beta stage. Developments are moving fast on master then are keen to be less stable. Tagged versions are said to be more stable and sanity tested.

Documentation

The documentation of boruta server is available here it provides insights about its usage.

Implemented specifications and certification

As it, boruta server aim to follow the RFCs from IETF:

And the specifications from the OpenID Foundation:

This server has been certified for the Basic, Implicit, and Hybrid OpenID Provider profiles by the OpenID Foundation on October, 18th 2022 for the tagged version 0.1.0

This server has been certified for the Config and Dynamic OpenID Provider profiles by the OpenID Foundation on May, 16th 2023 for the tagged version 0.2.0

This server has also been certified against the European Blockchain Service Infrastructure (EBSI) issuance test suite for the tagged version 0.4.0 and for verifiable credential verification for the tagged version 0.5.0.

EBSI certified - issue EBSI certified - verify OpenID certified

Installation

A loom presentation about how to get a server up and running.

Note that the easiest way to try the server is by using docker compose.

System wide setup (Debian based)

You can perform a system wide installation performing the following command. It will create a systemd service to run the server. During the installation, you will be asked to fill out the environment variables for the server. The environment takes .env.example as a basis.

Remember to change admin username / password for the install to be secured

curl -s https://raw.githubusercontent.com/malach-it/boruta-server/master/scripts/setup.debian.sh | sudo sh

The applications will be available on different ports (depending on the filled out environment configuration):

Run an instance from docker

Note this image is built for x86_64 architecture, for other architectures build yourself the image or use docker compose install that will build the image for your architecture.

A docker image is available at malachit/boruta-server on DockerHub, you will need a postgres instance installed on your system with credentials provided as environment variables in .env.*.

  1. Get environment file
wget https://raw.githubusercontent.com/malach-it/boruta-server/master/.env.dev

Once done you will be able to launch the server.

docker run -it --env-file .env.dev --network=host malachit/boruta-server:0.4.0

The applications will be available on different ports (depending on the values provided in .env.dev):

Admin credentials are the one seeded and available in environment file.

Run an instance from docker-compose

You can build and run the docker images as follow:

docker-compose up

The applications will be available on different ports (depending on the docker compose environment configuration):

Admin credentials are the one seeded and available in environment file.

Requirements

  • Elixir >= 1.13
  • postgreSQL >= 13
  • node >= 16.5 (if you need to prepare assets)

Run a release from scratch

  1. first you need to get project dependencies
mix deps.get
  1. you need to prepare assets in order for them to be included in the release
./scripts/prepare_assets.sh
  1. then you can craft the release
MIX_ENV=prod mix release boruta

Once done, you can run the release as follow:

env $(cat .env.example | xargs) _build/prod/rel/boruta/bin/boruta start

The applications will be available on different ports (depending on the values provided in .env.example):

Admin credentials are the one seeded and available in environment file.

Run a development server

  1. first you need to get project dependencies
mix deps.get
  1. you need to prepare assets in order to fetch javascript dependencies
./scripts/prepare_assets.sh
  1. because of the forwarding of requests between web and identity modules, you need to add the /accounts path prefix in configuration
--- a/apps/boruta_identity/config/config.exs
+++ b/apps/boruta_identity/config/config.exs
@@ -4,8 +4,8 @@ config :boruta_identity,
   ecto_repos: [BorutaAuth.Repo, BorutaIdentity.Repo]

 config :boruta_identity, BorutaIdentityWeb.Endpoint,
-  url: [host: "localhost"],
-  # url: [host: "localhost", path: "/accounts"],
+  # url: [host: "localhost"],
+  url: [host: "localhost", path: "/accounts"],

You now should be able to start the development server

env $(cat .env.dev | xargs) MIX_ENV=dev mix boruta.server

The applications will be available on different ports (depending on the values provided in .env.dev):

Admin credentials are the one seeded and available in environment file.

Default admin credentials

In order to authenticate to the administration interface you will be asked for credentials that are by default (seeded from environment variables) [email protected] / imaynotknowthat.

Environment variables

Variable name description
SECRET_KEY_BASE The Phoenix secret key base. It must be at least 64 cheracters long.
POSTGRES_USER The database user provided as credentials in postgreSQL connections.
POSTGRES_PASSWORD The database password provided as credentials in postgreSQL connections.
POSTGRES_DATABASE The database name provided in postgreSQL connections.
POSTGRES_HOST The database host provided in postgreSQL connections.
POOL_SIZE The postgreSQL pool size of each application, the real connection count will be twice that value.
MAX_LOG_RETENTION_DAYS The number of days the logs are kept to the server. This value defaults to 60.
K8S_NAMESPACE If set along with K8S_SELECTOR, it setups libcluster in order to connect boruta erlang nodes in kubernetes together.
K8S_SELECTOR If set along with K8S_NAMESPACE, it setups libcluster in order to connect boruta erlang nodes in kubernetes together.
BORUTA_ADMIN_OAUTH_CLIENT_ID An uuidv4 string representing the admin oauth client id. It will be part of the client seeded in the setup task.
BORUTA_ADMIN_OAUTH_CLIENT_SECRET The admin oauth client secret. It will be part of the client seeded in the setup task.
BORUTA_ADMIN_OAUTH_BASE_URL The URL base URL of the authorization server admin will use (linked to above client_id and secret, without trailing slash).
BORUTA_ADMIN_EMAIL The first admin email. It will be part of the user seeded in the setup task.
BORUTA_ADMIN_PASSWORD The first admin password. It will be part of the user seeded in the setup task.
BORUTA_ADMIN_HOST The host that represent the host where boruta admin server will be deployed to.
BORUTA_ADMIN_BIND The IP address the boruta admin server will be bound to.
BORUTA_ADMIN_PORT The port where boruta admin server will be exposed on.
BORUTA_ADMIN_BASE_URL The base URL where boruta admin server http endpoint will be deployed to (without trailing slash).
BORUTA_OAUTH_SCHEME The scheme that will be used for URL building, default to https.
BORUTA_OAUTH_HOST The host where boruta oauth server will be deployed to.
BORUTA_OAUTH_BIND The IP address the boruta oauth server will be bound to.
BORUTA_OAUTH_PORT The port where boruta oauth server will be exposed on.
BORUTA_OAUTH_BASE_URL The base URL where boruta oauth server http endpoint will be deployed to (without trailing slash).
BORUTA_GATEWAY_PORT The port where boruta gateway will be exposed on.
BORUTA_GATEWAY_SIDECAR_PORT The port where boruta microgateway will be exposed on.
BORUTA_GATEWAY_CONFIGURATION_PATH The path containing the gateway static configuration.
BORUTA_CONFIGURATION_PATH The path containing the boruta static configuration.
BORUTA_SUB_RESTRICTED If set, the uid of the only user to have access to the administration interface.
BORUTA_ORGANIZATION_RESTRICTED If set, the uid of the only organization to have access to the administration interface.
DID_RESOLVER_BASE_URL Did resolver API endpoint, accroding to the W3C DID resolution specification
DID_REGISTRAR_BASE_URL Did registrar API endpoint, accroding to the W3C DID registration specification
DID_SERVICES_API_KEY API key granting access to DID revolver and registrar services.

Code of Conduct

This product community follows the code of conduct available here

License

This code is released under the Apache 2.0 license.

About boruta

The name boruta comes from a polish legend where he is a gentle devil (an angel, maybe) that is such evil that having him at home makes you safe. He was living during the middle ages in the castle of the little town of Leczyca, since then the people from there have a little figurine of him at home helping the house to be protected from bad fate.