
## 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](https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/oauth_provider).

For this tutorial, we will make use of the Koyeb [service mesh and discovery](/docs/reference/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](/blog/service-mesh-and-microservices-improving-network-management-and-observability) and accessible to authenticated users via OAuth2 Proxy

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

![OAuth2 proxy deployment on Koyeb](/static/images/tutorials/oauth2-proxy-diagram.svg)

## Requirements

To successfully follow and complete this tutorial, you need:

- A [Koyeb account](https://app.koyeb.com) to deploy and run
- A [GitHub account](https://github.com/) 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](#create-and-configure-a-new-google-oauth-application)
2. [Deploy and configure OAuth2 Proxy on Koyeb](#deploy-and-configure-oauth2-proxy-on-koyeb)
3. [Deploy a private sample application on Koyeb](#deploy-a-private-sample-application-on-koyeb)
4. [Validate the setup](#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](https://github.com/koyeb/example-expressjs).

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](https://app.koyeb.com) 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](https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/overview).


This guide explains how to deploy OAuth2 Proxy to secure and add authentication to all your services on the Koyeb serverless platform.

OAuth2

Add Authentication to your Apps using OAuth2 Proxy