Step SSH + Gitea integration w/OAuth

[LecrisUT]

I was wondering how to integrate step ssh with something like gitea. Hopefully this would be popular enough to become more standard, but for now gitea's setup should cover all possible outcomes.

Ideal usage

1. Setup a remote via ssh
2. When doing a git operation, prompt for the OAuth to get a short-lived key
3. Repo server after checking its internal public key setup, would check stored CAs (certificate/URL+fingerprint/etc.) either setup for each user/organization or globally and check the certificate of the ssh'ing user
4. Proceed with normal user authentication and git command

Benefits

• Easier to setup securely and roll the public key
• The certificate/OAuth has built-in info of the user
• Can allow anonymous ssh via git and access control

Possible problems:

• gitea can be setup either with its built-in sshd or the OS's, where in the former the user has to be the gitea unix user
• If the ssh-ing user is a local user able to directly ssh to the server, it should be able to distinguish if it's ssh-ing normally or to do a git operation. The CA would have to allow to use both usernames for the ssh attempt, but specify the OAuth user in the certificate.
• Multiple step-ca servers should be allowed on the server so that each user can point to their own setup. Would the repo server be able to know which CA server granted its permission, possibly from the client certificate? Would the repo server be able to add/manage additional CA servers it trusts?
• Is/Can the client certificate be passed to the listening repo server to further access control?

Most of this implementation would have to be on the repo server side, but how far is the step ssh standard that such and implementation can be done? Are there more issues that should be considered?

[tashian]

Hi @LecrisUT I have been meaning to follow up on this. I think a Gitea workflow is a great idea, and if you're able to get it working we'd love to be able to share it in a blog post or tutorial about it.

step ssh will issue standard SSH certificates derived from the OIDC token. So, if that's something Gitea supports then you should have a good flow here.

Not sure if you saw this, but in our blog post about SSH certificate templates, I have an example that uses step-ca SSH certificate templates to support this flow in GitHub (it requires a GitHub enterprise account, though). Point is, you can customize the SSH certificate fields to meet your needs. And you can pass custom claims from the OIDC token into the certificate, if that's helpful.

[LecrisUT]

Thanks for the pointers, I should be able to test some configuration with this and get some feedback from the gitea community

[LecrisUT]

@tashian It sort-of works without special settings like the certificate templates.
So it turns out gitea already has ssh certificates implemented, and you can add the principals in your certificate to login. However I was only able to get it running on gitea's native sshd, and setting up SSH_TRUSTED_USER_CA_KEYS directly instead of using SSH_TRUSTED_USER_CA_KEYS_FILENAME. I suspect that part is because gitea uses different names than the ones in sshd: ssh-ecdsa-sha2-nistp256 instead of ecdsa-sha2-nistp256. I suspect that I don't have the system's sshd setup so that it redirects properly to gitea's logic, instead I am using regular git via plain ssh. If I figure out how gitea is supposed to be setup for the system's sshd.

Otherwise, the setup is straightforward, and you don't need to add the git user in your user certificate.

[LecrisUT]

I think I understand what's going on. If I shutdown step-ca's ssh certificate login, and I use a user's ssh key, it will use gitea's authorized_keys with it's command that enables it logic:

PTY allocation request failed on channel 0
Hi there, ****! You've successfully authenticated with the key named ****, but Gitea does not provide shell access.
If this is unexpected, please log in with password and setup Gitea under another user.
Connection to gitea.example.com closed.

However when we use step-ca's it completely bypasses this and we don't get the same message.

[LecrisUT]

Ok the missing piece was setting AuthorizedPrincipalsFile .ssh/authorized_principals. So finally there are two approaches:

Using gitea's built-in sshd

First setup gitea's built in ssh server to include the CA_user public key, e.g.:

DISABLE_SSH                           = false
START_SSH_SERVER                      = true
BUILTIN_SSH_SERVER_USER               = gitea
SSH_DOMAIN                            = gitea.example.com
SSH_PORT                              = 22
SSH_LISTEN_PORT                       = %(SSH_PORT)s
; Place the CA_user public key here in the format ssh-<algorithm> <key>
SSH_TRUSTED_USER_CA_KEYS              = ssh-ecdsa-sha2-nistp256 THELONGCAPAUBLICKEY
; Or alternatively link it to a file
SSH_TRUSTED_USER_CA_KEYS_FILENAME     = /path/to/CA/Public/Key

Note: Beware that the format in gitea's file is different than the one used in the sshd_config, so you would not be able to link to the one used there directly , i.e. /etc/ssh/ca.pub.

And that's it, everything should work out-of-the-box. Check the Testing-connection section that everything works ok.

Using the host's sshd

On top of the documented sshd_config in step-ca's documentation and blogs, make sure AuthorizedPrincipalsFile is set. All together the config file should have these settings set:

AuthorizedPrincipalsFile .ssh/authorized_principals
TrustedUserCAKeys /etc/ssh/ca.pub
HostCertificate /etc/ssh/ssh_host_ecdsa_key-cert.pub
HostKey /etc/ssh/ssh_host_ecdsa_key

On gitea's side the only settings needed to be enabled is SSH_CREATE_AUTHORIZED_PRINCIPALS_FILE in order to create the local commands in .ssh/authorized_principals so that gitea can authorize the principals it needs from the system's sshd:

SSH_CREATE_AUTHORIZED_PRINCIPALS_FILE = true

Also make sure you run Update the '.ssh/authorized_principals' file with Gitea SSH principals..

Testing connection

If everything works, you should be able to run one of the commands in ${GITEA_HOME}/.ssh/authorized_principals (this should be created when you're using the host's sshd setup) as the gitea/git user, e.g.:

$ /opt/gitea/gitea --config=/opt/gitea/custom/conf/app.ini serv key-15
Hi there! You've successfully authenticated with the principal ***, but Gitea does not provide shell access.
If this is unexpected, please log in with password and setup Gitea under another user.

And the same output should appear when you ssh via the certificate.

[tashian]

@LecrisUT 🤩 thank you for putting this together. This is really helpful. I edited the title to make it clearer for posterity. Step SSH + Gitea is a great workflow. 💯 💯 💯