OAuth2 Proxy - Azure IDP integration for any app

Introduction

OAuth2 Proxy is a tool increasingly being appreciated by developers for its robust functionality in securing applications and its ability to provide a seamless authentication and authorization layer. With its capacity to use multiple identity providers including Google, Azure, Okta and Github and others, OAuth2 Proxy effectively stands as a trusted tool for securing applications. In this blog post, we will introduce OAuth2 Proxy, its functionalities, it’s working, and wrap up with a simplistic example.

What is OAuth2 Proxy?

OAuth2 Proxy is an open-source application that provides an authentication layer using OAuth2 for applications that do not possess inherent authentication features. In essence, it gives applications a layer of security through user validation, which developers can use in conjunction with HTTP reverse proxies like NGINX to ensure safe usage.

Working Mechanism:

OAuth2 Proxy successfully authenticates users through their respective identity providers and then transfers the authentication data while redirecting them to the actual web service. With this, you don’t need to manage server session state as OAuth2 Proxy handles the session management independently. This is especially helpful when using older application stacks that don’t benefit from more modern libraries to handle this.

OAuth2 Proxy Installation:

Installing OAuth2 Proxy is a straightforward process and can be simply done downloading precompiled binaries from the GitHub Releases page. Alternatively, it can be installed using Docker, Helm, or from Source. In our example, we’ll be using the Docker container.

OAuth2 Proxy Configuration:

OAuth2 Proxy can use a configuration file e.g. oauth2_proxy.cfg, command-line options or environment variables control its function. The configuration will specify the settings related to the OAuth provider, like client secret, client ID, and more. Check out the detailed settings and configurations in the official OAuth2 Proxy documentation.

Example usage:

In this example, we’ll use:

  • Docker-compose to spin up our stack
  • Environment variables to configure it
  • Azure as the identity provider
version: '2.4'

  your-app:
    image: your-image:latest

  oauth2-proxy:
    image: bitnami/oauth2-proxy:latest
    depends_on:
      - oauth2-proxy-redis
      - your-app
    command:
      - --https-address
      - 0.0.0.0:443
    ports:
      - '0.0.0.0:443:443'
    volumes:
      - /path/to/certificates:/certificates
    environment:
      # Where to send authenticated traffic, replace with service name of the actual application
      - OAUTH2_PROXY_UPSTREAMS=http://your-app:80
      # Set Azure default options
      - OAUTH2_PROXY_PROVIDER=azure
      # The domain for the cookie
      - OAUTH2_PROXY_COOKIE_DOMAINS=<<your domain e.g. example.com>>
      # Client ID from application registration in Azure
      - OAUTH2_PROXY_CLIENT_ID=<<Client ID from Azure>>
      # Client Secret from application registration in Azure
      - OAUTH2_PROXY_CLIENT_SECRET=<<API Client Secret from Azure>>
      # Tenant ID from application registration in Azure
      - OAUTH2_PROXY_AZURE_TENANT=<<Tenant ID from Azure>>
      # Issuer URL including Tenant ID from application registration in Azure
      - OAUTH2_PROXY_OIDC_ISSUER_URL=https://login.microsoftonline.com/<<Tenant ID from Azure>>/v2.0
      # The encryption secret for stored cookies e.g. from http://www.unit-conversion.info/texttools/random-string-generator
      - OAUTH2_PROXY_COOKIE_SECRET=<<A random 32 byte string>>
      # Storing session tokens in redis
      - OAUTH2_PROXY_SESSION_STORE_TYPE=redis 
      - OAUTH2_PROXY_REDIS_CONNECTION_URL=redis://oauth2-proxy-redis:6379
      # Session cookie expiry time
      - OAUTH2_PROXY_COOKIE_REFRESH=30m
      # Don't show 'login' button, redirect straight to IDP
      - OAUTH2_PROXY_SKIP_PROVIDER_BUTTON=true 
      # Name of browser cookie
      - OAUTH2_PROXY_COOKIE_NAME=OA2P_SESSION
      # Allow cookie to be sent on cross-site requests
      - OAUTH2_PROXY_COOKIE_SAMESITE=lax
      # this skips auth for specific paths e.g. public APIs and healthcheck
      - OAUTH2_PROXY_SKIP_AUTH_ROUTES=^/public,^/health
      # Let OAuth2 Proxy terminate TLS, provide path to certificate and key:
      -  OAUTH2_PROXY_TLS_CERT_FILE=/certificates/domain.crt
      -  OAUTH2_PROXY_TLS_KEY_FILE=/certificates/domain.key

  oauth2-proxy-redis:
    image: bitnami/redis:latest
    ports:
     - 127.0.0.1:6379:6379
    environment:
      - ALLOW_EMPTY_PASSWORD=yes
    volumes:
      - oauth2-proxy-redis:/bitnami/redis/data

To get the Client ID, Client Secret and Tenant ID for this configuration:

  • Log in to Azure Portal
  • Navigate to App Registrations
  • Create a new registration:
    • Provide a name
    • Choose Single tenant if you want to restrict access to your email domain
    • Set a redirect URI:
      • Choose Web as the platform and set redirect URI as https://«yourappdomain.com»/oauth2/callback
      • For testing, you can set it to https://localhost/oauth2/callback

Once you register, find the first two fields in the Overview section of your app registration:

  • Application (client) ID
  • Directory (tenant) ID

To get the Client Secret, go to Certificates & secrets and create a new client secret:

  • Choose a secret name
  • Choose a sensible expiry e.g. 180 days

Upon creation, the secret will only be displayed only once. Copy the secret value and store it safely.

With the three values, complete the environment section of the docker compose definition. Start up your stack, e.g.

docker-compose up -d && docker-compose logs -f oauth2-proxy

With your stack running, navigate to your domain from an Incognito Window. You should immediately be redirected to a Microsoft login page. Authenticate with your credentials, complete multi-factor authentication if configured and upon successful login you’ll be redirected to your application.

Note headers should be included on all requests authenticated using OAuth2 Proxy, e.g.

  • X-Forwarded-User: email address of user.
  • X-Forwarded-Groups: UUIDs of the groups your user belongs to.
  • Token: JWT token

Conclusion:

OAuth2 Proxy is a powerful tool that helps developers enhance applications’ security through proper authentication. With the help of our basic example, we hope you have gained initial insight into its functioning and mechanism.

For a more detailed explanation and advanced use cases, head over to the official documentation.

OAuth2 Proxy greatly simplifies the security complexities, particularly for legacy applications running on stacks without support for OAuth/OIDC authentication.

Table of content

Share article with