orcais a SSH gateway comparable to a reverse HTTP proxy. You
can use orca to enable your employees to connect to internal servers without
the need to build a VPN. Simply put orca in front of your servers and you can
connect to any backend server via SSH.
![Call Graph](http://g.gravizo.com/g? digraph G { client -> sshgate [label="Agent Forwarding"]; sshgate -> backend1; sshgate -> backend2; sshgate -> backend3 [label="Agent Forwarding"]; sshgate [label="Orca Gateway"] backend1 [label="Backend 1"] backend2 [label="Backend 2"] backend3 [label="Backend 3"] sshgate -> keystore [style=dotted, label="HTTP Rest"]; keystore [label="PubKey store"] } )
Orca uses a public key store to query the user for a given public key. You can
implement your own REST service (its one single function) or you can use the
preimplemented key store bundled with orca which uses a clustered etcd
backbone to store all the public keys.
For quick testdrive there is a docker image!
To build orca you need make bower and go.
Create a new workspace in your home and execute the included setup.sh. You do not
need to clone before, the setup.sh clones:
~ mkdir orcaWorkspace
~ cd orcaWorkspace
~ curl https://raw.githubusercontent.com/clusterit/orca/master/setup.sh | /bin/shNow you have a ~/orcaWorkspace directory which should be embedded in your GOPATH. This
workspace contains all needed dependencies. If you don't want a separate project directory
for orca you do a go get github.com/clusterit/orca/cmd/gateway and the gateway will
be installed in your default GOPATH. The other tools can be built with make.
All binaries are built into src/github.com/clusterit/orca/packaging/.
TODO: dockerize the build
Please install etcd and start a cluster; a single machine cluster is ok.
If your etcd cluster is not accessible via http://localhost:4001 you can
specify a different location via the -e ... flag. You can also name your
zone with -z myhomezone.
In a production you should use an etcd cluster with https and client
certificates. You can specifiy the clustermembers with -e https://<etcd-member>
and also specify the --etcdkey, --etcdcert (key and cert of the client) and
--etcdca (the cert of the rootca; not necessarily needed). Another option are the
environment variables:
- ORCA_ETCD_MACHINES
- ORCA_ETCD_KEY
- ORCA_ETCD_CERT
- ORCA_ETCD_CA
If you want a testdrive, start an etcd-cluster with goreman start in the testing
subdirectory. You can then
cd testing
export ORCA_ETCD_MACHINES=https://localhost:4001,https://localhost:4002,https://localhost:4003
export ORCA_ETCD_KEY=`pwd`/ssl/client.key
export ORCA_ETCD_CERT=`pwd`/ssl/client.cert
orcaman uses an external Oauth provider to authenticate. So first of all, please
register a new application with your github account, navigate to your settings
and register a new application. Enter
Orca local as name and http://localhost:9011 as homepage URL. The redirect
url should be http://localhost:9011/redirect.html. Now click on Update Application
and you will get a Client ID and a Client Secret. As the name says, keep the
secret in a secret place :-).
Start orcaman and register a oauth provider (at this time, orca knows
the settings for github and google):
orcaman provider github <your-clientid> <your-clientsecret>
2015/04/18 16:04:03 [DEBUG] no zones existing, creating zone 'intranet'.
2015/04/18 16:04:06 [DEBUG] create a default gatway setting
2015/04/18 16:04:07 [DEBUG] create a default ManagerConfig setting
(*oauth.OauthRegistration)(0xc208070420)({
Network: (string) (len=6) "github",
ClientId: (string) (len=20) "<your-clientid>",
ClientSecret: (string) (len=40) "<your-clientsecret>",
Scopes: (string) (len=10) "user:email",
AuthUrl: (string) (len=40) "https://github.com/login/oauth/authorize",
AccessTokenUrl: (string) (len=43) "https://github.com/login/oauth/access_token",
UserinfoUrl: (string) (len=27) "https://api.github.com/user",
PathId: (string) (len=5) "login",
PathName: (string) (len=4) "name",
PathPicture: (string) (len=10) "avatar_url",
PathCover: (string) ""
})
Next, register an admin account. Prefix your account with the name of the provider you used in the previous step:
orcaman admins github:<your-github-account>
Last, but not least, start orcaman:
orcaman serve
2015/04/18 16:06:28 [INFO] start listening on :9011
Now you can connect
and login with your github account
First, upload a public key, so click on the Key tab and add a new key:
In another console you can now start the gateway:
gateway
2015/04/18 16:55:07 [INFO] gateway listens on "[::]:2022" ...
If you want to connect to a known computer via the gateway, you should first add your keys to your agent:
ssh-add <your-key-file>
You can leave the filename and ssh-add will add your default keys.
After that you can try to login (please accept the server key; you can change
it via orcaman):
ssh -A -p 2022 [email protected]@localhost
[email protected]@localhost's password:
As you can see, the address of the server uses the form
user@<your-server>@gateway. You can also use ssh -l user@<your-server> gateway
to specify the user, because the userid must include the name of the target server.
And as a third option you can configure a default server
where the gateway will delegate a call; in this case you can omit <your-server>.
In the upper example the gateway denies access and prompts for a password (which will also not be accepted because you don't have one):
2015/04/18 16:55:48 [DEBUG] remote: 127.0.0.1:55746: cannot fetch key for user '[email protected]': HTTP 404: {"error":"entity could not be found"}
2015/04/18 16:55:48 [DEBUG] remote: 127.0.0.1:55746: cannot fetch key for user '[email protected]': HTTP 404: {"error":"entity could not be found"}
2015/04/18 16:55:48 [DEBUG] remote: 127.0.0.1:55746: not allowed to login for user '[email protected]': please activate your account
2015/04/18 16:55:49 [ERROR] failed to handshake (EOF)
Here you see three attempts to login, because i have three keys in my local development computer here (ssh-add'ed). Two of the attepmts were not accepted because the gateway could not find an acceptable user for the provided public key. The third was denied, because the account is not activated, so lets activate it for 1 hour:
If you now try the login again, it should succeed!
2015/04/18 17:03:23 [INFO] remote: 127.0.0.1:55777: login by &{Id:0e65dc4d-144d-4410-bad2-88f25ae634df Name:ulrichSchreiner Keys:[{Id:usc@fedorabox Value:ssh-rsa .... Fingerprint:... }] Roles:USER,MANAGER Aliases:[ulrichSchreiner@github] Allowance:0xc208114c00}
2015/04/18 17:03:23 [INFO] [client=127.0.0.1:55777] [sid=3f1bee208f674830239f3fbc2fc5ab1164578928ff9cc510fd8d530410a39d58] new ssh connection with [SSH-2.0-OpenSSH_6.6.1p1 Ubuntu-8]
You don't need to use the time based login, go to the Gateway Settings and disable them. You can also change the loglevel and the SSH Server key. Please note that a change of this values is published to all gateway's in the selected zone. You don't have to restart:
As you have seen, the gatway also supports 2FA. To use this feature you need a OTP app on your mobile. Links to them are embedded in the application. After you installed such an application, go to your account page and click on ENABLE:
After you scanned the QR code you must enter an OTP password displayed on your OTP application. If you entered the right one you have successfully activated 2FA!
After this activation, you need your private SSH key and you also need your mobile. The SSH gateway will prompt you for a password and you must enter the current one time password displayed in your app.
As you can see in the screenshot, there is a caching option. If you don't want to enter your OTP every time you can use the slider to let the gateway cache your successful authentication. Please note that the administrator of the gateway can overwrite this value with an upper limit! The default value in the gateway is 0, so it doesn't matter what the user set; a zero value in the gateway simply disables 2FA caching.
Please note that the TOTP is only used for the SSH gateway; it is not used for
the Web-UI! If you want to use Two Factor Authentication for the frontend too,
you have to enable it with the account provider (google, github, ...). So if
anyone steals your oauth-credentials, the attacker can login, upload public
keys and create a new TOTP secret!
If you decide to use the web frontend in the internet your users should be
aware of this. Otherwise you should think about using the frontend only in
the intranet.
To register new OAuth providers, you can use predefined ones (google, github)
or you can insert the values you want. Here are some templates for given
oauth servers:
- name:
gitlab - clientid/clientsecret: generate via Gitlab Admin UI
- scopes: empty
- Auth Url:
<yourgitlabserver>/oauth/authorize - Access Token Url:
<yourgitlabserver>/oauth/token - Userinfo Url:
<yourgitlabserver>/api/v3/user - Path Id:
username - Path Name:
name - Path Picture:
avatar_url
orca has the different components, one for the ssh gateway, another for the management
interface/rest services.
This is the SSH daemon that listens for incoming requests. Any request must have one or more
public keys and the gateway invokes a REST call UserByKey to get the user for the given public
key. If there is no such user, the login will be denied.
If there is a user, the gateway checks an optinal Allowance. This check can be enforced, so that the user has to login via a second channel (a web UI) and click on a button to allow the login for a specific duration.
After the permission to login to the gateway is granted, the request will be forwarded to the
referenced backend server with current ssh-agent provided keys.
The orcaman provides Rest-Services and an embedded HTML5 app. This application can be used
to store keys inside etcd and to request an Allowance for a specific time. If you have
the MANAGER role you can also register new users and change some other settings.
The orcaman also implements the UserByKey REST endpoint
which is needed by the gateway. If you start orcaman with a publish address it registeres
itself within a wellknown key inside of etcd so it will be discoverable by the gateway. After
stopping or crashing orcaman it will deregister automatically.
To secure the REST api, orcaman uses a JWT which signs the user data with a RSA key. The
allowed users for orcaman have to be configured in the etcd backbone. The user logs in via
an Oauth2 Provider (at this time orcaman supports Google users, but other OAuth2 providers will
follow soon) and orcaman checks if the user is allowed to use orca.
orcaman is also a cli webservice provider. It populates all the webservices with a
simple HTTP Basic Auth backend. To disable other's to connect to this simple authentication
you should always put a reverse proxy in front of orcaman. You can also start the cli
services on a different interfaces (--clilisten ... so that they can only be used from localhost
whereas the Oauth-secured endpoints can listen on a public IP.
The cli support some basic commands to manage the system from the command line. To use it, you have to set two environment variables:
-
ORCA_SERVICE
The URL of the webservice backend. If you have more than one
orcamanrunning, specify one of the or use a loadbalancer in front. -
ORCA_TOKEN
Your token, which is displayed in the web UI of
orcaman. Keep this token secure or generate a new one if this token is compromized. It allows you to make service calls and you will be identified by this token
When both variables are set, you can simply call cli to see all options.
When using git with orca in front of gitlab, you must use agent forwarding. So create a file named $HOME/.ssh/config with a content like:
Host gitlabgw
ForwardAgent yes
where gitlabgw is the adress of orca. Now you can use git commands like git clone git@gitlab@gitlabgw:user/test.git and git will do agent forwarding. If you enabled 2FA in orca you must have a correct private key AND you will be prompted for a password (your TOTP).
Last but not least you can configure orca to use gitlab as the default host. And now you don't see any difference, you can do a git clone git@gitlabgw:user/test.git and orca will forward the request to your internal server gitlab.