Struct kvarn_auth::Builder

pub struct Builder { /* private fields */ }

You can use multiple authentication setups on a single site, but make sure that the respective Builder::with_cookie_paths do not overlap. You MUST set with_cookie_path to use more than 1 auth setup.

Implementations

impl Builder

pub fn new() -> Self

Create a new builder. Use Self::build or Self::build_validate to get a Config.

pub fn with_auth_page_name(self, auth_page_name: impl Into<String>) -> Self

Sets the URL endpoint where your frontend authenticates to.

pub fn with_lax_samesite(self) -> Self

Decrease security and protection against CSRF but allow users to follow links to auth-protected pages from other sites. This sets the SameSite property of the cookie to lax.

pub fn with_relaxed_httponly(self) -> Self

Decrease security and protection against XSS but allow the JavaScript to read the cookie, which allows the client to get the logged in status. It’s highly recommended to enable Builder::with_force_relog_on_ip_change when this is enabled, as that negates any credential theft, as the credentials are bound to an IP.

This disables the usual setting of the HttpOnly cookie property. This does not affect the credentials cookie. That will never be served without HttpOnly.

pub fn with_force_relog_on_ip_change(self) -> Self

Forces relogging by the user when they change IPs. This can protect users from getting their cookies scraped by malware, as the authentication is IP dependant.

pub fn with_jwt_cookie_name(self, jwt_cookie_name: impl Into<String>) -> Self

Sets the name of the JWT cookie. This is the cookie that authorizes the user.

Panics

Panics if jwt_cookie_name contains illegal bytes for a header value.

pub fn with_credentials_cookie_name(
    self,
    credentials_cookie_name: impl Into<String>
) -> Self

Sets the name of the credentials cookie. This is the cookie that stores the user’s credentials to allow renewal of the JWT cookie without requiring the user to input credentials. It is encrypted with the server’s PK.

Panics

Panics if credentials_cookie_name contains illegal bytes for a header value.

pub fn with_cookie_path(self, cookie_path: impl Into<String>) -> Self

Sets the path of all the cookies. Set this to avoid slowing down other pages on your server, as Kvarn will try to renew the JWT on every page by default. By setting this to only your protected pages, the JWT cookie is only sent there. Kvarn thinks the user isn’t logged in on other pages, reducing the work it has to do.

This is also useful if you want to have multiple authentication systems on a single host.

Panics

Panics if cookie_path contains illegal bytes for a header value.

pub fn with_show_auth_page_when_unauthorized(
    self,
    auth_page: impl Into<String>
) -> Self

Show this page when the user isn’t logged in.

This guarantees nobody can view any pages which starts with Self::with_cookie_path without being logged in.

Please also specify Self::with_cookie_path, as else auth_page will be shown instead of every other page when not logged in.

Panics

Panics if show_auth_page_when_unauthorized cannot be converted into a kvarn::prelude::HeaderValue. kvarn::prelude::Uri.

pub fn with_jwt_validity(self, valid_for: Duration) -> Self

Makes all JWTs valid for the duration of valid_for. After that, the JWT is automatically refreshed from the securely stored credentials.

pub fn with_credentials_cookie_validity(self, valid_for: Duration) -> Self

Makes the credentials cookie valid for the duration of valid_for. If this is a year, the user doesn’t have to relog in a year.

pub fn build<T: Serialize + DeserializeOwned + Send + Sync, F: Fn(&str, &str, SocketAddr, &FatRequest) -> Fut + Send + Sync, Fut: Future<Output = Validation<T>> + Send + Sync>(
    self,
    is_allowed: F,
    pk: CryptoAlgo
) -> Arc<Config<T, F, Fut>>

Build these settings into a Config, which you then use for validation.

pub fn build_validate(
    self,
    validation_key: ValidationAlgo
) -> Arc<Config<(), fn(_: &str, _: &str, _: SocketAddr, _: &FatRequest) -> Pending<Validation<()>>, Pending<Validation<()>>>>

Available on crate features rsa or ecdsa only.

Build these settings into a Config built for validation. See the module-level documentation for more info.

Trait Implementations

impl Debug for Builder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Builder

fn default() -> Builder

Returns the “default value” for a type.