Skip to content

Commit 0273ddf

Browse files
committed
Add README
1 parent dd6d852 commit 0273ddf

1 file changed

Lines changed: 104 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# OAuth2 API Proxy for Development
2+
3+
A reverse proxy to be run on development machines that allows transparent access to APIs and other HTTP resources behind an [oauth2_proxy](https://github.com/bitly/oauth2_proxy) authenticating reverse proxy.
4+
5+
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.
6+
7+
## Why?
8+
9+
* No need to modify API clients to add credentials
10+
* No need to store/manage credentials on development machines
11+
* Authentication via identity provider
12+
- No manually managed credentials on proxy (e.g. basic auth htpasswd file)
13+
- Centralized user managemnent via provider
14+
* Convenience: Authentication in default browser to leverage active identity provider session
15+
16+
## Usage
17+
18+
1. Start the dev proxy: `oauth2-dev-proxy <TARGET BASE URL>`, e.g. `oauth2-dev-proxy https://api-staging.example.com`
19+
2. The dev proxy automatically opens the identity provider's page in your default browser.
20+
3. Log in to your identity provider - if you're already logged in there, authentication may happen without manual interaction.
21+
4. The proxy shows a success browser page including the local HTTP endpoint you can use for accessing the API you provided in step 1.
22+
23+
Example success message in the browser:
24+
25+
```
26+
Authentication complete. You can now use the proxy.
27+
28+
Proxy URL: http://127.0.0.1:8124
29+
Upstream: https://api-staging.example.com
30+
31+
You can close this window.
32+
```
33+
34+
Example output in the shell:
35+
36+
```
37+
2018/07/10 08:29:45 Please authenticate in your browser via our identity provider.
38+
2018/07/10 08:29:46 Authentication complete. You can now use the proxy.
39+
40+
Proxy URL: http://127.0.0.1:8124
41+
Upstream: https://api-staging.example.com
42+
43+
The proxy will automatically terminate in 12 hours (reauthentication required)
44+
```
45+
46+
## Installation
47+
48+
### Binary
49+
50+
Download the binary from the [releases page](https://github.com/FRI-DAY/oauth2-dev-proxy/releases) and make it executable:
51+
52+
VERSION="0.0.1-alpha1"; OS="darwin" # or linux or windows
53+
curl --silent --location https://github.com/FRI-DAY/oauth2-dev-proxy/releases/download/v${VERSION}/oauth2-dev-proxy_${VERSION}_${OS}_amd64 \
54+
> /usr/local/bin/oauth2-dev-proxy && \
55+
chmod +x /usr/local/bin/oauth2-dev-proxy
56+
57+
### Source
58+
59+
go get github.com/FRI-DAY/oauth2-dev-proxy
60+
61+
## oauth2_proxy Setup
62+
63+
You deploy [oauth2_proxy](https://github.com/bitly/oauth2_proxy) as ususal, the only difference is to set a special redirect URL:
64+
65+
-redirect-url=http://127.0.0.1:8123/oauth2/callback
66+
67+
You also need to allow this redirect URL in your identity provider's configuration.
68+
69+
## Architecture
70+
71+
The following diagram shows HTTP requests made by the different components.
72+
73+
```
74+
Development machine
75+
+------------------------------------------+ +--------------+ +-----------------+
76+
| | | | | |
77+
| API Client +-------> oauth2-dev-proxy +----> | oauth2-proxy | +-> | Service (API) |
78+
| (e.g. curl) ^ | | | | |
79+
| | | +------+-------+ +-----------------+
80+
| | | |
81+
| Browser +-----------------+ | +------v-----------+
82+
| +-----------------------------------> | |
83+
| | | Identity Provider|
84+
+------------------------------------------+ | |
85+
+------------------+
86+
```
87+
88+
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*.
89+
90+
The trick requires a separate *oauth2_proxy* instance to be deployed with a redirect URL of `http://127.0.0.1:8123/oauth2/callback`.
91+
92+
From the dev proxy's point of view, the process works like this:
93+
94+
1. Start an HTTP server on port 8123
95+
2. Request `TARGET/oauth2/start`
96+
- Store the CSRF cookie
97+
- Note the identity provider URL the proxy redirects to
98+
3. Open the identity provider URL in the local default browser
99+
4. The user authenticates to the identity provider
100+
5. The identity provider redirects to `http://127.0.0.1:8123/oauth2/callback`
101+
6. Forward the `/oauth2/callback` request to the *oauth2_proxy*, including the auth code
102+
- From the response, note the `_oauth2_proxy` cookie
103+
7. Start a reverse proxy server to the target URL on another port, configured to transparently add the `_oauth2_proxy` cookie to all requests
104+
8. After the cookie expires, shut down the proxy

0 commit comments

Comments
 (0)
⌂ 换网址