Using OAuth Proxy

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 from the awesome-release library to demonstrate.

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

---
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.

- 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:

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

And change it to the following:

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

The Application Template should now look like this:

---
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.

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

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 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 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 available for OAuth2.