guardian
A token-based authentication library for Elixir applications, supporting JWT and custom tokens.
What is guardian?
Guardian is an authentication library for Elixir applications built around token-based authentication, primarily using JSON Web Tokens (JWT) by default. It provides a flexible, functional system for securing web endpoints, channels, sockets, and other protocols, integrating seamlessly with Plug and Phoenix while remaining decoupled for broader use cases.
Elixir developers building web applications or APIs that require secure authentication, particularly those using the Phoenix framework or Plug-based systems. It is also suitable for developers implementing custom authentication schemes for non-web protocols like TCP/UDP.
Developers choose Guardian for its extensible, token-based architecture that supports multiple token types and configurations within a single application, along with advanced features like permission encoding and key rotation. Its pluggable design allows customization without imposing rigid structures, making it adaptable to complex authentication flows.
Overview
Elixir Authentication
Use Cases
Best For
- Securing Phoenix web endpoints and channels with token-based authentication.
- Implementing authentication for custom TCP/UDP protocols in Elixir applications.
- Building applications that require multiple token types (e.g., access and refresh tokens) within a single system.
- Integrating permission-based authorization scopes directly into authentication tokens.
- Managing advanced secret configurations, including key rotation and dynamic secret fetching.
- Creating custom authentication pipelines with Plug for complex or non-standard authentication flows.
Not Ideal For
- Applications requiring traditional session-based authentication without token management
- Teams seeking a fully pre-configured, opinionated authentication solution with minimal setup
- Projects that need built-in, database-backed token revocation without extra dependencies like GuardianDb
- Systems not built on Elixir or not using Plug/Phoenix for web interfaces
Pros & Cons
Pros
Supports any token type implementing the Guardian.Token behaviour, with JWT as default, allowing custom claims and tamper-proof payloads for diverse use cases.
Enables multiple token types and settings within a single application, such as defining different TTLs for access and refresh tokens via token_ttl configuration.
Offers options from simple strings to JWK structures and runtime secret fetching, facilitating secure key rotation and dynamic secret handling as shown in the key server example.
Integrates seamlessly with Plug for web authentication and supports custom pipelines, making it adaptable to complex flows beyond standard endpoints, including channels and sockets.
Cons
By default, JWT tokens are not tracked; effective revocation requires additional libraries like GuardianDb, adding complexity and dependencies.
Requires implementing callbacks like subject_for_token and resource_from_claims, plus configuring pipelines and error handlers, which can be time-consuming compared to drop-in solutions.
Some components, such as the VerifyCookie plug, are marked deprecated, indicating potential breaking changes and maintenance challenges in future updates.
Frequently Asked Questions
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.