From 90f6a0ab7e1fc3ff088ac151b3711387bc2441a2 Mon Sep 17 00:00:00 2001 From: geoffsee <> Date: Fri, 6 Jun 2025 09:39:08 -0400 Subject: [PATCH] Update README.md --- README.md | 270 +++++++++++------------------------------------------- 1 file changed, 53 insertions(+), 217 deletions(-) diff --git a/README.md b/README.md index 59c6bcc..7b60301 100644 --- a/README.md +++ b/README.md @@ -1,251 +1,87 @@ # axum-tower-sessions-edge -Formerly `zitadel-session-worker` -> Original commit history availble by request. +> OAuth 2.0 Proxy built with Axum and Tower. Targets `wasm32-unknown-unknown` -## Development History -Below is a curated list of key milestones in the development of this project, reflecting significant updates and features added over time (reverse-chronological) -- Implement new session functionality - 5/9/25 -- Add error handlers for introspection - 5/9/25 -- Improve error handling for smoother operation - 5/8/25 -- Ensure compatibility with Safari - 5/8/25 -- Deploy latest changes - 5/8/25 -- Deploy updates - 5/8/25 -- Evaluate next steps for project direction - 5/6/25 -- Enable effective cache usage - 5/6/25 -- Update introspection handler to prioritize cache - 5/6/25 -- Revise session expiry and add proxy status API tests - 5/6/25 -- Confirm basic functionality of recent changes - 5/6/25 -- Resolve issues in _cyberspace_ context (placeholder for explicatives) - 5/5/25 -- Complete full login cycle - 5/5/25 -- Add Cloudflare introspection cache - 5/5/25 -- Implement minor updates - 5/3/25 -- Enhance Cloudflare session storage backend - 4/30/25 -- Fix Tower session extractor and refactor session creation - 4/30/25 -- Perform code cleanup - 4/30/25 -- Optimize for API application compatibility - 4/29/25 -- Establish basic session functionality - 4/29/25 -- Make progress on key features - 4/29/25 -- Experiment with redirect configurations - 4/29/25 -- Debug callback issues; session store functional in callback - 4/28/25 -- Continue work on callback implementation - 4/28/25 -- Complete proxy target compilation - 4/28/25 -- Reintroduce session middleware - 4/28/25 -- Remove sensitive secrets from codebase - 4/28/25 -- Implement dynamic incoming URL handling - 4/28/25 -- Correct KV storage naming - 4/27/25 -- Add callback functionality - 4/27/25 -- Introduce project structure improvements - 4/26/25 -- Address client returning 403 error - 4/26/25 -- Advance project development - 4/26/25 -- Clean up code and rename functions for clarity - 4/24/25 -- Integrate session manager and introspection features - 4/24/25 -- Add root path configuration - 2/2/25 -- Fetch provider metadata successfully - 2/2/25 -- Update type definition for introspected user - 2/1/25 -- Confirm application runs successfully - 2/1/25 -- Reintegrate test suite - 2/1/25 -- Achieve successful compilation - 2/1/25 -- Create random development checkpoint - 2/1/25 -- Initialize project repository - 2/1/25 +Proxies incoming requests for defined routes and forwards traffic to the service defined as `PROXY_TARGET`. +Configuration is modified by changing `.dev.vars`, `wrangler.jsonc`, or `secrets.json`. It's not perfect yet, but it's powerful. +## Features +- [OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749) +- [Proof Key for Code Exchange (PKCE)](https://datatracker.ietf.org/doc/html/rfc7636) +- [OAuth 2.0 Token Introspection](https://datatracker.ietf.org/doc/html/rfc7662) -> ⚠️ **WARNING**: This project is currently in development and **NOT** production-ready. Use at your own risk. It may -> contain bugs, security vulnerabilities, or incomplete features. This should -> serve as a starting point for anyone building similar technology. All feedback is welcome. +## Todo +- Proof compliance +- Expand configuration interface +- Zero-config development environment -A Rust Cloudflare Worker that provides authentication and session management for web applications using ZITADEL as the identity provider. It adopts the implementation for oauth2 token introspection from [smartive/zitadel-rs](https://github.com/smartive/zitadel-rust). - -## Overview - -This project is a Rust-based Cloudflare Worker that acts as an authentication proxy for web applications. It handles: - -- oauth2/oidc w/PKCE via Zitadel -- Session management using Cloudflare KV storage -- Token introspection and validation -- Proxying authenticated requests to backend services - -When deployed, the worker sits between your users and your application services. It: -1. Intercepts incoming requests -2. Verifies if the user has a valid session -3. If not, redirects to ZITADEL for authentication -4. After successful authentication, creates a session and proxies the request to your service -5. For subsequent requests, validates the session and proxies authenticated requests - - -> **Note**: Caches are used by the introspection and session modules. They prevent excessive r/w. - -## Prerequisites - -- [Rust](https://www.rust-lang.org/tools/install) (latest stable version) -- LLVM and clang -- [Bun](https://bun.sh/) JavaScript runtime -- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/) for Cloudflare Workers development -- ZITADEL Administrator Access - -## Installation - -1. Clone the repository: +## Quickstart ```bash - git clone - cd zitadel-session-worker - ``` +git clone https://github.com/seemueller-io/axum-tower-sessions-edge.git +cd axum-tower-sessions-edge +bun install +# Create a `.dev.vars` file in the project root with the following variables: +#CLIENT_ID="your-client-id" +#CLIENT_SECRET="your-client-secret" +#AUTH_SERVER_URL="https://your-zitadel-instance-url" +#ZITADEL_ORG_ID="your-organization-id" +#ZITADEL_PROJECT_ID="your-project-id" +#APP_URL="http://localhost:3000" +#DEV_MODE="true" -2. Install dependencies: - ```bash - # Install JavaScript dependencies - bun install - ``` +# Update the wrangler.jsonc and replace the value of PROXY_TARGET with a worker script name. -## Configuration - -> **Note**: There is a docker compose file with Zitadel in this repository that can be used for testing. - -### Environment Variables - -Create a `.dev.vars` file in the project root with the following variables: - -``` -CLIENT_ID="your-client-id" -CLIENT_SECRET="your-client-secret" -AUTH_SERVER_URL="your-zitadel-instance-url" -ZITADEL_ORG_ID="your-organization-id" -ZITADEL_PROJECT_ID="your-project-id" -APP_URL="http://localhost:3000" -DEV_MODE="true" +npx wrangler dev +# Open `http://localhost:3000` in your browser. If everything is configured correctly, you should be taken to a Zitadel login page. ``` -### Wrangler Configuration +### Extras -- `wrangler.jsonc` - Base configuration +Run your own Zitadel: `docker compose up -d` +> You will need to configure: +> - Organization +> - Project +> - Application. _Choose PKCE (with code)_ -## Development - -### Running Locally - -```bash -# Start the development server -bun run dev -``` - -This will start the worker on `localhost:3000`. ### Building - +Sometimes the error messages are challenging to surface. Here are some alternative build commands that might help. ```bash -# Build the project +# Default build +npx wrangler build + +# Build command as defined in wrangler.jsonc cargo clean && cargo install -q worker-build && worker-build --release + +# Hacky but effective (targets the common runtime) +cargo build --release --target wasm32-unknown-unknown ``` -## Deployment - -### Deploying to Cloudflare - -```bash -# Deploy to development environment -bun run deploy:dev - -# Deploy with updated secrets -bun run deploy:dev:secrets -``` - -### Viewing Logs - -```bash -# View logs from the deployed worker -bun run tail:dev -``` - -## Integration with Your Application - -To integrate this worker with your existing application: - -1. **Configure Cloudflare**: - - Set up a Cloudflare Worker route that points to your application domain - - Deploy this worker to that route - -2. **Configure ZITADEL**: - - Create an application in ZITADEL - - Configure the redirect URI to `https://your-worker-domain/login/callback` - - Get the client ID and client secret - -3. **Configure this Worker**: - - Update the environment variables with your ZITADEL credentials - - Set the `APP_URL` to your application's URL - - Set an http route in `wrangler.jsonc` - -4. **Access Control**: - - The worker will automatically handle authentication - - Your application will receive authenticated requests with user information - - You can access user information via the `/api/whoami` endpoint - -## Testing - -The project uses Rust's built-in testing framework with tokio for async tests. - -```bash -# Run all tests -cargo test -``` - -### Adding New Tests - -1. For unit tests, add them to the `tests` module in the relevant source file -2. For async tests, use the `#[tokio::test]` attribute -3. Follow the existing pattern of testing both success and error cases -4. Mock external dependencies when necessary - -## Debugging - -1. For local development, use `console_log!` macros to output debug information -2. View logs in the wrangler development console -3. For deployed workers, use `bun run tail:dev` to stream logs -4. Check the `/api/whoami` endpoint to verify user authentication and session data - ## Project Structure - - `src/` - Rust source code - `api/` - API endpoints and routing - `axum_introspector/` - Axum framework integration for token introspection - `credentials/` - Credential management - `oidc/` - OpenID Connect implementation - `session_storage/` - Session storage implementations - - `utilities.rs` - Utility functions - - `lib.rs` - Main entry point and worker setup - -## Contributing - -Contributions to this project are welcome! Here are some guidelines: - -1. **Fork the repository** and create your branch from `main` -2. **Install dependencies** and ensure you can build the project -3. **Make your changes** and add or update tests as necessary -4. **Ensure tests pass** by running `cargo test` -5. **Format your code** with `cargo fmt` -6. **Submit a pull request** with a clear description of your changes - -### Code Style - -- Follow Rust's standard code style and idioms -- Use `cargo fmt` to format code -- Use `cargo clippy` for linting + - `utilities.rs` - Common utility functions + - `lib.rs` - Server ## Acknowledgements This project is made possible thanks to: -- **ZITADEL**: For providing the robust identity management platform that powers this authentication proxy -- **Smartive**: For [zitadel-rs](https://github.com/smartive/zitadel-rust) -- **Cloudflare**: For their Workers platform and KV storage solution -- **Fermyon Spin** https://github.com/fermyon/http-auth-middleware (Reference implementation) -- **Open Source Community**: For the various dependencies and tools that make this project possible: - - The Rust ecosystem and its crates - - The Axum web framework - - The Tower middleware ecosystem - - Various other open-source projects listed in our dependencies - -I appreciate the hard work and dedication of all the developers and organizations that contribute to the open-source -ecosystem. +- **Open Source Community**: For the various dependencies and tools that make this project possible. +- [The Rust ecosystem](https://www.rust-lang.org/ecosystem) and its crates +- [ZITADEL](https://zitadel.com/): For providing the robust identity management platform that powers this authentication + proxy +- [Smartive](https://github.com/smartive): For [zitadel-rs](https://github.com/smartive/zitadel-rust) +- [Cloudflare](https://github.com/cloudflare): For their [Workers](https://workers.cloudflare.com/) platform and KV storage + solution +- [Fermyon/Spin](https://www.fermyon.com/spin): [http-auth-middleware](https://github.com/fermyon/http-auth-middleware) (Reference implementation) +- [The Axum web framework](https://github.com/tokio-rs/axum) +- [The Tower middleware ecosystem](https://github.com/tower-rs) +- Various other open-source projects listed in [Cargo.toml](./Cargo.toml) ## License