bifroest

README

Engity's Bifröst

Bifröst (spoken as "Bee-frest"), is an advanced SSH server. It can be used as a drop-in-replacement for OpenSSH Server, but it was actually created with some more advanced stuff in mind; see below.

TOC

• Use-cases
• Features
• Getting started
• Configuration
• Status
• License
• Code of Conduct
• Contributing
• Security

Features

1. SSH protocol complaint
2. OpenID Connect
3. Remember me
4. Automatic user provisioning

SSH protocol complaint

Fully SSH protocol compliant server, like you would expect.

OpenID Connect

You can connect via your SSH keys, as usually. And so on...

...but you can also use OpenID Connect (or OAuth2) identity provider. The best thing about this is: In contrast to the other SSH servers with OpenID Connect, you don't need any other client locally installed, than your regular SSH Client (OpenSSH, PuTTy, ...).

Remember me

If authorized via another authentication token then a Public Key, it can store (temporally) your provided Public Key, for faster reconnect, while the session is still alive.

Automatic user provisioning

If a local environment is used where the user executes inside and OpenID Connect was used to authorize a user, Bifröst can automatically create these users based on a defined requirement template.

It can also automatically clean up these users as they're no longer needed, for example: If their session becoming idle and times out (30 minutes). In this case the user itself, its home directory and all running processes can be cleaned up.

More to come...

Getting started

1. Download the latest version of Bifröst (see releases page):

   # Syntax
   curl -sSLf https://github.com/engity-com/bifroest/releases/download/<version>/bifroest-<os>-<arch>-<edition>.tgz | sudo tar -zxv -C /usr/bin bifroest
   
   # Example
   curl -sSLf https://github.com/engity-com/bifroest/releases/download/v1.2.3/bifroest-linux-amd64-extended.tgz | sudo tar -zxv -C /usr/bin bifroest
   

2. Configure Bifröst. For example, download the demo configuration and adjust it to your needs (see documentation of configuration for more details):

   sudo mkdir -p /etc/engity/bifroest/
   sudo curl -sSLf https://raw.githubusercontent.com/engity-com/bifroest/main/contrib/configurations/sshd-dropin-replacement.yaml -o /etc/engity/bifroest/configuration.yaml
   # Adjust it to your needs
   sudo vi /etc/engity/bifroest/configuration.yaml
   

3. Run Bifröst:

   sudo bifroest run
   

Let it run automatically

systemd

To enable Bifröst to run at every server start where systemd is available, simply:

1. Download our example service configuration:

   sudo curl -sSLf https://raw.githubusercontent.com/engity-com/bifroest/main/contrib/systemd/bifroest.service -o /etc/systemd/system/bifroest.service
   

2. Reload the systemd daemon:

   sudo systemctl daemon-reload
   

3. Enable and start Bifröst:

   sudo systemctl enable bifroest.service
   sudo systemctl start bifroest.service
   

What's next?

Read Use-Cases and the configuration documentation to see what else you can do with Bifröst.

Status

This project is currently under development. The application is stable (file a bug if you find one), but the configuration/command/API structure needs improvement.

More topics

• Use-Cases
• Configuration
• License
• Code of Conduct
• Contributing
• Security