Add Authentication to your Apps using OAuth2 Proxy

Introduction

OAuth2 Proxy is a reverse proxy and static file server that provides authentication using third-party providers like Google, GitHub, and others for validating accounts by email, domain, or group.

Oauth2 Proxy is useful when you want:

• One or more of your applications to be accessible only by authenticated users, for instance, users using a specific domain, emails whitelisting, and more
• To rely on a third-party provider to handle the authentication process (Google, GitHub, etc.)
• To keep a clear separation between the authentication service and the rest of your applications

In this guide, we will explain how to deploy OAuth2 Proxy on Koyeb to secure access to a sample application. We will configure OAuth2 Proxy to use Google as a provider for the authentication. If you are interested in using other providers, you can find the list of supported providers on the OAuth2 documentation.

For this tutorial, we will make use of the Koyeb service mesh and discovery and will deploy:

• The OAuth2 Proxy service using the official Docker image and expose it publicly to act as our authentication layer and gateway access our sample application
• A sample application accessible only via the Koyeb service mesh and accessible to authenticated users via OAuth2 Proxy

Below is the diagram of what our deployment will look like:

Requirements

To successfully follow and complete this tutorial, you need:

• A Koyeb account to deploy and run
• A GitHub account to deploy the sample application

Steps

To successfully follow this guide, you need to follow these steps:

1. Create and configure a new Google OAuth application
2. Deploy and configure OAuth2 Proxy on Koyeb
3. Deploy a private sample application on Koyeb
4. Validate the setup

Deploy a private sample application on Koyeb

First, get started by deploying the sample application that the OAuth2 Proxy will serve once a user is authenticated. In this guide, we will deploy the Koyeb ExpressJS example application available on the following GitHub repository.

Deploy it inside a new Koyeb App, clicking the Deploy to Koyeb button in the readme. You land on the pre-filled App creation page to deploy the application.

In the Exposed ports section, disable the Public exposure of the service by clicking the switch.

Change the App name to oauth2-proxy-on-koyeb and click Deploy

Our Koyeb App is created, and our sample application is being deployed. We can now move to the next section.

Create and configure a new Google OAuth application

Before deploying the OAuth Proxy service, we need to create a new Google OAuth application we will use to authenticate our users.

Go to https://console.developers.google.com/project and create a new project that will own our application by clicking New project on the project dropdown menu in the navigation bar. Once your project is created, in the search bar, type OAuth consent screen and press Enter.

You land on the OAuth consent screen creation page.

1. Select External as User type
2. Fill in the App information form with your app's name, logo, scopes, test users, etc.

Once the configuration is completed, click the Save button.

Then, in the search bar, type Credentials and press Enter to create a new OAuth2 client. On the Credentials page, click the Create credentials button and select OAuth client ID.

1. Select Web application as the application type
2. Name your OAuth 2.0 client, for example, Koyeb OAuth2 client
3. In the Authorized redirect URIs click Add URI and set the URI to https://<yourApp>-<yourOrg>.koyeb.app/oauth2/callback where <yourApp> is your Koyeb App name and <yourOrg> your Koyeb organization name

Click the Create button, your OAuth client ID and Secret appear. You can also download them as a JSON file. Save them in a safe place. We will need them in a future step.

Our application is now ready and will allow us to obtain limited access to Google user accounts by delegating user authentication to Google.

Deploy and configure OAuth2 Proxy on Koyeb

We are now ready to deploy the OAuth2 Proxy service on Koyeb. Go to the Apps tab of the Koyeb control panel and select the App you previously created.

On the chosen App page, click the Create Service button to deploy the OAuth2 Proxy service:

1. Select Docker as the deployment method.
2. In the Docker image field, enter quay.io/oauth2-proxy/oauth2-proxy.
3. In the Environment variables section, create the following environment variables:

• OAUTH2_PROXY_COOKIE_SECRET: with a seed string for secure cookie as value. You can create the following shell command to generate once: dd if=/dev/urandom bs=32 count=1 2>/dev/null | base64 | tr -d -- '\n' | tr -- '+/' '-_'; echo
• OAUTH2_PROXY_CLIENT_ID: with Google Oauth2 client ID you previously created as value
• OAUTH2_PROXY_CLIENT_SECRET: with Google Oauth2 client Secret you previously created as value
• OAUTH2_PROXY_PROVIDER: with the Oauth provider name as value, here google
• OAUTH2_PROXY_EMAIL_DOMAINS: with the authenticate emails domains as value, here *
• OAUTH2_PROXY_HTTP_ADDRESS: with 0.0.0.0:8080 to ensure the OAuth2 Proxy is listening on all interfaces
• OAUTH2_PROXY_UPSTREAMS: with the private domain of the Koyeb Service you want to restrict access, example: http://<myService>.<myApp>.koyeb:3000

4. Click Deploy.

The Oauth Proxy service is being deployed and will be up and running in a few seconds.

Validate the setup

With the OAuth2 Proxy deployed, we are now ready to test the authentication flow.

In your browser, open your Koyeb App URL of form https://<yourApp>-<yourOrg>.koyeb.app/.

You land the OAuth2 Proxy landing page, where you can authenticate with your Google account.

Click the Sign in with Google button and select the Google account you want to use to authenticate. Once the authentication has succeeded, the Oauth2 Proxy will proxy requests to your private sample application.

Conclusion

In this guide, we demonstrate how OAuth Proxy helps to delegate user authentication to a third-party provider and secure applications without any code changes in your existing application.

We took advantage of the Koyeb Mesh and discovery to make our OAuth2 Proxy and the sample application services communicate effortlessly and securely.

OAuth2 Proxy provides many options you can use to fine-tune the authentication flow and more. You can learn more about what you can achieve by reading the configuration options available in the documentation.