leptos_oidc2

This crate is a community-maintained fork of leptos_oidc, which is no longer actively maintained. All credits go to the original authors.

Maintained by @nopeNoshishi. Bug reports and pull requests are welcome at GitHub.

leptos_oidc2 is a utility library for handling OpenID Connect (OIDC) authentication within the Leptos framework. It simplifies the integration of OIDC authentication flows with Leptos-based applications, making it easier to manage user authentication and tokens.

Table of Contents

• leptos_oidc2
  • Table of Contents
  • Leptos compatibility
  • Features
    • Missing Features
    • Tested Backends with Example
  • Installation
    • Crypto backend
  • Usage
    • Initialization and Example
    • Generating Login and Logout URLs
    • Conditional Rendering Components
    • Refreshing Access Tokens
  • License

Leptos compatibility

Features

leptos_oidc2 offers the following features:

• Initialization of the OIDC authentication process.
• Generation of login and logout URLs for redirecting users to OIDC providers (e.g., Keycloak).
• Conditional rendering of components based on the authentication state.
• Refreshing access tokens and storing them in local storage.
• Working with client and server side rendering
• Automatically refresh the access token in the background.
• PKCE challenge

Missing Features

• Make refresh token optional
• Some minor code refactoring/cleanup

Tested Backends with Example

leptos_oidc2 was tested with various backends. This doesn't mean that other backends are not supported. Every backend which supports oidc should work. But feel free to ask for advice or give feedback!

Tested backends:

• KeyCloak
• rauthy

You can find a setup guide for the backends under docs/backends.

Installation

To use leptos_oidc2 in your Leptos-based application, add it as a dependency in your Cargo.toml file:

[dependencies]
leptos_oidc2 = "0.10"

Note: This needs at least leptos v0.8.

Crypto backend

leptos_oidc2 uses jsonwebtoken for JWT handling and exposes its crypto backend as a feature flag. Exactly one backend must be enabled at a time.

The default (rust_crypto) works on all platforms without additional system dependencies.

Note: Exactly one backend must be enabled. If you set default-features = false for any reason, you must explicitly add a backend feature — otherwise the crate will fail to compile.

To use rust_crypto explicitly (e.g. when disabling default features for other reasons):

[dependencies]
leptos_oidc2 = { version = "0.10", default-features = false, features = ["rust_crypto"] }

To switch to the AWS LC backend:

[dependencies]
leptos_oidc2 = { version = "0.10", default-features = false, features = ["aws_lc_rs"] }

Usage

Initialization and Example

To get started with OIDC authentication, initialize the library with the required authentication parameters. You can use the AuthParameters struct to specify the OIDC endpoints, client ID, redirect URIs, and other relevant information.

Please make sure that the issuer url is the base url without the /.well-known/openid-configuration and without a trailing slash. A simple example may be found here.

Note: Please keep in mind that the Auth::init needs to be inside a Router. The internal state is using use_query and use_navigate, which is only available inside a Router.

Generating Login and Logout URLs

leptos_oidc2 provides functions to generate login and logout URLs for your application. These URLs are used to redirect users to the OIDC provider for authentication and logout. They are available once the authentication is initialized.

use leptos::prelude::*;
use leptos_oidc2::Auth;

#[component]
fn MyComponent() {
    let auth = expect_context::<AuthSignal>();

    // Generate the login URL to initiate the authentication process.
    let login_url = move || {
        auth.with(|auth| {
            auth
                .unauthenticated()
                .map(|unauthenticated| unauthenticated.login_url())
        })
    };

  // Generate the logout URL for logging out the user.
    let logout_url = move || {
        auth.get()
            .authenticated()
            .map(|authenticated| authenticated.logout_url())
    };
}

Conditional Rendering Components

The library includes transparent components to conditionally render content based on the authentication state. These components simplify the user interface when dealing with authenticated and unauthenticated users.

use leptos::prelude::*;
use leptos_oidc2::Auth;

#[component]
fn MyComponent() {

    view! {
        // Generate Sign In link
        <LoginLink class="optional-class-attributes">Sign in</LoginLink>

        // Generate Sign Out link
        <LogoutLink class="optional-class-attributes">Sign Out</LogoutLink>

        <AuthLoaded>"This will be rendered only when the auth library is not loading anymore"</AuthLoaded>

        <AuthLoading>"This will be rendered only when the auth library is still loading"</AuthLoading>

        <Authenticated>"This will only be rendered if the user is authenticated"</Authenticated>

        <AuthErrorContext>"This will only be rendered if there was an error during authentication"</AuthErrorContext>

        // A more complex example with optional fallbacks for the loading and unauthenticated state
        <Authenticated
            unauthenticated=move || view! { "this will only be rendered if the user is unauthenticated" }
            loading=move || view! { "this will only be rendered if the library is still loading" }
            >
                "This will only be rendered if the user is authenticated"
        </Authenticated>
    }
}

Refreshing Access Tokens

This library is now capable of refreshing the access_token in the background.

License

leptos_oidc2 is distributed under the MIT License. For more information, see the LICENSE file.