A reverse proxy to be run on development machines that allows transparent access to APIs and other HTTP resources behind an oauth2_proxy authenticating reverse proxy.
After authenticating via an OpenID Connect identity provider in the default browser, the dev proxy transparently adds the authentication cookie used by oauth2_proxy to requests directed to the dev proxy.
- No need to modify API clients to add credentials
- No need to store/manage credentials on development machines
- Authentication via identity provider
- No manually managed credentials on proxy (e.g. basic auth htpasswd file)
- Centralized user managemnent via provider
- Convenience: Authentication in default browser to leverage active identity provider session
- Start the dev proxy:
oauth2-dev-proxy <TARGET BASE URL>, e.g.oauth2-dev-proxy https://api-staging.example.com - The dev proxy automatically opens the identity provider's page in your default browser.
- Log in to your identity provider - if you're already logged in there, authentication may happen without manual interaction.
- The proxy shows a success browser page including the local HTTP endpoint you can use for accessing the API you provided in step 1.
Example success message in the browser:
Authentication complete. You can now use the proxy.
Proxy URL: http://127.0.0.1:8124
Upstream: https://api-staging.example.com
You can close this window.
Example output in the shell:
2018/07/10 08:29:45 Please authenticate in your browser via our identity provider.
2018/07/10 08:29:46 Authentication complete. You can now use the proxy.
Proxy URL: http://127.0.0.1:8124
Upstream: https://api-staging.example.com
The proxy will automatically terminate in 12 hours (reauthentication required)
Download the binary from the releases page and make it executable:
VERSION="0.0.1"; OS="darwin" # or linux or windows
curl --silent --location https://github.com/FRI-DAY/oauth2-dev-proxy/releases/download/v${VERSION}/oauth2-dev-proxy_${VERSION}_${OS}_amd64 \
> /usr/local/bin/oauth2-dev-proxy && \
chmod +x /usr/local/bin/oauth2-dev-proxy
go get github.com/FRI-DAY/oauth2-dev-proxy
You deploy oauth2_proxy as ususal, the only difference is to set a special redirect URL:
-redirect-url=http://127.0.0.1:8123/oauth2/callback
You also need to allow this redirect URL in your identity provider's configuration.
The following diagram shows HTTP requests made by the different components.
Development machine
+------------------------------------------+ +--------------+ +-----------------+
| | | | | |
| API Client +-------> oauth2-dev-proxy +----> | oauth2-proxy | +-> | Service (API) |
| (e.g. curl) ^ | | | | |
| | | +------+-------+ +-----------------+
| | | |
| Browser +-----------------+ | +------v-----------+
| +-----------------------------------> | |
| | | Identity Provider|
+------------------------------------------+ | |
+------------------+
The dev proxy uses a trick to allow authentication with the identity provider in the local browser, while making the requests to the oauth2_proxy directly, so the dev proxy can capture the authentication cookie from oauth2_proxy.
The trick requires a separate oauth2_proxy instance to be deployed with a redirect URL of http://127.0.0.1:8123/oauth2/callback.
From the dev proxy's point of view, the process works like this:
- Start an HTTP server on port 8123
- Request
TARGET/oauth2/start- Store the CSRF cookie
- Note the identity provider URL the proxy redirects to
- Open the identity provider URL in the local default browser
- The user authenticates to the identity provider
- The identity provider redirects to
http://127.0.0.1:8123/oauth2/callback - Forward the
/oauth2/callbackrequest to the oauth2_proxy, including the auth code- From the response, note the
_oauth2_proxycookie
- From the response, note the
- Start a reverse proxy server to the target URL on another port, configured to transparently add the
_oauth2_proxycookie to all requests - After the cookie expires, shut down the proxy