> For the complete documentation index, see [llms.txt](https://docs.release.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.release.com/guides-and-examples/common-setup-examples/opensource-oauth-proxy.md).

# Using OAuth Proxy

[OAuth2 Proxy](https://oauth2-proxy.github.io/oauth2-proxy/) is:

> A reverse proxy and static file server that provides authentication using Providers (Google, GitHub, and others) to validate accounts by email, domain or group.

You can deploy OAuth2 Proxy to secure your services in Release. This is handy if a service doesn't have its own authentication mechanism.

## Configuring your Application Template

We'll use the Release [`apache-php` example](https://github.com/awesome-release/apache-php) from the `awesome-release` library to demonstrate.

After import, Release creates an Application Template containing the following:

```yaml
---
repo_name: awesome-release/apache-php
hostnames:
- web: web-${env_id}-${domain}
services:
- name: web
  has_repo: true
  static: false
  ports:
  - type: node_port
    target_port: '80'
    port: '80'
  build:
    context: app
```

We can add `oauth2-proxy` to this as a service alongside our `web` service.

```yaml
- name: oauth2-proxy
  image: quay.io/oauth2-proxy/oauth2-proxy
  ports:
  - type: node_port
    port: 4180
    loadbalancer: false
```

Replace the current hostname that points directly to the web service, and have it point to `oauth2-proxy` instead. Find the following:

```yaml
hostnames:
- web: web-${env_id}-${domain}
```

And change it to the following:

```yaml
hostnames:
- oauth2-proxy: web-${env_id}-${domain}
```

The Application Template should now look like this:

```yaml
---
repo_name: awesome-release/apache-php
hostnames:
- oauth2-proxy: web-${env_id}-${domain}
services:
- name: web
  has_repo: true
  static: false
  ports:
  - type: node_port
    target_port: '80'
    port: '80'
  build:
    context: app
- name: oauth2-proxy
  image: quay.io/oauth2-proxy/oauth2-proxy
  ports:
  - type: node_port
    port: 4180
    loadbalancer: false
```

## Configuring your default environment variables

Next, we'll configure OAuth by setting some environment variables.

Find all the available settings in the [OAuth2 Proxy documentation](https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/overview/#environment-variables).

In this example, we'll use Google as our OAuth2 provider but configuring any other service will be nearly the same.

```yaml
services:
  oauth2-proxy:
  - key: OAUTH2_PROXY_PROVIDER
    value: google
  - key: OAUTH2_PROXY_OIDC_ISSUER_URL
    value: https://accounts.google.com
  - key: OAUTH2_PROXY_CLIENT_ID
    value: << YOUR_CLIENT_ID >>
  - key: OAUTH2_PROXY_CLIENT_SECRET
    value: << YOUR_CLIENT_SECRET >>
    secret: true
  - key: OAUTH2_PROXY_COOKIE_SECRET
    value: << YOUR_COOKIE_SECRET >>
    secret: true
  - key: OAUTH2_PROXY_COOKIE_DOMAINS
    value: ".release.com"
  - key: OAUTH2_PROXY_EMAIL_DOMAINS
    value: release.com
  - key: OAUTH2_PROXY_WHITELIST_DOMAINS
    value: ".release.com"
  - key: OAUTH2_PROXY_HTTP_ADDRESS
    value: 0.0.0.0:4180
  - key: OAUTH2_PROXY_UPSTREAMS
    value: http://web:80
  - key: OAUTH2_PROXY_SKIP_PROVIDER_BUTTON
    value: true
mapping:
  OAUTH2_PROXY_REDIRECT_URL: ${OAUTH2_PROXY_INGRESS_URL}/oauth2/callback
```

Generate `YOUR_COOKIE_SECRET` by running `python -c 'import os,base64; print(base64.urlsafe_b64encode(os.urandom(16)).decode())'`.

Follow [the OAuth2 Proxy docs to set up Google OAuth2 credentials](https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/oauth_provider#google-auth-provider) to get `YOUR_CLIENT_ID` and `YOUR_CLIENT_SECRET`.

When you set up your Google OAuth2 credentials, you will be asked for the authorized JavaScript origin and redirect URI.

```
Authorized redirect URIs is the location of oauth2/callback ex: https://internal.yourcompany.com/oauth2/callback
```

As each Release environment generates its own domain, you can handle this using environment handles or by updating environment variables.

### Using environment handles

Release [environment handles](https://docs.releasehub.com/reference-documentation/account-settings/environment-handles) is probably the best bet for truly ephemeral environments with OAuth2 support.

You can predefine a handful of environment names like `dev1`, `dev2`, `dev3`, and so on, or `jupiter`, `mars`, `venus`. Then you can predefine your OAuth2 credentials for each of these predefined environments and your domains will match up correctly.

### Updating environment variables

If you don't want to use environment handles, you can deploy a new environment in Release as normal and once that new environment is created, you can plug the generated domain into your OAuth2 settings, update the environment variables for that specific environment, and redeploy it.

The environment will restart with the correct OAuth2 settings for that temporary domain. The settings will work until that environment disappears.

## Accessing your service

Once you have configured OAuth2, you can access the generated URL (in our case, `https://web-jupiter-mydomain.com/`) and you will be automatically redirected to the Google Login screen.

Log in with an email that belongs to one of the domains that you configured your OAuth2 credentials for, and you should be redirected to your service.

## Further Configuration

Take a look at all the [configuration options](https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/overview#command-line-options) available for OAuth2.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.release.com/guides-and-examples/common-setup-examples/opensource-oauth-proxy.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.