For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

OAuth2 Proxy

Add user authentication with GitHub, Google, Azure AD, and other OAuth providers by integrating agentgateway with OAuth2 Proxy.

Agentgateway can integrate with OAuth2 Proxy to add browser authentication through GitHub, Google, Azure AD, and other OAuth providers. Agentgateway uses an external authorization (extAuthz) policy to send authentication checks to OAuth2 Proxy, which handles the redirect to the provider’s login page.

This guide uses GitHub as the example provider. If you use another provider, only the OAuth2 Proxy flags change.

Before you begin

• Install agentgateway.
• Install Docker and make sure it is running.
• Have a GitHub account so that you can create an OAuth app.

Step 1: Create a GitHub OAuth application

1. Go to GitHub Developer Settings.
2. Click OAuth Apps > New OAuth App.
3. Fill in the application details.
   • Application name: agentgateway dev, or any name you choose.
   • Homepage URL: http://localhost:3000
   • Authorization callback URL: http://localhost:4180/oauth2/callback
4. Click Register application.
5. Copy the Client ID.
6. Click Generate a new client secret and copy the Client Secret.

Step 2: Set up your environment

Create a working directory and set your GitHub OAuth credentials.

mkdir oauth2-proxy-test && cd oauth2-proxy-test

export OAUTH2_PROXY_CLIENT_ID=your-github-client-id
export OAUTH2_PROXY_CLIENT_SECRET=your-github-client-secret

# Generate a random cookie secret
export OAUTH2_PROXY_COOKIE_SECRET=$(python3 -c 'import os,base64; print(base64.b64encode(os.urandom(32)).decode()[:32])')

Step 3: Start OAuth2 Proxy

1. Run OAuth2 Proxy in Docker.

   docker run -d --name oauth2-proxy \
     -p 4180:4180 \
     --add-host=host.docker.internal:host-gateway \
     -e OAUTH2_PROXY_CLIENT_ID=$OAUTH2_PROXY_CLIENT_ID \
     -e OAUTH2_PROXY_CLIENT_SECRET=$OAUTH2_PROXY_CLIENT_SECRET \
     -e OAUTH2_PROXY_COOKIE_SECRET=$OAUTH2_PROXY_COOKIE_SECRET \
     -e OAUTH2_PROXY_COOKIE_SECURE=false \
     quay.io/oauth2-proxy/oauth2-proxy:latest \
     --provider=github \
     --email-domain=* \
     --upstream=file:///dev/null \
     --http-address=0.0.0.0:4180 \
     --set-xauthrequest \
     --reverse-proxy=true

2. Verify that OAuth2 Proxy is running.

   docker logs oauth2-proxy

Step 4: Create the agentgateway configuration

Create a config.yaml file. The configuration routes /oauth2/* requests to OAuth2 Proxy for login and callback handling, and protects the MCP application with an extAuthz policy that checks authentication and extracts the user’s identity.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
frontendPolicies:
  accessLog:
    add:
      # Log the authenticated user's identity and email
      oauth.user: extauthz.oauthUser
      oauth.email: extauthz.oauthEmail

binds:
- port: 3000
  listeners:
  - name: default
    protocol: HTTP
    routes:
    # Route OAuth2 Proxy endpoints (login, callback, and so on)
    - name: oauth2-proxy
      matches:
      - path:
          pathPrefix: /oauth2
      backends:
      - host: localhost:4180

    # Protected MCP application
    - name: application
      backends:
      - mcp:
          targets:
          - name: everything
            stdio:
              cmd: npx
              args: ["@modelcontextprotocol/server-everything"]
      policies:
        cors:
          allowOrigins: ["*"]
          allowHeaders: ["*"]
          exposeHeaders: ["Mcp-Session-Id"]
        extAuthz:
          host: localhost:4180
          protocol:
            includeRequestHeaders:
            - cookie
            http:
              # Check authentication status
              path: |
                "/oauth2/auth"
              # Redirect unauthenticated users to login
              redirect: |
                "/oauth2/start?rd=" + request.path
              addRequestHeaders:
                x-forwarded-host: request.host
              includeResponseHeaders:
              - x-auth-request-user
              - x-auth-request-email
              # Extract user info from OAuth2 Proxy response headers
              metadata:
                oauthUser: response.headers["x-auth-request-user"]
                oauthEmail: response.headers["x-auth-request-email"]

The following table describes the key settings in the configuration.

Step 5: Start agentgateway

agentgateway -f config.yaml

Step 6: Test the authentication flow

1. Send an unauthenticated request. Because the request has no session cookie, agentgateway redirects it to the login flow.

   curl -i http://localhost:3000/mcp

   Example output:

   HTTP/1.1 302 Found
   location: /oauth2/start?rd=/mcp

2. Test the flow in a browser.

   1. Open http://localhost:3000/mcp.
   2. You are redirected to GitHub for authentication.
   3. After you log in, you are redirected back to the MCP endpoint.
   4. The agentgateway logs show the authenticated user’s identity and email in the oauth.user and oauth.email access log fields.

Other providers

OAuth2 Proxy supports many providers. The agentgateway configuration stays the same, but you should follow the OAuth2 Proxy documentation for the provider-specific flags and callback settings.

Production considerations

For production deployments, consider the following.

• Set OAUTH2_PROXY_COOKIE_SECURE=true and use HTTPS.
• Restrict email-domain to your organization’s domain.
• Use a persistent cookie secret instead of a randomly generated one.
• See the OAuth2 Proxy documentation for additional security options.

Cleanup

Stop and remove the OAuth2 Proxy container, then remove the working directory.

docker stop oauth2-proxy && docker rm oauth2-proxy
cd .. && rm -rf oauth2-proxy-test

Learn more