# 🔐 loco-keycloak-auth

A plug-and-play Keycloak authentication layer for [Loco.rs](https://github.com/loco-rs/loco), powered by [axum-keycloak-auth](https://crates.io/crates/axum-keycloak-auth).  
This crate allows you to easily add secure Keycloak authentication to your Loco web app, with full control over protected routes and clean YAML-based config.

---

## ✨ Features

- ✅ Simple integration with Loco initializers
- ✅ Based on `axum-keycloak-auth`
- ✅ Configurable via `config.yaml`
- ✅ Supports `Block` and `Pass` passthrough modes
- ✅ Designed to be flexible: apply middleware only where you want it
- ✅ Ideal for securing internal APIs or user-facing endpoints

---

## ⚙️ Installation

Add to your `Cargo.toml`:

```toml
[dependencies]
loco-keycloak-auth = "0.1"
```

> **Note**: If you’re using a local path for development:

```toml
loco-keycloak-auth = { path = "../loco-keycloak-auth" }
```

or just do `cargo add loco-keycloak-auth`

## 🛠 Setup

### 1. Add Keycloak config to your `config/config.yaml`

```yaml
settings:
  keycloak_settings:
    url: "https://keycloak.example.com"
    realm: "myrealm"
    expected_audiences:
      - "account"
    passthrough_mode: "Block" # or "Pass"
    persist_raw_claims: false
```

### 2. Add the initializer to your `App` in `app.rs` if you want to have all routes protected.

```rust
use loco_keycloak_auth::KeycloakAuthInitializer;

#[async_trait]
impl Hooks for App {
    async fn initializers(_ctx: &AppContext) -> Result<Vec<Box<dyn Initializer>>> {
        let keycloak_auth = loco_keycloak_auth::initializer::KeycloakAuthInitializer {};
        Ok(vec![Box::new(keycloak_auth)])
    }
}
```

---

## 🔒 Usage

### Protect specific endpoints

```rust
use loco_keycloak_auth::Keycloak;

fn routes(ctx: &AppContext) -> Routes {
    let keycloak = Keycloak::from_context(ctx).expect("Failed to create Keycloak layer");

    Routes::new()
        .prefix("secure")
        .add("/profile", get(profile_handler).layer(keycloak.layer))
}
```

---

## 📦 API

### Settings struct

```rust
pub struct KeycloakSettings {
    pub url: String,
    pub realm: String,
    pub expected_audiences: Vec<String>,
    pub passthrough_mode: PassthroughMode, // "Block" or "Pass"
    pub persist_raw_claims: bool,
}
```

> `PassthroughMode` lets you decide whether unauthenticated requests should be blocked or passed along.

---

## 🤝 Contributing

We welcome contributions! Here's how to get started:

### 1. Clone and link locally

```bash
git clone https://github.com/GKaszewski/loco-keycloak-auth
cd loco-keycloak-auth
```

### 2. Use in your Loco project with a local path

```toml
[dependencies]
loco-keycloak-auth = { path = "../loco-keycloak-auth" }
```

### 3. Run tests if there are any

```bash
cargo test
```

### 4. Submit a PR 🚀

Please open an issue or discussion first for larger feature proposals or breaking changes.

---

## 📄 License

MIT

---

## 🙌 Credits

- Built with ❤️ for the [Loco.rs](https://github.com/loco-rs/loco) ecosystem
- Powered by [axum-keycloak-auth](https://github.com/lpotthast/axum-keycloak-auth)

---

## 📫 Contact

Questions? Ideas? Want to contribute together?  
Open an issue or reach out on [GitHub Discussions](https://github.com/GKaszewski/loco-keycloak-auth/discussions).