OAuth and Other Authentication Methods

What's so special about authentication with a self-hosted application? Well, there's a few areas we take for granted with cloud hosted applications. However, these implementations are nothing huge to worry about and can easily be added and maintained in your app you wish to self-host. Let's dive in!

Username + Password

Standard username/email password authentication is straight forward with a self-hosted app. You need to make sure the username/email is unique and the password is securely stored in your database. Standard practice. However, when you get to password resets, there's a gotcha.

Why is email config important for self-hosted apps?

When you get to sending emails, this is always pre-configured on a cloud provider. You forget your password, just send a password reset. On a self-hosted instance, that might not always be the case. As part of your onboarding you should ensure that an email provider is configured correctly or you could end up with some serious functional issues.

While part of this lies on the system admin side, some of this relies on the developer. You need to gracefully handle scenarios where an email provider is not configured and alert the super admin. This becomes even more critical if your app supports password-less authentication via email or two factor with a code sent to your email address.

The other area of concern is how to ensure email deliverability. Once again, on a cloud instance, the company managing the app should have devoted a ton of time to ensure this is set up. However, a quick self-hosted install this might not always be the case. In these scenarios, you should allow for multiple email providers that allow the user hosting your app to get off the ground quickly. SMTP should obviously be supported, but some other providers that support API keys might also be helpful as these services can guide you through essential set up steps to configure email deliverability.

OAuth

If I were to estimate, I'd say 90% of oAuth providers integrate seamlessly into self-hosted instances. There's a little set up that you will need to guide your user through in most cases, but there's one huge exception: Google.

What's Needed for oAuth in a Self-Hosted App?

On a cloud SaaS, the company will have set up their app on as many oAuth provider's instances as they support. They will have generated the client id, secret keys, and redirect URLs. In a self-hosted app, the system admin will have to take care of that themselves. They should, like everything else, be guided through the process.

To get oAuth set up on your self-hosted instance, you will have to:

1. Register your application with an oAuth provider. To do this, your app needs to be up and running and have URL set up.
2. Set up a callback URL. This needs to be documented when you distribute your app .Where should the oAuth provider call back to to exchange tokens?
3. A way to store secure client and secret tokens.

All of these steps need to work seamlessly from documentation to app development. We will loop back to step 2, because this is where Google has an additional requirement. The biggest is step 3. You could allow the system admin hosting your app to set these tokens in specific, documented environment variables. Or, you could provide a UI that makes this easy and store them in your database. I prefer the latter. Why? Because it allows you to distribute your app easier and set up a UI that guides the system admin through the set up process instead of having them edit an .env file on a server when setting up your app. You just need to store these tokens securely (encrypted) in your database and load them when needed. This also makes any updates a lot easier if tokens get compromised.

What Makes Google Challenging?

It's not that Google is more challenging, they still follow a standard oAuth flow. What makes them different is they limit the callback URL. You can't have an IP Address or a .test domain. This means you have to host your self-hosted app somewhere with a valid DNS name set up. That's really it, but it's just an extra step for your system admin. It's more of an issue in development, but that's what services like ngrok are for anyway!

Hopefully this sheds some light on some of the quick gotchas you may encounter when designing your self-hostable application. If you have any questions, by all means reach out on X (danpastori) and I'll be glad to help!