https://github.com/stack-auth/auth-proxy
https://github.com/stack-auth/auth-proxy
Last synced: 9 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/stack-auth/auth-proxy
- Owner: stack-auth
- License: mit
- Created: 2024-10-07T20:14:58.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-11-08T18:53:09.000Z (about 1 year ago)
- Last Synced: 2024-11-08T19:38:55.633Z (about 1 year ago)
- Language: JavaScript
- Size: 404 KB
- Stars: 17
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# auth-proxy
auth-proxy is a simple one-command proxy that authenticates your HTTP requests and redirects to a pre-built sign-in page if a user is not authenticated.
## Setup
First, sign in and create your API keys on [Stack Auth cloud](https://stack-auth.com/) (or you can [host it locally](https://github.com/stack-auth/stack)). Stack Auth is the open-source Auth0 alternative.
Then, start your application server on port `3000` and run the proxy with the following command:
```sh
docker run \
-e NEXT_PUBLIC_STACK_PROJECT_ID= \
-e NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY= \
-e STACK_SECRET_SERVER_KEY= \
-e SERVER_PORT=3000 \
-e PROXY_PORT=3001 \
-p 3001:3001 \
stackauth/auth-proxy:latest
```
You can now access your application server at [localhost:3001](http://localhost:3001) and all the routes under the protected patterns will only be accessible by authenticated users.
The protected patterns are URL patterns (check out the syntax [here](https://github.com/snd/url-pattern)). Don't forget to include the leading `/` and handling the trailing `/`. For example, if you want to protect everything under `/a` and only the route `/b` (not `/b/c`), you can run
`... stackauth/auth-proxy:latest "/a(/*)" "/b(/)"`.
If you don't have an application server, you can run our example server to play around with the proxy
Start the example server on port 3000:
```sh
git clone git@github.com:stack-auth/auth-proxy.git
cd express-example-server
npm install
npm run dev
```
You can check out the original server without the proxy at [localhost:3000](http://localhost:3000).
Now, open a new terminal and run the proxy server on port 3000:
```sh
docker run \
-e NEXT_PUBLIC_STACK_PROJECT_ID= \
-e NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY= \
-e STACK_SECRET_SERVER_KEY= \
-e SERVER_PORT=3000 \
-e PROXY_PORT=3001 \
-p 3001:3001 \
stackauth/auth-proxy:latest "/protected(/*)"
```
You can explore the proxy at [localhost:3001](http://localhost:3001).
## Features
If you access a protected page through the proxy without being authenticated, you will be redirected to a sign-in page like this (customizable on the dashboard):
After signing in, you will be able to access the protected pages.
To retrieve user information from your webpage, you can read the headers as shown in this JavaScript Express + handlebars example (works similarly on other languages/frameworks):
```js
const express = require("express");
const handlebars = require("handlebars");
const app = express();
const template = handlebars.compile(`
`);
app.get('/', (req, res) => {
const authenticated = !!req.headers['x-stack-authenticated'];
const displayName = req.headers['x-stack-user-display-name'] || '';
const html = template({ authenticated, displayName });
res.send(html);
});
app.listen(3000);
```
Available headers:
- `x-stack-authenticated`: "true" if authenticated; not present otherwise.
- `x-stack-user-id`
- `x-stack-user-primary-email`
- `x-stack-user-display-name`
Available URLs (redirect your app server to these URLs as needed):
- `/handler/sign-in`
- `/handler/sign-up`
- `/handler/sign-out`: Clears cookies and redirects back to your homepage.
- `/handler/account-settings`: Users can update their email, display name, password, etc.
- `/handler/me`: If you make a request to this URL with the user's session cookie, you will get the client information in JSON. This is useful for client-side apps.
## How It Works
When a request is received, the logic is as follows:
```
if url is /handler/*:
render the auth pages
else:
if user is not authenticated && url is protected:
redirect to /handler/sign-in
else:
forward the request to your server with user info headers
```
```mermaid
graph TB
Client((Request))
Proxy[Auth Proxy]
YourServer[Your Server]
StackAuthServer[Stack Auth Server]
Client --> Proxy
Proxy --> |"add user info headers"| YourServer
Proxy --> StackAuthServer
StackAuthServer --> Proxy
classDef container fill:#1168bd,stroke:#0b4884,color:#ffffff
class StackAuthServer container
class YourServer container
class Proxy container
```