🔐 loco-keycloak-auth

A plug-and-play Keycloak authentication layer for Loco.rs, powered by 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:

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

Note

: If you’re using a local path for development:

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

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.

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

use loco_keycloak_auth::Keycloak;

pub async fn profile_handler(
    State(_ctx): State<AppContext>,
    Extension(token): Extension<KeycloakToken<String>>,
) -> Result<Response> {
    format::json(token.subject)
}

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

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

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

2. Use in your Loco project with a local path

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

3. Run tests if there are any

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 ecosystem
• Powered by axum-keycloak-auth

---

📫 Contact

Questions? Ideas? Want to contribute together?
Open an issue or reach out on GitHub Discussions.