Skip to content

Getting started

Install pf

We recommend to use pipx to install pf. From a terminal, run this command:

$ pipx install provablyfine

And then, check that it has been installed successfully: 

$ pf --version
0.7.1

Create your first tenant

The fastest way to create your first tenant is to use the free tier of our managed instance. After you login, click on Add tenant and choose a tenant name that is available.

The list of tenants should display the new tenant!

Connect with your new tenant

From the managed instance, click on the Connect via CLI button to display the commands needed and run the accept command: 

$ pfa accept --invitation https://api.provablyfine.net/pf/t/your-tenant/directory

You can now login: 

$ pfa login

The login command triggers a browser-based login and saves your temporary (30 minutes) session key in your local ssh-agent. All other local CLI commands will use this key transparently until it expires.

If you do not have a local ssh-agent, login will ask for confirmation to store the session key as cleartext in your local configuration file ~/.config/pf/config.json.

Check your connection

If you get pong, you are authenticated successfully: 

$ pf ping
pong

Register a new server

If you have an OpenSSH (>= 7.4, released in december 2016) service installed on your server, you can register it within your tenant.

Create a new host identity

First, on your local host, create an identity associated with this OpenSSH server instance: 

$ pfa identity create -n demo
$ INVITATION_URL=$(pfa identity invite --manual -i $(pfa identity list -n demo -q))

Setup the host

You need to install first pf on the server globally: 

$ pip install --global provablyfine

Then, make your OpenSSH service know about the new centralized authentication system. Run this command on the server: 

$ pf openssh host-init --invitation $INVITATION_URL | sudo bash -s

Grant yourself access to the new host

We create a role, grant ssh permissions to all hosts to that role, and we add ourselves to that role: 

$ pf role create -n users
$ USERS_ROLE_ID=$(pf role list -n users -q)
$ pfa grant ssh-shell --username root --tag id=device | pfa role grant -i $USERS_ROLE_ID --set
$ pfa role member -i $USERS_ROLE_ID -a $(pfa whoami)

Connect to your new host

The pf ssh command is compatible with the OpenSSH ssh binary CLI: 

$ pf ssh root@demo echo hello
hello

Onboard new users via email

Create a new user identity

$ pfa identity create -n julie.chloe@gmail.com

Grant permissions to the new user

We are going to make this new user a member of the builtin root role for convenience: 

$ pfa role -i $(pfa role list -n root -q) -a julie.chloe@gmail.com

Invite the user

Create an invitation, and send it to this user via email: 

$ pfa identity invite --email -i $(pfa identity list -n julie.chloe@gmail.com -q)

Accept the invitation

After you share the invitation with your new user, she receives an email that describes how to connect via the SSO. accept asks the user to select which SSO to use, and completes login via a browser popin before coming back to the terminal: 

$ pf accept https://api.provablyfine.net/pf/t/your-tenant/directory
XXX

She can then look at which hosts she is allowed to access: 

$ pf hosts
XXX

Next steps

The setup we have completed is pretty basic. A more realistic setup would require a clear mapping of your security policy (who can access which hosts) to a set of identities, tags, roles, and boundaries.

Realistically, most administrators probably want to authenticate users via their own OIDC SSO.

You also need to prepare a strategy to automate host enrollment in your tenant, ideally so that it happens when hosts are provisionned.